Claude Tools: как работают инструменты в API и что выбрать

Claude Tools это механизм Claude API, который позволяет модели запросить внешнее действие в структурированном виде. Для своего инструмента Claude формирует блок tool_use, ваше приложение проверяет аргументы и выполняет функцию, затем возвращает tool_result. Серверные инструменты Anthropic выполняются на стороне платформы. Начинать безопаснее с одной операции чтения и явной проверки результата.

Что именно называется инструментом Claude

Инструмент не является скрытой способностью модели. Это договор между приложением и Claude: вы описываете доступную операцию и форму входных данных, а модель решает, когда запросить вызов. В официальном объяснении Anthropic прямо указано, что модель сама не выполняет пользовательский код. Она возвращает структурированный запрос, после чего код запускает ваше приложение.

Три типа инструментов и правило выбора

Главный вопрос выбора: где должен выполняться код и кто отвечает за последствия. Документация Anthropic по tool use разделяет пользовательские клиентские инструменты, клиентские инструменты со схемой Anthropic и серверные инструменты платформы. У каждой группы разная зона ответственности.

• Пользовательский клиентский инструмент: вы задаёте схему, выполняете код и возвращаете результат. Подходит для собственной базы, CRM или внутреннего API.
• Клиентский инструмент со схемой Anthropic: схема подготовлена Anthropic, но выполнение и контроль остаются в вашем приложении.
• Серверный инструмент: Anthropic выполняет операцию на своей инфраструктуре. Подходит, когда нужная возможность официально предоставляется платформой.
• Обычный ответ без инструмента: выбирайте его для стабильного знания, редактуры и рассуждения, которым не нужны внешние данные или действие.

Чем опаснее действие, тем меньше должна быть область инструмента. Функция чтения статуса безопаснее универсальной функции, которая умеет менять всё.

Карта результата до подключения

До написания схемы зафиксируйте исходную ситуацию. Например, пользователю нужно узнать статус заказа, данные доступны по внутреннему API, а изменение заказа запрещено. Ожидаемый результат: один статус для одного номера заказа с отметкой времени. Проверка: номер в ответе совпадает с входом, статус взят из API, запись не изменилась.

1. Назовите одно действие инструмента глаголом: получить, найти, создать или отменить.
2. Определите минимальные входные поля и допустимые значения.
3. Запишите, где выполняется код и какими правами он обладает.
4. Укажите проверяемый результат и формат ошибки.
5. Разделите чтение и изменение на разные инструменты.
6. Для изменения добавьте подтверждение, повторяемый идентификатор операции и журнал.
7. Подготовьте обычный тест, тест с пропущенным параметром и тест с запрещённым значением.

По теме: Как проверять ответы ИИ-агента: доказательства и повторяемость

Как устроен цикл tool_use и tool_result

Клиентский цикл состоит из двух запросов или большего числа повторений. Приложение отправляет сообщения и массив tools. Claude может ответить с stop_reason равным tool_use и блоком с именем инструмента и JSON-аргументами. Приложение валидирует данные, выполняет функцию и отправляет результат обратно. Цикл завершается, когда модель возвращает финальный ответ или другой ожидаемый повод остановки. Эта последовательность описана в официальной схеме Anthropic.

1. Приложение -> Claude: messages + tools
2. Claude -> приложение: stop_reason=tool_use + аргументы
3. Приложение: проверка аргументов и выполнение функции
4. Приложение -> Claude: tool_result
5. Claude -> приложение: финальный ответ или следующий вызов

Не исполняйте аргументы сразу после получения. Сначала проверьте типы, обязательные поля, права пользователя и допустимую область действия. JSON-схема ограничивает форму, но не решает бизнес-правила. Даже корректный номер заказа может принадлежать другому пользователю.

Как описать безопасный инструмент

Определение пользовательского инструмента содержит имя, подробное описание и input_schema. Официальная инструкция Anthropic указывает, что описание должно объяснять назначение, условия использования и поведение. В документации также предусмотрен режим strict: true, который требует соответствия вызова схеме. Он полезен для формы данных, но проверка разрешений всё равно остаётся в коде.

{
  "name": "get_order_status",
  "description": "Получить статус одного заказа текущего пользователя. Не изменяет заказ.",
  "input_schema": {
    "type": "object",
    "properties": {"order_id": {"type": "string"}},
    "required": ["order_id"],
    "additionalProperties": false
  },
  "strict": true
}

