Модель не видит код твоего сервера. Всё, на что она опирается, выбирая инструмент, — это имя и описание. Если описание сухое и общее, Claude будет звать инструмент невпопад или не звать вообще. Описание — это и есть интерфейс между моделью и твоим кодом.
Было
name: "task"
description: "Работа с задачами."
Что здесь не так? «Работа с задачами» — это создать, найти, закрыть, удалить? Модель не понимает границ. При двух-трёх похожих инструментах она начнёт путаться, какой звать.
Стало
name: "find_task"
description: "Найти ОДНУ задачу в трекере по её номеру и вернуть \
заголовок, статус и исполнителя. Использовать, когда пользователь \
называет конкретный номер задачи. НЕ создаёт и не меняет задачи."
input_schema:
number: integer # номер задачи, например 412
Что делает описание хорошим
- Одно действие — один инструмент.
find_taskищет, и только. Создание — отдельный инструмент со своим именем. - Сказано, КОГДА звать. «когда пользователь называет конкретный номер» — это подсказка модели, как выбрать.
- Сказано, чего инструмент НЕ делает. Явные границы спасают от ложных вызовов.
- Описаны входы. В схеме и в комментарии видно, что нужен номер, и приведён пример.
Пиши описание так, будто объясняешь новому сотруднику, который видит только эту строчку и больше ничего о системе не знает. Если ему было бы непонятно — модели тоже.
Хорошее описание — это не украшение. Это то, от чего напрямую зависит, попадёт ли Claude в нужный инструмент с первого раза.