Tool search в Claude Code: как агент ищет нужный MCP-инструмент

Если ты подключил несколько MCP-серверов к Claude Code, tool search позволяет подгружать нужные инструменты по запросу, не загружая все определения заранее. При старте агент получает имена отложенных инструментов и инструкции серверов, затем ищет нужное по каталогу. Это помогает работать с большим набором инструментов: документация Anthropic указывает, что точность выбора падает при более чем 30-50 одновременно загруженных инструментах. Это общий ориентир, не замер твоей сессии. Tool search включён по умолчанию при поддержке моделью, но может отключаться из-за платформы, прокси или настроек.

Что происходит с контекстом без tool search

Каждый подключённый MCP-сервер добавляет свои инструменты в список того, что агент может вызвать. Без tool search их определения - имя, описание, схема параметров - загружаются в контекст заранее. При старте сессии серверы подключаются в фоне. Если нужен инструмент сервера, который ещё не завершил подключение, Claude Code ждёт через служебный инструмент WaitForMcpServers.

Официальная документация Anthropic приводит два ориентировочных значения (общие цифры, без указания методики измерения):

• 50 инструментов способны занимать 10-20 тысяч токенов контекста;
• точность выбора нужного инструмента падает при более чем 30-50 одновременно загруженных.

Как оценить состояние tool search по настройкам

Чтобы понять, должен ли tool search работать в текущей сессии, проверь условия:

• какая модель отвечает - Sonnet/Haiku/Opus 4.5 или новее: механизм доступен; более старая модель - нет;
• задан ли ANTHROPIC_BASE_URL на нестандартный хост - в этом случае механизм по умолчанию выключен, если явно не включён через ENABLE_TOOL_SEARCH;
• какое значение у переменной ENABLE_TOOL_SEARCH - false выключает механизм полностью, auto/auto:N включает его только при достижении порога по объёму определений;
• задана ли CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS - без управляемых настроек организации она держит tool search выключенным, даже если пользователь установил ENABLE_TOOL_SEARCH;
• запрещён ли инструмент ToolSearch через permissions.deny в настройках - такой запрет отключает возможность поиска;
• какая платформа используется - на развёртываниях Microsoft Foundry в Azure механизм недоступен, а на Google Cloud Agent Platform его работа зависит от версии Claude Code и модели.

Эта проверка позволяет оценить состояние по конфигурации, но не наблюдать его внутри сессии. Раздел MCP и раздел про tool search в Agent SDK не описывают прямого индикатора «tool search: on/off» в интерфейсе. Отсутствие упоминания в этих двух документах не доказывает, что такого индикатора нет вообще.

Задать переменную можно перед запуском сессии, например ENABLE_TOOL_SEARCH=auto:15 claude. Чтобы инструменты конкретного сервера были загружены всегда, есть поле alwaysLoad: true в конфигурации этого сервера. Оно доступно для всех типов серверов; условия и ограничения описаны в разделе про alwaysLoad ниже.

Как работает tool search

При включённом tool search для отложенных инструментов в контекст при старте сессии загружаются только имена и инструкции сервера (server instructions) - описание, для каких задач сервер нужен. Когда задаче требуется возможность, которой ещё нет в контексте, агент сам ищет подходящий инструмент по каталогу.

Документация Agent SDK описывает механику поиска подробнее: за один поиск по умолчанию подгружается до пяти самых релевантных инструментов из каталога. Они остаются доступны для следующих ходов сессии, пока SDK не сожмёт сообщения, в которых агент их нашёл (в документации - compacts). После такого сжатия ранее найденные инструменты могут выпасть из контекста, и при следующей необходимости агент ищет их заново. Каталог поддерживает до 10 000 инструментов. Документация MCP для самого Claude Code этих конкретных цифр не приводит, но описывает тот же принцип отложенной загрузки.

По документации Agent SDK, каждый такой поиск добавляет один дополнительный цикл обмена (round-trip). Что именно этот цикл включает, документация не уточняет. Для Claude Code документация MCP описывает и различие в сообщениях об ошибках: без tool search Claude Code не сообщает модели о неудачных подключениях серверов. При включённом поиске модель получает сведения о том, какой сервер не подключился и с какой ошибкой.

Фиксированного лимита на число инструментов от одного сервера Claude Code не устанавливает. Практический предел - бюджет контекстного окна конкретной сессии.

Настройка инструментов - одна из задач при работе с контекстом ИИ-агента.

Практикум по вайб-кодингу

+Твой второй мозг

3 вечера - инструменты, метод, первый проект

Старт 17–19 ноября  ·  2 000 ₽

Записаться →

Когда tool search отключается по умолчанию

Механизм включён по умолчанию, но его работа зависит от модели, хоста API и платформы.

Модель. Tool search требует модель, поддерживающую tool_reference блоки: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 и более поздние. Для более старых моделей Claude Code загружает определения инструментов заранее.

Хост API. Claude Code отключает tool search, когда переменная ANTHROPIC_BASE_URL указывает на сторонний хост: большинство прокси не пропускают специальные tool_reference блоки. Это касается подключения к Claude через собственный шлюз или прокси-сервер вместо прямого адреса Anthropic. Причина отключения - нестандартный ANTHROPIC_BASE_URL; способ оплаты подписки сам по себе её не создаёт. Переменную ENABLE_TOOL_SEARCH можно задать явно, чтобы переопределить это поведение. Если сам прокси не поддерживает tool_reference блоки, принудительное включение приводит к ошибке запроса. Отката к предварительной загрузке в этом случае не будет.

