Описания, которые работают
Пока инструментов три, коротких WHEN TO USE и WHEN NOT TO USE хватает
с запасом. Добавьте четвёртый, пятый, потом субагентов - и в один
прекрасный день агент полезет в bash там, где хватило бы
read, хотя вы вообще ничего не меняли. Просто выбор стал
сложнее, а подсказок осталось столько же. Лечится всё тем же местом:
описаниями. Только теперь мы превратим их из вольного пересказа
в жёсткий контракт, одинаковый у всех инструментов.
read, grep и bash заметно
стабильнее, а вы получите шаблон для всех будущих инструментов.
Слова, которые встретятся
- Контракт описания - фиксированный шаблон текста, по которому написаны все инструменты. Когда они оформлены одинаково, модели заметно проще их сравнивать между собой.
- Мягкий запрет (WHEN NOT TO USE) - подсказка в стиле «в этой ситуации возьми лучше вот тот инструмент».
- Жёсткий запрет (DO NOT USE FOR) - «этим задачу X не решают, вообще никогда». Да, похоже на мягкий запрет, и это не случайность: важное модели приходится говорить дважды.
- Bash gravity - та самая тяга модели к терминалу, будто это швейцарский нож на все случаи жизни. Отговаривать её мы будем вежливо, но очень настойчиво.
Быстрый путь
- Расширьте docstring каждого tool до пяти секций.
- Добавьте USAGE (ограничения параметров) и EXAMPLES (конкретные вызовы).
- Оставьте оба негатива: WHEN NOT TO USE и DO NOT USE FOR.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
main.py |
Править. Docstrings у read, grep и bash - полный контракт из пяти секций. |
| логика tools | Не трогать. Меняем только описания, не код внутри функций. |
Упражнение 2.1
Приведите описания read, grep и bash к полному контракту.
- Первая строка - что делает tool и что возвращает.
- WHEN TO USE - 2-4 сценария словами из реальных промптов.
- WHEN NOT TO USE - мягко указать другой инструмент по имени.
- DO NOT USE FOR - жёсткие границы («никогда не для поиска / не для cat»).
- USAGE - лимиты, дефолты, то, чего не видно из типов аргументов.
- EXAMPLES - 2-3 конкретных набора аргументов.
Зачем два «не делай так»
Первое, что бросается в глаза: WHEN NOT TO USE и DO NOT USE FOR говорят
почти одно и то же. Так и есть, дублирование здесь сознательное. Под
нагрузкой, когда промпт размытый а инструментов много, модель прекрасно
«забывает» мягкий намёк и опять тянется к bash. Второй запрет
работает как ремень безопасности: сказали один раз - может проскочить,
сказали дважды - почти всегда держится.
Полный контракт на примере
Начнём с grep: у него больше всего шансов быть перепутанным
с остальными. Обратите внимание, что код функции мы не трогаем вообще,
меняется только текст в тройных кавычках.
docstring для grep
"""Поиск по содержимому файлов через regex. Строки с путями к файлам.
WHEN TO USE: паттерны по многим файлам, определения функций,
импорты, TODO, сообщения об ошибках.
WHEN NOT TO USE: чтение уже известного файла (используй read).
Запуск команд (используй bash).
DO NOT USE FOR: чтение файлов (read), список каталогов (bash),
правка файлов (edit / write - появятся позже).
USAGE: pattern - строка regex. glob - маска вроде "*.py".
Результат обрезается на 50 совпадениях.
EXAMPLES:
- TODO: pattern "TODO" glob "*.py"
- определения функций: pattern "def \\w+" glob "*.py"
- импорт пакета: pattern "from pydantic_ai" glob "*.py"
"""
docstring для read
"""Прочитать файл проекта. Возвращает пронумерованные строки.
WHEN TO USE: просмотр содержимого, конфигов, исходников,
кусок файла через offset/limit.
WHEN NOT TO USE: поиск по многим файлам (используй grep).
Запуск команд (используй bash).
DO NOT USE FOR: поиск по коду (grep), выполнение в shell (bash),
изменение файлов (edit / write).
USAGE: path - относительно рабочей директории.
offset и limit необязательны. Вывод не больше 500 строк.
"""
docstring для bash
"""Выполнить shell-команду в рабочей директории.
WHEN TO USE: сборка, установка пакетов, тесты, git, список файлов.
WHEN NOT TO USE: чтение файла (используй read).
Поиск по паттерну (используй grep).
DO NOT USE FOR: чтение файлов (read), поиск по коду (grep).
USAGE: command - одна строка shell. Команды вне белого списка
блокируются и возвращают понятное сообщение.
EXAMPLES:
- список файлов: command "ls -la"
- статус git: command "git status"
- тесты: command "pytest" # если добавите в белый список
"""
| Секция | Зачем |
|---|---|
| Первая строка | Что делает и что отдаёт |
| WHEN TO USE | Сценарии и слова из промптов пользователя |
| WHEN NOT TO USE | Мягкий редирект на другой tool |
| DO NOT USE FOR | Жёсткая граница, повтор |
| USAGE | Лимиты и дефолты, которых нет в типах |
| EXAMPLES | Конкретные вызовы «скопируй как образец» |
Да, описания заметно распухли, и это нормально. Они уезжают к модели вместе с системными инструкциями, то есть вы платите за них токенами один раз на запуск, а не на каждый чих логики. Взамен получаете предсказуемый выбор инструмента, что в разы дешевле, чем разбираться, почему агент опять полез в терминал.
Проверьте
По одному промпту на каждый «характер» инструмента:
uv run python main.py . "Найди все TODO-комментарии в проекте"
uv run python main.py . "Прочитай pyproject.toml"
uv run python main.py . "Перечисли файлы в этой директории"
Ждём такого расклада: TODO уходит в grep, файл в
read, а список каталога в bash с
ls. Отдельная история - смешанные фразы вроде «покажи
содержимое pyproject через cat»: они честно могут уйти и в
read, и в bash. Это не баг маршрутизации,
а размытый промпт, в котором вы сами назвали два разных способа.
Готово, если:
- У всех трёх tools есть все пять секций описания
- Поиск TODO уходит в
grep - Чтение файла уходит в
read - Список файлов уходит в
bash - (бонус) Убрали EXAMPLES - и поймали, где маршрутизация впервые ломается