Описываем инструменты так, чтобы Claude их понял
Ты подключил Claude к своему API, описал три инструмента, запустил — и видишь странное поведение: иногда модель вызывает не тот инструмент, иногда передаёт параметры в неправильном формате, иногда вообще игнорирует инструмент и пытается ответить «из головы». Менять модель бесполезно — проблема в описании. Claude не видит код твоих функций, он видит ТОЛЬКО JSON-схемы, которые ты ему отдал. Качество описаний ≈ качество агента.
Из чего состоит описание инструмента
Каждый tool это объект с тремя полями: name (имя функции, без пробелов), description (текстовое объяснение что делает), input_schema (JSON Schema параметров). Имя — короткое и говорящее: search_web лучше чем sw, get_user_orders лучше чем getuserorders. Description — главный канал коммуникации с моделью: чем подробнее тем лучше, можно несколько предложений, можно с примерами когда вызывать а когда нет. input_schema — стандартный JSON Schema: type, properties, required. Каждое поле properties тоже имеет свой description — они тоже важны.
Description — пиши как для нового сотрудника
Представь что описание читает человек который только что пришёл в команду и не знает контекста. Что делает инструмент? Что возвращает? Когда его стоит звать а когда не стоит? Какие limitations? Плохой description: "поиск". Хороший description: "Ищет в интернете по строке запроса, возвращает первые 10 результатов с заголовком, URL и сниппетом. Используй когда нужна свежая информация (новости, цены, погода). НЕ используй для перевода или объяснения концепций — для этого ответь сам". Видишь разницу? Второй описывает не только функцию, но и ПОЛИТИКУ когда её применять. Это сильно сокращает ошибочные вызовы.
Параметры — каждое поле тоже описано
Распространённая ошибка: написать description для самого инструмента и забыть про поля. Если у тебя поле "type": "string" без description — модель сама придумывает что туда класть. Правильно: каждое поле в properties имеет свой description, идеально с примером. "city": { "type": "string", "description": "Название города на русском или английском, например Москва или Moscow" }. Используй enum для перечислений вместо свободного текста: "level": { "type": "string", "enum": ["beginner", "advanced"] } — модель НЕ ошибётся в значении.
Required — что обязательно
Поле required в schema — это НЕ просто валидация. Это сигнал модели «без этого нельзя». Если в required лежит "user_id", а пользователь не давал ID — Claude поймёт что нужно сначала уточнить или поискать. Если поле НЕ в required и без него можно — модель его пропустит. Не клади в required то без чего на самом деле можно — иначе модель будет зря допрашивать пользователя. Не забывай в required то что критично — иначе модель сама придумает значение.
Частые ошибки — чек-лист
Что я регулярно вижу в чужих агентах: (1) Описание в три слова — модель путает похожие инструменты. (2) Поля без description — модель придумывает значения. (3) Слишком много инструментов (15+) — модель теряется, разбей на тематические группы и подключай только нужные. (4) Перекрывающиеся инструменты — два tool делают похожее, модель выбирает неправильный. Сделай один с параметром mode. (5) Возврат сложного объекта без описания формата — модель не знает что взять. Всегда возвращай JSON и описывай его структуру в description инструмента.
// ❌ Плохо
const badTool = {
name: 'search',
description: 'поиск',
input_schema: {
type: 'object',
properties: { q: { type: 'string' } },
required: ['q'],
},
};
// ✅ Хорошо
const goodTool = {
name: 'search_web',
description: `Ищет в интернете по запросу пользователя.
Используй когда:
- Нужна свежая информация (новости, цены, погода, события)
- Нужны факты которых может не быть в твоём обучающем наборе
НЕ используй для:
- Объяснений концепций (отвечай сам)
- Перевода (отвечай сам)
- Математики (отвечай сам)
Возвращает JSON: { results: [{ title, url, snippet }] }, до 10 результатов.`,
input_schema: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'Поисковый запрос на естественном языке. Пример: "курс доллара к рублю на сегодня"',
},
lang: {
type: 'string',
enum: ['ru', 'en'],
description: 'Язык результатов. По умолчанию ru.',
},
},
required: ['query'],
},
};Плохой и хороший вариант описания одного инструмента