Описание инструмента — это интерфейс для модели

Короткий ответ: модель не читает ваш код. Она видит только имя инструмента, его описание и схему параметров — и выбирает по ним. Значит описание является интерфейсом, а не комментарием к нему: ошибка в описании проявляется как неверное поведение агента, а не как неудобство чтения.

Симптом узнаваемый: инструмент есть, работает, а агент им не пользуется. Или пользуется там, где не надо. Лезут в промпт и в код, хотя чинить надо строку описания.

Из чего состоит рабочее описание

Разберу на настоящем примере — описании инструмента, который делегирует работу параллельным подагентам:

Delegate one or more self-contained pieces of work to subagents that run in parallel and report back. Use this when the next step splits into parts that do not depend on each other: surveying several areas of the project, checking several hypotheses, reading several unrelated subsystems. Do not use it for a single step you can take yourself, for anything that needs the user’s approval, or for work where one part needs the result of another. Each subagent starts with no memory of this conversation, so its prompt must contain everything it needs.

Четыре части, и каждая делает свою работу.

Что делает. Одно предложение без деталей реализации. Модели не нужно знать, как устроено выполнение, — ей нужно знать результат.

Когда применять, с примерами. Не абстрактное «для параллельных задач», а три конкретных случая. Примеры здесь работают так же, как в промпте: правило считывается из них надёжнее, чем из формулировки.

Когда не применять. Самая недооценённая часть и обычно отсутствующая. Три явных запрета, каждый закрывает конкретный способ ошибиться: взять инструмент для того, что делается одним шагом; попытаться сделать через него то, что требует подтверждения; разбить на части работу, где вторая зависит от первой.

Что должен знать вызывающий. «Подагент не помнит этот разговор» — свойство, которое невозможно вывести из имени и схемы, но без которого модель составит неполный промпт и получит бесполезный результат.

Схема параметров — тоже описание

Поля схемы имеют собственные описания, и они работают ровно так же. В том же примере у поля name написано: «короткая метка задачи, показывается пользователю в ленте, например „слой базы данных”».

Здесь три вещи одновременно: что это, кто это увидит, и пример. Без второго модель напишет служебный идентификатор, без третьего — предложение на строку.

Отдельно стоит отметить приём с ограничением, снятым явно: описание поля tasks говорит, что задач можно передать больше, чем настроенная параллельность, — лишние подождут. Без этой строки модель будет осторожничать и дробить работу на несколько вызовов.

Как проверять

Описание проверяется не чтением, а поведением.

Дать модели список инструментов и задачу, не давая выполнять. Спросить, какой она возьмёт и почему. Ответ показывает, как она поняла описание, — и расхождение видно сразу.

Проверять на задачах, где инструмент НЕ нужен. Половина дефектов — не «не вызвала», а «вызвала лишний раз». Ловится только отрицательными примерами.

Смотреть на аргументы, а не только на выбор. Правильный инструмент с неполными аргументами — это дефект описания полей, и он маскируется под «модель плохо справилась».

Условие несогласия

Если инструментов два-три и они очевидно различны — «прочитать файл» и «записать файл», — вся эта работа избыточна: перепутать их трудно.

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

Чего я делать не стал бы

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

Не стал бы чинить неверный выбор инструмента правилами в системном промпте. Это лечение симптома в другом месте: правило конкурирует с описанием, а описание ближе к точке решения. К тому же системный промпт — это налог на каждый вызов.

Не стал бы оставлять поле без описания, считая имя достаточным. path, target, scope — каждое из них модель поймёт по-своему, и угадает неправильно ровно в том случае, который вы не проверяли.

Открытый вопрос

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

Проверить, какая часть описания реально влияет на выбор, я не умею: убрать предложение и посмотреть — это отдельный прогон набора примеров на каждое предложение. Дёшево для одного инструмента, неподъёмно для пятнадцати.