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

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

Загрузка всех определений инструментов заранее вызывает две проблемы по мере роста библиотеки инструментов:

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

Поиск инструментов общедоступен в Claude API. Поддерживаемые модели см. в разделе Совместимость моделей.

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



Совместимость моделей

Оба варианта поиска инструментов доступны в следующих моделях:

Claude Opus 4.1 и более ранние модели не поддерживают инструмент поиска инструментов.



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

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

• 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) в свой список tools.
2. Вы предоставляете определение каждого инструмента в массиве tools и устанавливаете defer_loading: true для инструментов, которые не должны загружаться заранее. Как минимум один инструмент — обычно сам инструмент поиска инструментов — должен оставаться неотложенным.
3. Изначально контекст Claude содержит только инструмент поиска инструментов и все неотложенные инструменты.
4. Когда Claude нужны дополнительные инструменты, он выполняет поиск с помощью инструмента поиска инструментов.
5. API выполняет поиск и возвращает подходящие инструменты в виде блоков tool_reference (по умолчанию до 5).
6. API автоматически разворачивает эти ссылки в полные определения инструментов.
7. Claude выбирает из обнаруженных инструментов и вызывает их.



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

Следующий пример включает инструмент поиска инструментов и два отложенных инструмента:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get the weather at a specific location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
            "defer_loading": True,
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "file_types": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["query"],
            },
            "defer_loading": True,
        },
    ],
)

print(response)

Claude выполняет поиск по каталогу, обнаруживает get_weather и вызывает его. Ответ завершается с stop_reason: "tool_use". Выполните обнаруженный инструмент и верните tool_result, как описано в разделе Обработка вызовов инструментов. В разделе Формат ответа показаны блоки, которые вы получите, и что отправлять дальше.



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

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

{
  "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 управляет тем, что попадает в контекстное окно, а не тем, что вы отправляете в запросе:

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

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

Внутренне API исключает отложенные инструменты из префикса системной подсказки. Когда Claude обнаруживает отложенный инструмент через поиск инструментов, API добавляет блок tool_reference непосредственно в разговор, а затем разворачивает его в полное определение инструмента перед передачей Claude. Префикс остаётся нетронутым, поэтому кэширование подсказок сохраняется. Грамматика для строгого режима (правила, ограничивающие вывод вызова инструмента в соответствии с вашими схемами) строится на основе полного набора инструментов, поэтому 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": {
        "pattern": "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 к инструменту поиска инструментов. Поиск выполняется на серверах Anthropic. Никогда не возвращайте tool_result для его идентификатора srvtoolu_....
• tool_search_tool_result: результаты поиска во вложенном объекте tool_search_tool_search_result. Сохраняйте его в истории сообщений как есть.
• tool_references: массив объектов tool_reference, указывающих на обнаруженные инструменты. API разворачивает их для Claude. Вам никогда не нужно разворачивать их самостоятельно.
• tool_use: вызов Claude к обнаруженному инструменту. Выполните его и верните tool_result точно так же, как при стандартном использовании инструментов.

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



Продолжение разговора

В следующем запросе передайте содержимое ассистента обратно без изменений, включая блоки server_tool_use и tool_search_tool_result. Добавьте свой tool_result для обнаруженного инструмента в сообщение пользователя и отправьте тот же массив tools: инструмент поиска плюс все отложенные определения. Не возвращайте tool_result для идентификатора srvtoolu_...: API отклонит запрос. API разворачивает блоки tool_reference на протяжении всей истории разговора, поэтому Claude может повторно использовать обнаруженные инструменты в последующих ходах без повторного поиска. Поиск, который ничего не находит, возвращает tool_search_tool_search_result с пустым массивом tool_references, а не ошибку.



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

Если ваши инструменты поступают с серверов MCP через коннектор MCP, вы не устанавливаете defer_loading для отдельных определений инструментов. Вместо этого установите его один раз в default_config записи mcp_toolset для всего сервера или для каждого инструмента в его configs. См. Конфигурация набора инструментов MCP.



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

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

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

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

Полный пример с использованием эмбеддингов см. в рецепте поиск инструментов с эмбеддингами.



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



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

Эти ошибки не позволяют API обработать запрос:

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

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
  }
}

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

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' not found in available tools"
  }
}



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

Когда операция поиска инструментов завершается сбоем во время выполнения, API возвращает ответ 200 с ошибкой в теле:

{
  "type": "tool_search_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_tool_input",
    "error_message": "Invalid regular expression pattern: missing ) at position 1"
  }
}

Поле error_code имеет четыре возможных значения:

• invalid_tool_input: входные данные поиска были недопустимыми, например некорректный шаблон регулярного выражения или шаблон, превышающий лимит в 200 символов
• unavailable: поиск не удалось выполнить, например из-за истечения времени ожидания или недоступности сервиса
• too_many_requests: превышено ограничение скорости для операций поиска инструментов
• execution_time_exceeded: поиск превысил лимит времени выполнения



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



Кэширование подсказок

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

Инструмент с defer_loading: true не может одновременно иметь cache_control: API вернёт ошибку 400. Размещайте точку разрыва кэша на неотложенном инструменте.



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

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

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 pattern streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"pattern\":\"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.



Ограничения и рекомендации



Ограничения

• Максимальное количество отложенных инструментов: 10 000 инструментов с defer_loading: true на запрос
• Результаты поиска: каждый поиск возвращает по умолчанию до 5 подходящих инструментов
• Длина шаблона и запроса: максимум 200 символов для шаблонов регулярных выражений и 500 символов для запросов BM25
• Поддержка моделей: см. Совместимость моделей



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

Используйте поиск инструментов, если применимо любое из следующего:

• У вас доступно 10 или более инструментов.
• Ваши определения инструментов потребляют более 10 тыс. токенов.
• Точность выбора инструментов падает по мере роста набора инструментов.
• Вы агрегируете несколько серверов MCP (200+ инструментов).
• Ваша библиотека инструментов растёт со временем.

Стандартный вызов инструментов без поиска инструментов лучше подходит, когда у вас менее 10 инструментов, каждый инструмент используется в каждом запросе или ваши определения инструментов малы (менее 100 токенов в сумме).



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

• Оставляйте 3–5 наиболее часто используемых инструментов неотложенными.
• Пишите понятные, описательные имена и описания инструментов.
• Используйте согласованные пространства имён в именах инструментов: добавляйте префикс по сервису или ресурсу (например, github_, slack_), чтобы один поиск соответствовал всей группе.
• Используйте в описаниях ключевые слова, соответствующие тому, как пользователи описывают задачи.
• Добавьте в системную подсказку раздел с описанием доступных категорий инструментов: «Вы можете искать инструменты для взаимодействия со Slack, GitHub и Jira».
• Отслеживайте, какие инструменты обнаруживает Claude, чтобы уточнять свои описания.



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

Поиск инструментов не учитывается как отдельный серверный инструмент. Объект usage.server_tool_use в ответе не содержит поля для поиска инструментов, а определения инструментов, которые поиск загружает в контекст, учитываются как входные токены, как и любые другие определения инструментов.



Дальнейшие шаги