Tool Catalog

Суть

Инструмент, описанный только схемой входа и формой ответа, отдаёт слою выполнения слишком мало. Для опасных операций контракт обязан хранить ещё и то, как с ними обращаться при сбое.

Минимальный состав операционной семантики:

• идемпотентно ли действие;
• нужен ли ключ идемпотентности (Idempotency For Agents);
• какие ошибки допустимы для повтора;
• каков предел повторов;
• какие лимиты на частоту вызова;
• что делать при неизвестном исходе;
• возможен ли откат или компенсирующее действие (Rollback Boundary).

Каталог, где этих полей нет, вынуждает слой выполнения импровизировать в момент отказа — то есть ровно тогда, когда импровизировать хуже всего.

Две оси классификации

Чтение против записи — различие по классу риска, а не по механике вызова:

Смешение их в одну неявную категорию «вызов инструмента» — самый быстрый способ потерять управляемость слоя выполнения.

Роль в системе — вторая, ортогональная ось:

• data tools читают и возвращают контекст: проверить статус, извлечь, прочитать запись;
• action tools меняют внешний мир: создать тикет, отправить письмо, обновить запись;
• orchestration tools обслуживают сам рантайм: запросить подтверждение, сделать передачу, вызвать планировщик.

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

Каталог сообщает не только «что есть», но и «где это безопасно»

Дисциплина, которую легко пропустить: каталог должен делать явным, в каких паттернах оркестрации инструмент безопасно участвовать. Инструмент, приемлемый в детерминированной цепочке с проверкой между шагами, может быть неприемлем внутри автономного цикла, где число вызовов не ограничено заранее (Agent vs Workflow).

Без этого поля выбор паттерна и выбор инструментов делаются независимо, и их несовместимость обнаруживается в проде.

Каталог эволюционирует медленно

Свойство, отличающее каталог от обычного кода: он — публичный интерфейс платформы, и на него завязаны политики, подтверждения и трассы (Tool Gateway, Agent Control Plane). Быстрое изменение состава возможностей ломает не вызывающий код, а накопленные правила и историю расследований.

Отсюда практика: расширять каталог легко, сужать и переименовывать — через процедуру устаревания, как у публичного API (API As Product).

Описание инструмента — это API выбора для модели

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

Рабочая форма — контракт из пяти секций:

Два отрицания подряд выглядят дублированием, и это намеренно. У моделей есть устойчивое тяготение к самому общему инструменту — к выполнению произвольной команды: он умеет всё, и при неуверенности выбирается он. Сказать «этим не ищут» один раз хватает не всегда; сказать дважды — почти всегда.

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

USAGE заслуживает места только там, где у параметра есть ограничение, которое из схемы не выводится: потолок, умолчание, кодировка. Про потолки — Bounded Tool Output: если вывод усечён, это часть контракта, и модель должна узнать об этом из описания, а не из усечённого результата.

Реестр вместо списка: где проходит шов расширения

Пока инструментов семь, они собираются руками в точке входа. Как только кто-то захочет добавить свой инструмент или обернуть существующий проектными правилами, руками собранный список означает форк.

Шов — реестр: register / get / list, плюс тонкая обёртка, оборачивающая существующий инструмент дополнительным поведением до и после вызова. Ядро при этом не меняется, а набор инструментов агента собирается из реестра.

Важно, что это не про удобство, а про то же различие, что и в Orchestrator Adapter: пока точка расширения не названа, расширение делается форком, и дальше две копии расходятся.

Plugin — граница владения, capability — контракт

Реестр отвечает, как подключить реализацию, но не должен протаскивать vendor-specific типы во всех потребителей. Более устойчивый шов разделяет:

• capability — типизированный контракт ядра; ядро владеет политикой, fallback и совместимостью;
• plugin — граница владения конкретной реализацией; vendor-код и его жизненный цикл остаются внутри;
• consumer — канал или функция, зависящие только от capability.

При hot reload принятая работа заканчивает на одной runtime generation, а новая идёт в следующую. Смена реализации посреди запроса создаёт состояние, которого не тестировала ни одна версия. Native plugin, работающий в процессе, при этом не является sandbox: его установка эквивалентна доверию произвольному коду Gateway.

Связано с

• Human in the Loop — второй слой того же контракта: что инструменту позволено без спроса
• Bounded Tool Output — контракт усечения как часть контракта инструмента
• Tool Gateway — что делает с этими полями слой исполнения
• Tool Calling — механика вызова и реестр имён
• Idempotency For Agents — поля повторов в контракте
• Rollback Boundary — поля отката в контракте
• Agent Control Plane — политика, опирающаяся на класс риска из каталога
• MCP — стандарт, которым каталог отдаётся наружу
• Tool Retrieval — как агент находит нужный инструмент в большом каталоге
• Agent vs Workflow — совместимость инструмента с паттерном оркестрации