- Эффективность контекста: Определения инструментов могут занимать большую часть окна контекста (50 инструментов могут использовать 10-20K токенов), оставляя меньше места для фактической работы.
- Точность выбора инструмента: Точность выбора инструмента снижается при загрузке более 30-50 инструментов одновременно.
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 и более поздние версии.
Связанная документация
- Tool search в API: Полная документация API для tool search, включая пользовательские реализации
- Подключение MCP серверов: Подключение к внешним инструментам через MCP серверы
- Пользовательские инструменты: Создавайте свои собственные инструменты с помощью SDK MCP серверов
- Справочник TypeScript SDK: Полный справочник API
- Справочник Python SDK: Полный справочник API