Как писать tools для агента

Tool — это интерфейс для другого читателя

Tool (инструмент) для агента описывают name (имя), description (описание) и schema (описание параметров с типами). Но хороший tool — больше, чем обёртка над API (программным интерфейсом сервиса). Anthropic называет это ACI (agent-computer interface, интерфейс между агентом и компьютером) и советует вкладывать в него столько же сил, сколько в интерфейс для людей. В статье «Building effective agents» команда признаётся, что на задаче SWE-bench (набор реальных задач по исправлению кода) больше времени ушло на доводку tools, чем на общий prompt (инструкцию для модели).

Читатель tool — модель с ограниченным context (всем, что она видит за один вызов). Она не листает документацию, не помнит прошлых разговоров и платит tokens (кусками слов, единицами длины текста) за каждую строку ответа. Пять принципов из статьи Anthropic «Writing effective tools for agents» (сентябрь 2025) вытекают из этого.

1. Выбрать правильные tools

Не заворачивай каждый endpoint (точку API) в отдельный tool. Пример из статьи: list_contacts, который возвращает всех контактов, заставляет агента читать список целиком; search_contacts возвращает только нужного. Tools можно объединять: один schedule_event находит свободное время и создаёт встречу вместо трёх (list_users, list_events, create_event). Для банка: get_customer_context собирает в одном вызове всё, что нужно для ответа о клиенте, вместо пяти запросов. Правило статьи: у каждого tool — ясная, отдельная цель. Пересекающиеся tools сбивают агента. Обратная крайность тоже опасна: один tool «выполнить любой запрос к базе» удобен, но это лишние функции и лишние права в одном месте, и модель с ним ошибается дороже. Граница tool проходит по одной задаче пользователя: достаточно широко, чтобы не делать пять вызовов подряд, и достаточно узко, чтобы права и проверки были понятны. Меньше хорошо названных tools — ещё и меньше описаний в context.

2. Namespacing: группы по префиксу

Namespacing (пространства имён) — общий префикс у связанных tools: по сервису (asana_search, jira_search) или по ресурсу (asana_projects_search, asana_users_search). Когда у агента десятки серверов и сотни tools, префикс помогает отличить «поиск в картах» от «поиска в платежах», а поиску по tools — находить всю группу одним запросом. Тонкость, которую мало кто знает: в замерах Anthropic префикс против суффикса заметно менял результат, и по-разному на разных моделях. Значит, схему имён выбирают тестом, а не вкусом.

3. Возвращать осмысленный context

Модель лучше работает с понятными словами, чем с загадочными ID. Поля name и file_type полезнее, чем uuid (длинный случайный идентификатор) и mime_type (технический тип файла); по словам Anthropic, замена UUID на понятные имена (или короткие номера с нуля) снизила выдумки при поиске. Но иногда ID нужен для следующего вызова: search_user(name='jane'), потом send_message(id=12345). Решение — параметр response_format с вариантами concise (кратко) и detailed (подробно): агент сам выбирает. В примере статьи подробный ответ занял 206 tokens, краткий — 72.

4. Экономить tokens

Если ответ может быть большим, добавь pagination (выдачу страницами), фильтры, выбор диапазона и truncation (обрезку) с разумными значениями по умолчанию. Для ориентира: Claude Code по умолчанию ограничивает ответ tool 25 000 tokens. При обрезке скажи агенту, что делать дальше: «показаны 50 из 3 400 операций; сузь период или категорию». И ошибки должны вести к исправлению: «date ожидается в формате YYYY-MM-DD, например 2026-10-03» вместо голого кода или traceback (стека вызовов). Такая ошибка экономит целый круг цикла.

5. Писать описания как для нового сотрудника

Описание и schema попадают прямо в context модели, поэтому их правка — один из самых сильных рычагов. Пиши так, будто вводишь в курс нового коллегу: скажи явно то, что тебе кажется очевидным — формат запроса, термины отрасли, связь между ресурсами. Имена параметров однозначные: user_id, а не user. По данным Anthropic, точные правки описаний помогли Claude Sonnet 3.5 выйти на лучший результат своего времени на SWE-bench Verified. Ещё один приём оттуда же, poka-yoke (защита конструкцией): в их агенте модель путалась в относительных путях к файлам, и команда потребовала только абсолютные пути — ошибки ушли.

Пример: переписать плохое описание

Было:

name: get_data
description: get data about client
params: client (string)

Стало:

name: cards_get_status
description: Returns the current status of the signed-in customer's
  cards: masked number (*4417), status (active/blocked/expired),
  block reason, expiry month. Use when the customer asks whether a
  card works, why a payment was declined, or when a card expires.
  Does not change anything. The customer comes from the session.
params: card_last4 (string, 4 digits, optional; omit for all cards)
response_format: concise | detailed (default concise)

Что изменилось: префикс cards_ ставит tool в группу; описание говорит, что возвращает и когда звать; параметра «клиент» нет, он берётся из сессии; краткий ответ по умолчанию бережёт tokens.

Как узнать, что стало лучше

Нельзя на глаз. Порядок из статьи: собрать набор реалистичных задач, где известен верный tool и верный результат; прогнать агента со старым и новым описанием по несколько раз; сравнить долю успеха, число вызовов, tokens и ошибки tool. Часть задач держат отдельно (held-out set, отложенный набор), чтобы не подогнать описания под знакомые примеры. Anthropic даже давала Claude читать traces (журналы шагов) неудачных прогонов и переписывать tools; по их замерам такие tools обошли написанные экспертами вручную. Мерило — набор задач, а не чьё-то мнение.