Инструмент поиска инструментов

Инструмент поиска инструментов позволяет Claude работать с сотнями или тысячами инструментов, динамически обнаруживая и загружая их по требованию. Вместо того чтобы загружать все определения инструментов в контекстное окно заранее, Claude выполняет поиск по вашему каталогу инструментов (включая имена инструментов, описания, имена аргументов и описания аргументов) и загружает только те инструменты, которые ему нужны.

Этот подход решает две проблемы, которые быстро усугубляются по мере масштабирования библиотек инструментов:

• Раздувание контекста: Определения инструментов быстро расходуют бюджет контекста. Типичная многосерверная конфигурация (GitHub, Slack, Sentry, Grafana, Splunk) может потреблять ~55 тыс. токенов в определениях до того, как Claude начнёт выполнять реальную работу. Поиск инструментов обычно сокращает это более чем на 85%, загружая только 3–5 инструментов, которые Claude действительно нужны для конкретного запроса.
• Точность выбора инструментов: Способность Claude правильно выбирать нужный инструмент значительно снижается, когда доступных инструментов становится более 30–50. Предоставляя сфокусированный набор релевантных инструментов по требованию, поиск инструментов поддерживает высокую точность выбора даже при наличии тысяч инструментов.

Хотя это предоставляется как серверный инструмент, вы также можете реализовать собственную клиентскую функциональность поиска инструментов. Подробности см. в разделе Пользовательская реализация поиска инструментов.

Вы также можете реализовать клиентский поиск инструментов, возвращая блоки tool_reference из вашей собственной реализации поиска.

Как работает поиск инструментов

Существует два варианта поиска инструментов:

• Regex (tool_search_tool_regex_20251119): Claude строит регулярные выражения для поиска инструментов
• BM25 (tool_search_tool_bm25_20251119): Claude использует запросы на естественном языке для поиска инструментов

Когда вы включаете инструмент поиска инструментов:

1. Вы включаете инструмент поиска инструментов (например, tool_search_tool_regex_20251119 или tool_search_tool_bm25_20251119) в список инструментов
2. Вы предоставляете все определения инструментов с defer_loading: true для инструментов, которые не должны загружаться немедленно
3. Claude изначально видит только инструмент поиска инструментов и любые незадержанные инструменты
4. Когда Claude нужны дополнительные инструменты, он выполняет поиск с помощью инструмента поиска инструментов
5. API возвращает 3–5 наиболее релевантных блоков tool_reference
6. Эти ссылки автоматически разворачиваются в полные определения инструментов
7. Claude выбирает из обнаруженных инструментов и вызывает их

Это позволяет поддерживать эффективность контекстного окна при сохранении высокой точности выбора инструментов.

Быстрый старт

Вот простой пример с отложенными инструментами:

Определение инструмента

Инструмент поиска инструментов имеет два варианта:

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}

Отложенная загрузка инструментов

Пометьте инструменты для загрузки по требованию, добавив defer_loading: true:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}

Ключевые моменты:

• Инструменты без defer_loading загружаются в контекст немедленно
• Инструменты с defer_loading: true загружаются только тогда, когда Claude обнаруживает их через поиск
• Сам инструмент поиска инструментов никогда не должен иметь defer_loading: true
• Оставьте 3–5 наиболее часто используемых инструментов незадержанными для оптимальной производительности

Оба варианта поиска инструментов (regex и bm25) выполняют поиск по именам инструментов, описаниям, именам аргументов и описаниям аргументов.

Как работает отложенная загрузка внутри: Отложенные инструменты не включаются в префикс системного промпта. Когда модель обнаруживает отложенный инструмент через поиск инструментов, определение инструмента добавляется встроенно как блок tool_reference в разговоре. Префикс остаётся нетронутым, поэтому кэширование промптов сохраняется. Грамматика для строгого режима строится из полного набора инструментов, поэтому defer_loading и строгий режим совместимы без перекомпиляции грамматики.

Формат ответа

Когда Claude использует инструмент поиска инструментов, ответ включает новые типы блоков:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll search for tools to help with the weather information."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01ABC123",
      "name": "tool_search_tool_regex",
      "input": {
        "query": "weather"
      }
    },
    {
      "type": "tool_search_tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": {
        "type": "tool_search_tool_search_result",
        "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
      }
    },
    {
      "type": "text",
      "text": "I found a weather tool. Let me get the weather for San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01XYZ789",
      "name": "get_weather",
      "input": { "location": "San Francisco", "unit": "fahrenheit" }
    }
  ],
  "stop_reason": "tool_use"
}

Понимание ответа

• server_tool_use: Указывает, что Claude вызывает инструмент поиска инструментов
• tool_search_tool_result: Содержит результаты поиска с вложенным объектом tool_search_tool_search_result
• tool_references: Массив объектов tool_reference, указывающих на обнаруженные инструменты
• tool_use: Claude вызывает обнаруженный инструмент

