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

​
How tool search works

Когда tool search активен, определения инструментов исключаются из окна контекста. Агент получает сводку доступных инструментов и ищет релевантные, когда задача требует возможности, которая еще не загружена. 3-5 наиболее релевантных инструментов загружаются в контекст, где они остаются доступными для последующих ходов. Если разговор достаточно длинный, чтобы SDK компактировал более ранние сообщения для освобождения места, ранее обнаруженные инструменты могут быть удалены, и агент снова ищет по мере необходимости. Tool search добавляет один дополнительный обмен данными в первый раз, когда Claude обнаруживает инструмент (этап поиска), но для больших наборов инструментов это компенсируется меньшим контекстом на каждом ходу. При наличии менее ~10 инструментов загрузка всего заранее обычно быстрее. Для получения подробной информации об основном механизме API см. Tool search в API.
Tool search требует Claude Sonnet 4 или более поздней версии, либо Claude Opus 4 или более поздней версии. Модели Haiku не поддерживают tool search.
Tool search включен по умолчанию. Он отключен по умолчанию на Vertex AI, где он поддерживается для Claude Sonnet 4.5 и более поздних версий, а также Claude Opus 4.5 и более поздних версий. Он также отключен, когда ANTHROPIC_BASE_URL указывает на хост, не принадлежащий первой стороне, поскольку большинство прокси не пересылают блоки tool_reference. Вы можете переопределить любое значение по умолчанию с помощью переменной окружения ENABLE_TOOL_SEARCH:
ЗначениеПоведение
(не установлено)Tool search включен. Определения инструментов отложены и обнаруживаются по требованию. Возвращается к загрузке заранее на Vertex AI или при использовании ANTHROPIC_BASE_URL, не принадлежащего первой стороне.
trueTool search всегда включен. SDK отправляет заголовок beta даже на Vertex AI и через прокси. Запросы не выполняются на моделях Vertex AI более ранних версий, чем Sonnet 4.5 или Opus 4.5, или на прокси, которые не поддерживают блоки tool_reference.
autoПроверяет объединенное количество токенов всех определений инструментов в сравнении с окном контекста модели. Если они превышают 10%, tool search активируется. Если они менее 10%, все инструменты загружаются в контекст обычным образом.
auto:NТо же, что auto, но с пользовательским процентом. auto:5 активируется, когда определения инструментов превышают 5% окна контекста. Более низкие значения активируются раньше.
falseTool search отключен. Все определения инструментов загружаются в контекст на каждом ходу.
Tool search применяется ко всем зарегистрированным инструментам, независимо от того, поступают ли они с удаленных MCP серверов или пользовательских SDK MCP серверов. При использовании auto пороговое значение основано на объединенном размере всех определений инструментов на всех серверах. Установите значение в опции env на query(). Этот пример подключается к удаленному MCP серверу, который предоставляет множество инструментов, предварительно одобряет все их с помощью подстановочного символа и использует auto:5, чтобы tool search активировался, когда их определения превышают 5% окна контекста: 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and run the appropriate database query",
  options: {
    mcpServers: {
      "enterprise-tools": {
        // Connect to a remote MCP server
        type: "http",
        url: "https://tools.example.com/mcp"
      }
    },
    allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
    env: {
      ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}
Установка 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”). Вы также можете добавить раздел системного приглашения, в котором перечислены доступные категории инструментов. Это дает агенту контекст о том, какие виды инструментов доступны для поиска: 
You can search for tools to interact with Slack, GitHub, and Jira.

​
Limits

  • Максимальное количество инструментов: 10 000 инструментов в вашем каталоге
  • Результаты поиска: Возвращает 3-5 наиболее релевантных инструментов на поиск
  • Поддержка модели: Claude Sonnet 4 и более поздние версии, Claude Opus 4 и более поздние версии (без Haiku)