Устранение неполадок при использовании инструментов

Исправьте наиболее распространённые ошибки при использовании инструментов с помощью диагностических таблиц симптомов и решений.

Таблицы симптомов и решений для наиболее распространённых ошибок при использовании инструментов. Каждое решение содержит ссылку на страницу, которая описывает эту функцию.

Claude вызывает неправильный инструмент

Симптом	Вероятная причина	Решение
Claude вызывает инструмент A, когда вы хотели инструмент B	Неоднозначность описания	Уточните описания. Различайте инструменты по КОГДА их использовать, а не только ЧТО они делают. См. Define tools.
Claude никогда не вызывает ваш инструмент	Конфликт имён инструментов или слишком общая схема	Проверьте наличие дублирующихся имён в списке инструментов. Добавьте `input_examples` для конкретизации предполагаемого использования.
Claude вызывает с неправильными типами параметров	Модель угадывает неоднозначную схему	Добавьте `strict: true` (если ваша схема входит в поддерживаемое подмножество) или добавьте `input_examples`.

Claude придумывает параметры инструментов

Симптом	Вероятная причина	Решение
Параметр, который не существует в вашей схеме	Чрезмерная генерация моделью без режима strict	Добавьте `strict: true`, если ваша схема входит в поддерживаемое подмножество.
Значения параметров вне вашего перечисления	Отсутствие режима strict или слишком большое перечисление	Уменьшите перечисление или добавьте `input_examples`, показывающие допустимые варианты.

Параллельные вызовы инструментов не работают

Симптом	Вероятная причина	Решение
Claude вызывает инструменты последовательно, когда параллельный вызов был бы лучше	Форматирование истории сообщений	Отправьте несколько блоков `tool_result` в ОДНОМ сообщении пользователя, а не по одному за ход. См. Parallel tool use.
`disable_parallel_tool_use` кажется игнорируемым	Установлено слишком поздно в разговоре	Должно быть установлено в запросе, который возвращает `tool_use`. Установка его в более позднем запросе не влияет на более ранние вызовы инструментов.

Кэш постоянно инвалидируется

Симптом	Вероятная причина	Решение
Каждый запрос — это кэш-промах	`tool_choice` варьируется между запросами	Сохраняйте `tool_choice` стабильным или поместите точку разрыва `cache_control` перед точкой вариации. См. Tool use with prompt caching.
Добавление инструмента в середине разговора нарушает кэш	Инструмент добавлен в начало массива инструментов	Используйте `defer_loading: true` с поиском инструментов, чтобы добавить инструмент встроенным образом вместо изменения начала массива.

Ошибки во время запроса

Ошибка	Причина	Решение
`tool_use ids were found without tool_result blocks immediately after`	Отсутствует `tool_result` для некоторых `tool_use` ids, или `tool_result` не является первым блоком содержимого в сообщении пользователя	Верните один `tool_result` для каждого блока `tool_use` в ответе ассистента. Поместите блоки `tool_result` перед любым текстом. См. Handle tool calls и Parallel tool use.
`Input schema is not compatible with strict mode: string patterns are not supported`	Использование `pattern` с `strict: true`	Удалите pattern или отключите `strict: true`. Ключевое слово `pattern` ещё не входит в поддерживаемое подмножество JSON Schema.
`All tools have defer_loading: true`	Модель не видит инструменты	По крайней мере один инструмент должен быть немедленно загружен. Сам инструмент поиска инструментов никогда не должен иметь `defer_loading: true`.

Различия в экранировании JSON (Opus 4.6+)

Симптом	Причина	Решение
Сравнение строк на входах инструментов не работает с более новыми моделями	Экранирование Unicode и прямой косой черты отличается между версиями моделей	Парсируйте с помощью `json.loads()` или `JSON.parse()`. Никогда не выполняйте прямое сравнение строк на сериализованном входе.

Следующие шаги

Define tools

Напишите схемы и описания, которые направляют Claude на правильный инструмент.

Handle tool calls

Выполняйте инструменты и возвращайте результаты в требуемом формате сообщения.

Tool reference

Полный каталог инструментов Anthropic-schema и их строк версий.

Was this page helpful?

РазработкаИнструменты