Блоки tool_reference автоматически разворачиваются в полные определения инструментов перед показом Claude. Вам не нужно обрабатывать это разворачивание самостоятельно. Это происходит автоматически в API, при условии что вы предоставляете все соответствующие определения инструментов в параметре tools.

Интеграция с MCP

Для настройки mcp_toolset с defer_loading см. MCP connector.

Пользовательская реализация поиска инструментов

Вы можете реализовать собственную логику поиска инструментов (например, с использованием эмбеддингов или семантического поиска), возвращая блоки tool_reference из пользовательского инструмента. Когда Claude вызывает ваш пользовательский инструмент поиска, верните стандартный tool_result с блоками tool_reference в массиве content:

{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}

Каждый упомянутый инструмент должен иметь соответствующее определение инструмента в параметре верхнего уровня tools с defer_loading: true. Этот подход позволяет использовать более сложные алгоритмы поиска при сохранении совместимости с системой поиска инструментов.

Для полного примера с использованием эмбеддингов см. cookbook по поиску инструментов с эмбеддингами.

Обработка ошибок

HTTP-ошибки (статус 400)

Эти ошибки препятствуют обработке запроса:

Все инструменты отложены:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

Отсутствует определение инструмента:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

Ошибки результата инструмента (статус 200)

Ошибки во время выполнения инструмента возвращают ответ 200 с информацией об ошибке в теле:

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

Коды ошибок:

• too_many_requests: Превышен лимит запросов для операций поиска инструментов
• invalid_pattern: Некорректный шаблон регулярного выражения
• pattern_too_long: Шаблон превышает ограничение в 200 символов
• unavailable: Сервис поиска инструментов временно недоступен

Распространённые ошибки

Кэширование промптов

О том, как defer_loading сохраняет кэширование промптов, см. Использование инструментов с кэшированием промптов.

Система автоматически разворачивает блоки tool_reference по всей истории разговора, поэтому Claude может повторно использовать обнаруженные инструменты в последующих ходах без повторного поиска.

Потоковая передача

При включённой потоковой передаче вы будете получать события поиска инструментов как часть потока:

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}

// Claude continues with discovered tools

Пакетные запросы

Вы можете включить инструмент поиска инструментов в Messages Batches API. Операции поиска инструментов через Messages Batches API оцениваются так же, как и в обычных запросах Messages API.

Хранение данных

Серверный поиск инструментов (инструмент tool_search) индексирует и хранит данные каталога инструментов (имена инструментов, описания и метаданные аргументов) за пределами немедленного ответа API; эти данные каталога хранятся в соответствии со стандартной политикой хранения Anthropic. Пользовательские клиентские реализации поиска инструментов, использующие стандартный Messages API, полностью соответствуют требованиям ZDR.

Для получения информации о соответствии ZDR для всех функций см. API и хранение данных.

Ограничения и лучшие практики

Ограничения

• Максимальное количество инструментов: 10 000 инструментов в вашем каталоге
• Результаты поиска: Возвращает 3–5 наиболее релевантных инструментов на поиск
• Длина шаблона: Максимум 200 символов для шаблонов регулярных выражений
• Поддержка моделей: Только Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+ (без Haiku)

Когда использовать поиск инструментов

Хорошие варианты использования:

• В вашей системе доступно 10+ инструментов
• Определения инструментов потребляют >10 тыс. токенов
• Возникают проблемы с точностью выбора инструментов при большом наборе инструментов
• Создание систем на базе MCP с несколькими серверами (200+ инструментов)
• Библиотека инструментов растёт со временем

Когда традиционный вызов инструментов может быть лучше:

• Менее 10 инструментов всего
• Все инструменты часто используются в каждом запросе
• Очень небольшие определения инструментов (<100 токенов всего)

Советы по оптимизации

• Оставьте 3–5 наиболее часто используемых инструментов незадержанными
• Пишите чёткие, описательные имена и описания инструментов
• Используйте согласованное пространство имён в именах инструментов: добавляйте префикс по сервису или ресурсу (например, github_, slack_), чтобы поисковые запросы естественно находили нужную группу инструментов
• Используйте семантические ключевые слова в описаниях, соответствующие тому, как пользователи описывают задачи
• Добавьте раздел системного промпта, описывающий доступные категории инструментов: "You can search for tools to interact with Slack, GitHub, and Jira"
• Отслеживайте, какие инструменты обнаруживает Claude, чтобы уточнять описания

Использование

Использование инструмента поиска инструментов отслеживается в объекте использования ответа:

{
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 256,
    "server_tool_use": {
      "tool_search_requests": 2
    }
  }
}

Следующие шаги