раздел 02

Параметры и возврат

У инструмента есть вход (параметры, которые агент подставляет) и выход (то, что инструмент возвращает). Оба влияют на то, насколько точно работает агент.

Параметры: каждый аргумент должен быть понятен

Параметр - это аргумент функции: что именно агент передаёт внутрь. Например, у поиска заказов параметр - это поисковый запрос. У каждого параметра задайте:

Понятное имя
query, а не q. customer_email, а не arg1. Агент подставляет по смыслу имени.
Описание
Одна фраза: что это и в каком формате. Например, дата в виде YYYY-MM-DD.
Тип
Строка, число, дата, список. Тип отсекает половину ошибок с аргументами.
Дефолт
Разумное значение по умолчанию, чтобы агент не обязан был заполнять всё.

Чем однозначнее описан параметр, тем меньше агент промахивается. Если у параметра есть несколько допустимых значений - перечислите их и дайте пример.

Пример описания инструмента целиком

Так выглядит инструмент с хорошо описанными параметрами:

search_orders
  Описание: Ищет заказы клиента. Используй для вопросов про
  статус и состав заказа. Не используй для создания заказа.

  Параметры:
    query   (строка, обязательный)
            Имя, email или телефон клиента.
            Пример: "ivan@mail.ru"
    status  (строка, необязательный, по умолчанию "any")
            Фильтр по статусу. Допустимо: new, paid, shipped, any.
    limit   (число, необязательный, по умолчанию 10)
            Сколько заказов вернуть, максимум 50.

Здесь агент видит формат каждого аргумента, допустимые значения и дефолты. Ошибиться почти негде.

Возврат: чисто и по делу

Возврат - это то, что инструмент отдаёт обратно агенту. И вот здесь вайб-кодеры часто промахиваются: возвращают всё подряд, как отдала база данных или внешний сервис.

Всё, что инструмент вернул, попадает в контекст агента и занимает там место. Мусор в ответе - это потраченная память и деньги, плюс агент отвлекается на лишнее.

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

Большие ответы - обрезать и пагинировать

Если инструмент может вернуть тысячу заказов, не вываливайте их все. Это забьёт контекст и замедлит агента. Два приёма:

  • Обрезка: вернуть первые N результатов и пометить, что есть ещё.
  • Пагинация: вернуть страницу результатов плюс способ запросить следующую.

Коротко

  • У каждого параметра: понятное имя, описание, тип, дефолт, пример.
  • Возврат - только то, что нужно агенту, без служебного мусора.
  • Большие ответы обрезайте или пагинируйте.