СообщенияИнструменты

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

Масштабируйтесь до сотен или тысяч инструментов, позволяя Claude искать по вашему каталогу инструментов и загружать только те инструменты, которые ему нужны.

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

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

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

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

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

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

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

Модель	Версии инструмента
Claude Fable 5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Mythos 5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Opus 5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Opus 4.8 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Opus 4.7 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Opus 4.6 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Sonnet 4.6 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Opus 4.5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Sonnet 4.5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Haiku 4.5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`

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

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

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

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

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

Вы включаете инструмент поиска инструментов (например, tool_search_tool_regex_20251119 или tool_search_tool_bm25_20251119) в ваш список tools.
Вы предоставляете каждое определение инструмента в массиве tools и устанавливаете defer_loading: true для инструментов, которые не должны загружаться заранее. По крайней мере один инструмент, обычно сам инструмент поиска инструментов, должен оставаться неотложенным.
Изначально контекст Claude содержит только инструмент поиска инструментов и любые неотложенные инструменты.
Когда Claude нужны дополнительные инструменты, он выполняет поиск с помощью инструмента поиска инструментов.
API выполняет поиск и возвращает соответствующие инструменты в виде блоков tool_reference (по умолчанию до 5).
API автоматически разворачивает эти ссылки в полные определения инструментов.
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, как описано в разделе Обработка вызовов инструментов. Раздел Формат ответа показывает блоки, которые вы получаете обратно, и что отправлять дальше.

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

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

JSON

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

JSON

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

Формат запроса варианта Regex: регулярные выражения Python, а не естественный язык

С tool_search_tool_regex_20251119 Claude пишет шаблоны Python re.search(), а не запросы на естественном языке. Сопоставление нечувствительно к регистру. Распространённые шаблоны включают следующие:

"weather": соответствует именам и описаниям инструментов, содержащим «weather»
"get_.*_data": соответствует таким инструментам, как get_user_data и get_weather_data
"database.*query|query.*database": соответствует любому порядку слов

Максимальная длина шаблона: 200 символов

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

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

JSON

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

JSON

{
  "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 в массиве content:

JSON

{
  "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 с ошибкой в теле:

JSON

{
  "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 в ответе не имеет поля поиска инструментов, а определения инструментов, которые поиск загружает в контекст, учитываются как входные токены, как и любое другое определение инструмента.

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

Инструмент памяти

Позвольте Claude сохранять и извлекать информацию между разговорами, реализовав файловые операции инструмента памяти в вашем приложении.

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

Каталог инструментов, предоставляемых Anthropic, и справочник по необязательным свойствам определения инструментов.

Коннектор MCP

Настройте наборы инструментов MCP с отложенной загрузкой.

Использование инструментов с кэшированием подсказок

Кэшируйте определения инструментов между ходами и понимайте, что инвалидирует ваш кэш.

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

Задавайте схемы инструментов, пишите эффективные описания и управляйте тем, когда Claude вызывает ваши инструменты.

Was this page helpful?

СообщенияИнструменты

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

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

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

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

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

Модель	Версии инструмента
Claude Fable 5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Mythos 5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Opus 5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Opus 4.8 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Opus 4.7 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Opus 4.6 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Sonnet 4.6 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Opus 4.5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Sonnet 4.5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Claude Haiku 4.5 ()	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`

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

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

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

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

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

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

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

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

JSON

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

JSON

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

Формат запроса варианта Regex: регулярные выражения Python, а не естественный язык

"weather": соответствует именам и описаниям инструментов, содержащим «weather»
"get_.*_data": соответствует таким инструментам, как get_user_data и get_weather_data
"database.*query|query.*database": соответствует любому порядку слов

Максимальная длина шаблона: 200 символов

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

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

JSON

{
  "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 мог вызывать их без предварительного поиска.

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

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

JSON

{
  "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 точно так же, как при стандартном использовании инструментов.

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

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

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

JSON

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

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

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

Ошибки 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)

JSON

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

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

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

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

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

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+ инструментов).
Ваша библиотека инструментов растёт со временем.

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

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

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

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

Инструмент памяти

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

Коннектор MCP

Настройте наборы инструментов MCP с отложенной загрузкой.

Использование инструментов с кэшированием подсказок

Кэшируйте определения инструментов между ходами и понимайте, что инвалидирует ваш кэш.

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

Was this page helpful?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ошибка 400: все инструменты отложены

Ошибка 400: отсутствует определение инструмента

Claude не находит ожидаемые инструменты

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

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

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

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

Ограничения

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ошибка 400: все инструменты отложены

Ошибка 400: отсутствует определение инструмента

Claude не находит ожидаемые инструменты

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

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

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

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

Ограничения

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ограничения

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ограничения

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

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

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

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