Платформа развёртывания. На развёртываниях Microsoft Foundry, размещённых на Azure, tool search не работает: сервер отклоняет запрос, и ENABLE_TOOL_SEARCH этого не отменяет. На Google Cloud Agent Platform до версии Claude Code 2.1.221 механизм был выключен для всех моделей без явного ENABLE_TOOL_SEARCH=true. Начиная с этой версии он включён по умолчанию для Opus/Sonnet/Haiku 4.5 и новее. Для более старых моделей платформы Claude Code по-прежнему загружает все инструменты заранее, потому что их серверная инфраструктура отклоняет обязательный служебный заголовок.

У переменной ENABLE_TOOL_SEARCH пять вариантов настройки:

• не задана - стандартное поведение с перечисленными выше исключениями;
• true - механизм включён на моделях, которые его поддерживают, кроме двух исключений: Azure Foundry и старых моделей Agent Platform; при отправке через прокси без поддержки tool_reference блоков запросы завершатся ошибкой;
• auto - Claude Code грузит инструменты заранее, пока их суммарные определения занимают меньше 10% контекстного окна, и включает отложенную загрузку при достижении этого порога;
• auto:N - тот же принцип с порогом, заданным вручную в процентах;
• false - механизм выключен полностью, все инструменты грузятся заранее.

Отдельно есть переменная CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: если она задана, tool search остаётся выключенным, и установка ENABLE_TOOL_SEARCH пользователем этого не меняет. Исключение - организация держит tool search включённым через управляемые (managed) настройки, доступные начиная с Claude Code версии 2.1.227.

Что даёт alwaysLoad и как влияет на контекст и запуск

Поле alwaysLoad: true в конфигурации сервера доступно для всех типов серверов. С ним все инструменты этого сервера загружаются в контекст при старте независимо от настройки ENABLE_TOOL_SEARCH. Агенту не нужно искать их перед использованием.

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

Исключение - удалённый сервер с действительной кэшированной записью: он подставляет инструменты из кэша без подключения и не задерживает старт. Кэш обнаружения (discovery cache) по умолчанию выключен, если его ещё не включили для аккаунта при постепенном запуске функции. Также его можно включить явно через MCP_DISCOVERY_CACHE=1. Исключение с быстрым стартом действует, когда кэш активен и содержит действительную запись. При этом инструменты с alwaysLoad занимают контекст постоянно, независимо от того, понадобились бы они агенту при работе через поиск.

Для тех, кто пишет собственный MCP-сервер: инструкции сервера (server instructions) помогают Claude понять, когда искать его инструменты, по аналогии с тем, как работают навыки (Skills). Claude Code усекает описание каждого инструмента и инструкции каждого сервера до 2048 символов по умолчанию, поэтому критичные детали стоит помещать в начало.

Выбор способа расширить Claude Code зависит не только от числа подключённых MCP-серверов. Разбор Skills, Subagents, MCP и Plugins под разные задачи есть в статьях Claude Code: сколько расширений держать одновременно и Что выбрать в Claude Code: Skills, Subagents, MCP или Plugins. Пошаговую установку конкретных MCP-серверов разбирает MCP-серверы для Claude Code: готовые связки.

Что дальше

Для набора из менее чем примерно 10 инструментов, чьи определения помещаются в контекст без проблем, документация Agent SDK отмечает: загрузка всех сразу обычно быстрее. При этом в Claude Code по умолчанию, когда переменная не задана и нет перечисленных выше ограничений, tool search включён и загрузка MCP-инструментов откладывается до поиска, кроме серверов с alwaysLoad.

Здесь можно явно задать ENABLE_TOOL_SEARCH=auto: определения будут загружаться заранее, пока их суммарный объём меньше 10% контекстного окна, а при достижении порога включится поиск. Другой вариант - ENABLE_TOOL_SEARCH=false, если набор заведомо не вырастет. В этом случае Claude Code перестанет сообщать модели о сбоях подключения серверов, как описано выше.

В остальных случаях при изменении окружения снова проверь условия работы:

• смени модель на Sonnet/Haiku/Opus 4.5 или новее, если сессия работает на более старой;
• если подключение идёт через нестандартный ANTHROPIC_BASE_URL, задай ENABLE_TOOL_SEARCH=true явно, только когда сам прокси пропускает tool_reference блоки;
• убедись, что платформа развёртывания не входит в список исключений: Azure Foundry или старые модели Google Cloud Agent Platform.

Если условия выполнены и поиск не запрещён настройками, можно подключать нужные MCP-серверы. Полем alwaysLoad помечай только те, чьи инструменты нужны на каждом ходу сессии; для остальных оставь загрузку через поиск.

Практикум по вайб-кодингу

+Твой второй мозг

3 вечера - инструменты, метод, первый проект

Старт 17–19 ноября  ·  2 000 ₽

Записаться →

Новые материалы - дайджестом, без спама

Гайды выходят регулярно. Подпишись, чтобы не пропускать: пришлю подборку в Telegram или на email. Раз в неделю или каждый день - выбираешь сам.

Подписаться в Telegramили на email