• Имя описывает одну операцию и не обещает больше, чем делает функция.
• Описание указывает, когда вызывать инструмент и когда не вызывать.
• Схема запрещает лишние поля и ограничивает типы.
• Сервер повторно проверяет пользователя, права и область данных.
• Результат не содержит секреты и лишние персональные данные.
• Ошибка возвращается как ошибка, а не как правдоподобный пустой успех.

Безопасный пример и граничный случай

Инструмент get_order_status только читает одну запись, поэтому его можно тестировать первым. Функцию отмены заказа создайте отдельно. Она должна проверить владельца, допустимый статус, срок отмены и отдельное подтверждение. Не передавайте универсальную функцию manage_order, потому что модели сложнее выбрать безопасный режим, а журнал хуже показывает намерение.

Граничный случай: Claude запросил отмену дважды после сетевого повтора. Сервер должен распознать один идентификатор операции и не выполнить действие повторно. Это свойство называется идемпотентностью. Даже без специального термина правило простое: одинаковый повторный запрос не должен второй раз списывать деньги, отправлять письмо или отменять объект.

Если нужен именно внешний MCP-сервер, сначала сверяйте его полномочия и источник по отдельному руководству по Claude MCP. Подключение протокола не отменяет правила узких прав и проверки результата.

По теме: Работа с ИИ-агентами: задачи, контроль и проверка результата

Как проверить инструмент до реальных данных

1. Запустите корректный пример и проверьте точное совпадение результата с источником.
2. Уберите обязательное поле и убедитесь, что вызов не исполняется.
3. Передайте номер чужого объекта и ожидайте отказ без раскрытия данных.
4. Сымитируйте таймаут и верните явную ошибку, которую Claude не примет за результат.
5. Повторите один запрос дважды и проверьте отсутствие второго побочного эффекта.
6. Просмотрите журнал: в нём должны быть пользователь, инструмент, время, решение и итог без секретов.

Сначала тестируйте инструмент отдельно от модели обычным API-вызовом. Затем проверяйте, правильно ли Claude выбирает инструмент по естественной фразе. Так вы отличите ошибку функции от ошибки выбора. Для общей настройки поведения Claude пригодится разбор настроек и проектов Claude, но API-инструмент требует собственных тестов.

Диагностика по симптому

• Claude не вызывает инструмент: уточните описание, проверьте наличие инструмента в запросе и соответствие задачи его назначению.
• Вызывается не тот инструмент: уберите пересекающиеся функции и разведите описания по одному действию.
• Аргументы не проходят схему: проверьте обязательные поля, типы и режим strict.
• Модель вызывает инструмент по кругу: ограничьте число итераций, возвращайте ясный статус ошибки и задайте условие остановки.
• Ответ содержит старые данные: убедитесь, что функция действительно обращается к источнику, а не возвращает кэш без отметки времени.
• Действие выполнено, но ответ потерян: используйте идентификатор операции и проверку состояния перед повтором.

Для серверных инструментов учитывайте отдельные причины остановки. Документация Anthropic описывает pause_turn для продолжительной серверной работы. Приложение должно обработать этот статус по официальной схеме, а не считать незавершённый ответ успехом.

По теме: Claude-бот в Telegram: схема, шаги и проверка

Когда tool use не подходит

Не подключайте инструмент, если Claude уже имеет все данные в текущем сообщении и нужен только текстовый ответ. Не давайте модели действие, для которого нет проверки прав, журнала и безопасного повтора. Для одноразовой операции с высоким риском ручное выполнение может быть дешевле и надёжнее агентного цикла.

Начинайте с одного инструмента чтения, добейтесь стабильных тестов, затем добавляйте одну возможность за раз. Если сразу подключить десятки похожих функций, станет трудно понять, ошиблась модель, схема или ваш обработчик. Смежные сценарии создания агента разобраны в статье как создать ИИ-агента без кода, но собственный API-контур требует технической реализации.

Частые вопросы

Claude сам выполняет мой инструмент?

Пользовательский клиентский инструмент выполняет ваше приложение. Claude только возвращает структурированный запрос. Серверные инструменты Anthropic выполняются платформой.

Достаточно ли JSON-схемы для безопасности?

Нет. Схема проверяет форму аргументов. Права пользователя, допустимость действия, лимиты и повторные вызовы должен проверять сервер.

Нужно ли принуждать Claude всегда вызывать инструмент?

Только когда вызов обязателен по процессу. В остальных случаях автоматический выбор удобнее, если описания точны и есть тесты на ожидаемое поведение.

Можно ли объединить чтение и изменение в одну функцию?

Технически можно, но безопаснее разделить. Тогда проще ограничить права, запросить подтверждение и увидеть намерение в журнале.