Tool descriptions: что писать чтобы агент вызывал правильно

Напиши description для tool {{tool_name}} ({{tool_purpose}}). Description — это prompt в prompt'е: агент решает, когда звать tool, только на его основе. Плохое description = неправильные вызовы или невызовы.

1. Структура хорошего description

Пять блоков, в этом порядке:

1. Purpose (1 фраза): что делает, в активном залоге
2. When to use: 2-4 конкретных триггера
3. When NOT to use: 2-3 anti-trigger'а (что НЕ делает / когда есть лучший tool)
4. Edges & limits: rate limits, размер, idempotency, side effects
5. Example call: 1-2 минимальных примера inputs

Длина: 5-12 строк. Длиннее — модель не дочитает. Короче — не хватит сигнала.

2. Шаблон (заполни под {{tool_name}})

{{tool_name}}: [одна фраза в активном залоге, без "helps to" / "can be used to"]

When to use:
- [конкретный триггер 1: что в задаче должно быть]
- [конкретный триггер 2]
- [триггер 3, если есть]

When NOT to use:
- [случай где другой tool лучше — назови tool]
- [случай где tool не подходит вовсе]

Limits & edges:
- [rate-limit / quota если есть]
- [max input size]
- [side effects: "creates a file", "makes irreversible change"]
- [idempotency: safe to retry / not safe]

Example:
{ "param_a": "...", "param_b": "..." }   // [что вернёт]

3. Good vs bad: примеры

Bad (vague)

search_files: Helps the user search through files.

Проблемы:

• "helps" — мета-описание, бесполезно
• Нет триггеров — модель не знает когда звать
• Нет limits — стрельнёт по 100k файлов
• Нет contrast с другими tools (Grep? Find? Read?)

Good (specific)

search_files: Search file contents by regex. Returns list of (path, line, snippet).

When to use:
- Looking for a string or pattern across the codebase
- Don't know which file contains the symbol
- Need to count occurrences

When NOT to use:
- You know the file path already → use Read
- Searching by filename only → use Find
- Result will be > 200 matches → narrow the query first

Limits:
- Max 200 results returned
- Read-only (no side effects, safe to retry)
- Skips .git, node_modules by default

Example:
{ "pattern": "useAuth\\(", "path": "src/" }

Bad (overlapping / unclear contrast)

update_record: Updates a record in the database.
edit_record:   Edits a record in the database.

Модель будет рандомно выбирать. Сделай явное различие или объедини.

4. Common mistakes

5. Когда дробить tool на два

Если description начинает звучать как:

"Use it for X. But also for Y. Unless Z, then use mode='advanced'."

— ты должен дробить. Один tool = одно concise назначение. Modes/flags для одного tool = больше непредсказуемости в вызовах.

6. Тестирование description

1. Возьми 10 реальных задач из логов
2. Спроси модель (без доступа к коду) только по description'у: "Какой tool позвать для задачи X?"
3. Если ≥ 8/10 правильных — description работает
4. Если ≤ 5 — переписывай, конкретизируй when-to-use

7. Параметры — это часть description

Не описывай схему JSON отдельно. Каждый param должен иметь:

• type
• 1 строку purpose
• example value
• required vs optional явно

{
  "pattern":   { "type": "string", "required": true, "desc": "regex pattern (PCRE)", "example": "user_\\d+" },
  "path":      { "type": "string", "required": false, "desc": "subdir to scope search (default: cwd)", "example": "src/" }
}

8. Anti-patterns

• ❌ Description с "helps to" / "can be used to" / "this tool is for" — мета-вода, тратит токены
• ❌ Нет when-NOT блока — tool вызывается не по назначению
• ❌ Описание реализации ("calls internal API X") — модели всё равно, что внутри
• ❌ Два tools с почти одинаковыми descriptions — модель путается, выбор случайный
• ❌ Нет side-effects warning — модель "пробует" rm/drop/delete
• ❌ Нет example call — модель импровизирует параметры, схема падает на validation
• ❌ Description > 15 строк — конец не дочитается, важное в хвосте теряется
• ❌ Жаргон / acronyms без расшифровки — модель угадывает
• ❌ Скрытые предусловия ("должен быть вызван после X") — модель вызывает без X, фейл
• ❌ Описывать через примеры использования вместо чёткого purpose — "вот сценарии" не работает как trigger
• ❌ Один большой tool с 10 mode-флагами вместо 3 узких tools — модель путается в mode

Deliverable

• Description для {{tool_name}} по шаблону §2
• Параметры с описанием и examples
• 3 good / 3 bad варианта на сравнение
• Тест на 10 задачах с метрикой recall@1