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

How tool search works

Когда tool search активен, определения инструментов исключаются из окна контекста. Агент получает сводку доступных инструментов и ищет релевантные, когда задача требует возможности, которая еще не загружена. До пяти наиболее релевантных инструментов загружаются в контекст по умолчанию, где они остаются доступными для последующих ходов. Если разговор достаточно длинный, чтобы SDK компактировал более ранние сообщения для освобождения места, ранее обнаруженные инструменты могут быть удалены, и агент снова ищет по мере необходимости. Tool search добавляет один дополнительный обмен данными в первый раз, когда Claude обнаруживает инструмент (этап поиска), но для больших наборов инструментов это компенсируется меньшим контекстом на каждом ходу. При наличии менее ~10 инструментов загрузка всего заранее обычно быстрее. Для получения подробной информации об основном механизме API см. Tool search в API.
Tool search поддерживается на Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 и более поздних моделях; см. совместимость моделей в документации API для получения актуального списка. На платформе Agent Platform Google Cloud минимально поддерживаемые модели — Claude Sonnet 4.5 и Claude Opus 4.5.
Tool search включен по умолчанию. Он отключен по умолчанию на Google Cloud’s Agent Platform, где он поддерживается для Claude Sonnet 4.5 и более поздних версий, а также Claude Opus 4.5 и более поздних версий. Он также отключен, когда ANTHROPIC_BASE_URL указывает на хост, не принадлежащий первой стороне, поскольку большинство прокси не пересылают блоки tool_reference. Вы можете переопределить любое значение по умолчанию с помощью переменной окружения ENABLE_TOOL_SEARCH: Установка CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS сохраняет tool search отключенным, и ENABLE_TOOL_SEARCH не может его переопределить. Переменная удаляет заголовок beta, который требуют определения инструментов defer_loading и блоки содержимого tool_reference. Tool search применяется ко всем зарегистрированным инструментам, независимо от того, поступают ли они с удаленных MCP серверов или пользовательских SDK MCP серверов. При использовании auto пороговое значение основано на объединенном размере всех определений инструментов на всех серверах. Установите значение в опции 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, внутри цикла. Дополнительную информацию о сообщениях результатов см. в разделе Обработка результата. Установка ENABLE_TOOL_SEARCH на "false" отключает tool search и загружает все определения инструментов в контекст на каждом ходу. Это удаляет раунд поиска, что может быть быстрее, когда набор инструментов небольшой (менее ~10 инструментов) и определения удобно помещаются в окно контекста.

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 инструментов в вашем каталоге
  • Результаты поиска: возвращает до пяти наиболее релевантных инструментов на поиск по умолчанию
  • Поддержка модели: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 и более поздние модели; см. совместимость моделей в документации API для получения актуального списка. На платформе Agent Platform Google Cloud — Claude Sonnet 4.5 и более поздние версии, а также Claude Opus 4.5 и более поздние версии.