Tool Search

Когда к сессии подключено много MCP-серверов или инструментов сторонних плагинов, их JSON-схемы могут занимать значительную часть окна контекста на каждом шаге — даже если лишь немногие из них имеют отношение к тому, что на самом деле запросил пользователь.

Tool Search — это опциональный слой прогрессивного раскрытия VibeOS для решения этой проблемы. При активации MCP-инструменты и инструменты плагинов заменяются в массиве инструментов, видимых модели, тремя мостовыми инструментами, и модель загружает схему каждого конкретного инструмента по требованию.

Встроенные инструменты VibeOS никогда не откладываются

Инструменты, составляющие основной набор возможностей VibeOS (terminal, read_file, write_file, patch, search_files, todo, memory, browser_*, web_search, web_extract, clarify, execute_code, delegate_task, session_search, send_message и остальные из _VIBEOS_CORE_TOOLS), всегда загружаются напрямую. Откладыванию подлежат только MCP-инструменты и инструменты сторонних плагинов.

Как это работает

Когда Tool Search активируется для очередного шага, модель видит три новых инструмента вместо отложенных:

tool_search(query, limit?)     — поиск по каталогу отложенных инструментов
tool_describe(name)            — загрузка полной схемы одного инструмента
tool_call(name, arguments)     — вызов отложенного инструмента

Типичное взаимодействие выглядит так:

Модель: tool_search("создать issue в github")
  → { matches: [{ name: "mcp_github_create_issue", ... }, ...] }
Модель: tool_describe("mcp_github_create_issue")
  → { parameters: { type: "object", properties: { ... } } }
Модель: tool_call("mcp_github_create_issue", { title: "...", body: "..." })
  → { ok: true, issue_number: 42 }

Когда модель вызывает tool_call, VibeOS снимает мостовую обёртку и отправляет базовый инструмент точно так же, как если бы модель вызвала его напрямую. Хуки перед вызовом инструмента, ограждения, запросы на подтверждение и хуки после вызова инструмента выполняются для реального имени инструмента — а не для tool_call. Лента активности в CLI и шлюзе также снимает обёртку, чтобы вы видели базовый инструмент, а не мост.

Когда это активируется?

По умолчанию Tool Search работает в режиме auto: он активируется только тогда, когда схемы откладываемых инструментов занимают не менее 10% окна контекста активной модели. Ниже этого порога сборка массива инструментов является чистой передачей без изменений, и вы не несёте никаких накладных расходов.

Это решение пересматривается каждый раз при сборке массива инструментов, поэтому:

• Сессия с несколькими MCP-инструментами и моделью с длинным контекстом никогда не активирует Tool Search.
• Сессия со множеством подключённых MCP-серверов (обычно 15+ инструментов) начинает его активировать.
• Удаление MCP-серверов в середине сессии корректно возвращает к прямому отображению при следующей сборке.

Конфигурация

tools:
  tool_search:
    enabled: auto       # auto (по умолчанию), on или off
    threshold_pct: 10   # процент контекста — используется только в режиме auto
    search_default_limit: 5
    max_search_limit: 20

Ключ	По умолчанию	Значение
enabled	auto	auto активируется выше порога; on активируется всегда, если есть хотя бы один откладываемый инструмент; off полностью отключает.
threshold_pct	10	Процент длины контекста, при котором срабатывает режим auto. Диапазон 0–100.
search_default_limit	5	Количество результатов, возвращаемых при вызове tool_search моделью без указания limit.
max_search_limit	20	Жёсткая верхняя граница, которую модель может запросить через limit. Диапазон 1–50.

Вы также можете использовать устаревшую булеву форму:

tools:
  tool_search: true   # эквивалентно {enabled: auto}

Когда НЕ использовать

Tool Search обменивает фиксированную стоимость токенов за шаг (три схемы мостовых инструментов, ~300 токенов) и как минимум один дополнительный цикл запрос-ответ (поиск → описание → вызов) на экономию от отложенных схем. Это явный выигрыш, когда у вас много инструментов, но вы используете мало за шаг; это накладные расходы, когда инструментов в целом мало.

Режим auto по умолчанию обрабатывает это за вас. Если вы безусловно установите enabled: on, ожидайте небольших затрат на шаг при небольших наборах инструментов.

Компромиссы, которые никуда не деваются

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

• Один дополнительный цикл для «холодных» инструментов. Когда модель впервые нуждается в отложенном инструменте, она тратит один или два дополнительных вызова модели на поиск и загрузку схемы. Экономия токенов на статической стороне реальна, но часть её возвращается во время выполнения.
• Нет выгоды от кэширования для отложенных схем. Загруженный результат tool_describe попадает в историю разговора (поэтому он кэшируется на последующих шагах), но он никогда не получает выгоды от префикса кэша системной подсказки.
• Зависимость от качества модели. Tool Search предполагает, что модель может составить разумный поисковый запрос для нужного ей инструмента. Меньшие модели справляются с этим хуже; опубликованные цифры Anthropic (49% → 74% на Opus 4 с Tool Search и без него) показывают преимущество, но также и то, что ~26 пунктов точности всё ещё являются ошибкой извлечения.
• Изменения набора инструментов аннулируют кэш. Добавление или удаление инструмента в середине сессии изменяет описания мостовых инструментов (которые включают количество отложенных инструментов) и каталог, поэтому кэш подсказок аннулируется. Это тот же компромисс, что и при любом изменении набора инструментов.

Детали реализации

• Поиск: BM25 по токенизированному имени инструмента + описанию + именам параметров. При отсутствии результатов с положительным рейтингом от BM25 выполняется откат к буквальному поиску подстроки в имени инструмента, что защищает от вырожденных случаев с нулевым IDF (например, поиск «github» в каталоге, где каждое имя инструмента содержит «github»).
• Каталог не сохраняет состояние между шагами. Он перестраивается из текущего списка определений инструментов при каждой сборке — никакого Map с ключом сессии. Это позволяет избежать класса ошибок, когда сохранённый каталог рассинхронизируется с активным реестром инструментов.
• Каталог ограничен наборами инструментов сессии. tool_search, tool_describe и tool_call видят и вызывают только те инструменты, которые были фактически предоставлены сессии. Субагент, работник канбан-доски или сессия шлюза, ограниченные подмножеством наборов инструментов, не могут использовать мост для обнаружения или вызова инструмента за пределами этого подмножества — отложенный каталог — это откладываемая часть собственных включённых/отключённых наборов инструментов сессии, а не всего реестра процессов.
• Без JS-песочницы. VibeOS использует более простой режим «структурированных инструментов» (search / describe / call как обычные функции). Режим «кода» в JS-песочнице, который предлагают некоторые другие реализации, представляет собой большую поверхность атаки; мы его пропускаем.

См. также

• tools/tool_search.py — реализация
• tests/tools/test_tool_search.py — набор регрессионных тестов
• PDF-файл openclaw-tool-search-report в исходном PR реализации с исследованием, которое легло в основу дизайна