Skip to main content
Tool search позволяет вашему агенту работать с сотнями или тысячами инструментов, динамически обнаруживая и загружая их по требованию. Вместо загрузки всех определений инструментов в окно контекста заранее, агент ищет в каталоге инструментов и загружает только необходимые ему инструменты. Этот подход решает две проблемы при масштабировании библиотек инструментов:
  • Эффективность контекста: Определения инструментов могут занимать большую часть окна контекста (50 инструментов могут использовать 10-20K токенов), оставляя меньше места для фактической работы.
  • Точность выбора инструмента: Точность выбора инструмента снижается при загрузке более 30-50 инструментов одновременно.

How tool search works

Tool search включен по умолчанию, за исключением случаев, перечисленных в разделе Configure tool search. Когда tool search активен, определения инструментов исключаются из окна контекста. Агент получает сводку доступных инструментов и ищет релевантные, когда задача требует возможности, которая еще не загружена. До пяти наиболее релевантных инструментов загружаются в контекст по умолчанию, где они остаются доступными для последующих ходов до тех пор, пока SDK не компактирует сообщения, в которых агент их обнаружил. После этой компактификации агент снова ищет эти инструменты, когда они ему снова понадобятся. Tool search добавляет один дополнительный обмен данными каждый раз, когда Claude ищет инструменты, но для больших наборов инструментов это компенсируется меньшим контекстом на каждом ходу. При наличии менее ~10 инструментов, определения которых удобно помещаются в окно контекста, загрузка всего заранее обычно быстрее. Для получения подробной информации об основном механизме API см. Tool search в API.
Tool search не поддерживается на развертываниях Microsoft Foundry, размещенных на Azure, которые отклоняют его на стороне сервера: SDK обнаруживает отклонение и загружает определения инструментов заранее для этого развертывания вместо этого. ENABLE_TOOL_SEARCH не может переопределить это, так как отклонение исходит от самого развертывания.
Tool search включен по умолчанию. Для моделей из списка неподдерживаемых моделей SDK SDK загружает определения инструментов заранее, и никакое значение ENABLE_TOOL_SEARCH не переопределяет это. На Google Cloud’s Agent Platform SDK решает по поколению модели:
  • Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 и более поздние версии: tool search включен по умолчанию.
  • Более ранние модели Agent Platform: SDK загружает определения инструментов заранее, потому что их стеки обслуживания отклоняют требуемый заголовок beta. ENABLE_TOOL_SEARCH не может переопределить это.
До Claude Code v2.1.221 SDK отключал tool search для всех моделей на Google Cloud’s Agent Platform, если вы не установили ENABLE_TOOL_SEARCH. SDK также отключает tool search, когда ANTHROPIC_BASE_URL указывает на хост, не принадлежащий первой стороне, поскольку большинство прокси не пересылают блоки tool_reference. Вы можете переопределить это значение по умолчанию с помощью переменной окружения ENABLE_TOOL_SEARCH: Установка CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS сохраняет tool search отключенным. Вы не можете переопределить это, установив ENABLE_TOOL_SEARCH самостоятельно. В Claude Code v2.1.227 или более поздней версии ваша организация может сохранить tool search включенным при этой переменной через управляемые настройки. В сессии, которая получает конфигурацию HIPAA, tool search отключен, и ни ENABLE_TOOL_SEARCH, ни управляемые настройки не включают его снова. Отключение предварительных возможностей охватывает, где применяется переопределение и что переменная удаляет. Tool search применяется ко всем зарегистрированным инструментам, независимо от того, поступают ли они с удаленных MCP-серверов или пользовательских SDK MCP-серверов. Когда вы используете auto, SDK подсчитывает каждое определение, которое tool search может отложить, в сторону одного объединенного порога: каждый инструмент MCP, который не отмечен как alwaysLoad, с любого сервера, плюс встроенные инструменты, которые загружаются по требованию. SDK загружает основные встроенные инструменты, такие как Bash, Read и Edit, заранее и не подсчитывает их в сторону порога. Мод в одном из ваших плагинов также может отложить инструмент или загрузить его заранее, что изменяет этот подсчёт. Установите значение в опции env на query(). В TypeScript env заменяет окружение подпроцесса, поэтому распространите ...process.env, чтобы сохранить унаследованные переменные. В Python env объединяется с унаследованным окружением. Этот пример подключается к удаленному MCP-серверу, который предоставляет множество инструментов, предварительно одобряет все их с помощью подстановочного символа и использует auto:5, чтобы tool search активировался, когда определения, которые он может отложить, достигают 5% контекстного окна:
Чтобы запустить этот пример, замените https://tools.example.com/mcp на URL вашего собственного MCP-сервера. При успехе текст результата выводится на консоль. Поскольку это вызов query() в один ход, SDK вызывает исключение после выдачи результата ошибки, поэтому пример оборачивает цикл в блок try. Чтобы узнать, почему запуск не удался, проверьте subtype сообщения результата, например error_during_execution, внутри цикла. Дополнительную информацию о сообщениях результатов см. в разделе Обработка результата.

Optimize tool discovery

Механизм поиска сопоставляет запросы с именами и описаниями инструментов. Имена вроде search_slack_messages появляются для более широкого диапазона запросов, чем query_slack. Описания с конкретными ключевыми словами (“Search Slack messages by keyword, channel, or date range”) соответствуют большему количеству запросов, чем общие (“Query Slack”). Вы также можете добавить раздел системного приглашения, в котором перечислены доступные категории инструментов. Это дает агенту контекст о том, какие виды инструментов доступны для поиска. Передайте текст через опцию systemPrompt в TypeScript или system_prompt в Python, используя предустановку claude_code с append, которая добавляет ваш текст к приглашению предустановки вместо его замены:
Для полного набора опций системного приглашения см. Изменение системных приглашений.

Limits

  • Максимальное количество инструментов: 10 000 инструментов в вашем каталоге
  • Результаты поиска: возвращает до пяти наиболее релевантных инструментов на поиск по умолчанию
  • Поддержка модели: Opus 4, Sonnet 4, Haiku 4.5 и более поздние модели, либо Opus 4.5, Sonnet 4.5, Haiku 4.5 и более поздние модели на Agent Platform Google Cloud. На более ранних моделях SDK загружает определения инструментов заранее, как описано в разделе Настройка поиска инструментов.