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

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

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

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

Модели, поддерживающие поиск инструментов, перечислены в разделе Совместимость моделей.

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

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

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

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; Claude может задать limit во входных данных поиска).
6. API автоматически разворачивает эти ссылки в полные определения инструментов.
7. Claude выбирает из обнаруженных инструментов и вызывает их.

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    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 мог вызывать их без предварительного поиска.

Наборы инструментов для использования компьютера и браузера (computer_toolset_20260801 и browser_toolset_20260801) принимают defer_loading для каждого входящего в набор инструмента внутри объекта configs записи, а не на уровне самой записи; запрос, устанавливающий его на уровне записи, отклоняется. Поскольку набор инструментов откладывается и разворачивается как единое целое, defer_loading должен иметь одинаковое значение для каждого включённого участника набора, и когда Claude обнаруживает набор инструментов через поиск, все включённые участники загружаются одновременно. Формат configs см. в разделе Клиентские наборы инструментов.

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

Внутренне API исключает отложенные инструменты из префикса системной подсказки. Когда Claude обнаруживает отложенный инструмент через поиск инструментов, API добавляет блок tool_reference непосредственно в разговор, а затем разворачивает его в полное определение инструмента перед передачей Claude. Префикс остаётся нетронутым, поэтому «prompt caching» (кэширование подсказок) сохраняется. Грамматика для строгого режима (правила, ограничивающие вывод вызовов инструментов соответствием вашим схемам) строится на основе полного набора инструментов, поэтому 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",
        "limit": 10
      }
    },
    {
      "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_.... Поле input содержит поисковый запрос (pattern для варианта regex, query для BM25) и может включать необязательный limit — целое число от 1 до 10 000, ограничивающее количество подходящих инструментов, возвращаемых поиском (по умолчанию: 5).
• 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 в массиве content:

{
  "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: поиск превысил ограничение по времени выполнения

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

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

{
  "name": "my_tool",
  "description": "Full description here",
  "input_schema": {
    "type": "object"
  },
  "defer_loading": true
}

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

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

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

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

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

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 подходящих инструментов; Claude может задать limit во входных данных поиска любым целым числом от 1 до 10 000
• Длина шаблона и запроса: максимум 200 символов для шаблонов регулярных выражений и 500 символов для запросов BM25
• Поддержка моделей: см. раздел Совместимость моделей

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

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

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

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

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

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

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

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

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