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

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

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

• Эффективность контекста: Определения инструментов могут занимать огромные части вашего окна контекста (50 инструментов ≈ 10-20K токенов), оставляя меньше места для фактической работы
• Точность выбора инструмента: Способность 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 выбирает из обнаруженных инструментов и вызывает их

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

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

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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
            }
        ]
    }'

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

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

{
  "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) ищут имена инструментов, описания, имена аргументов и описания аргументов.

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

Когда 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. Добавьте заголовок бета-версии "mcp-client-2025-11-20" в ваш запрос API, а затем используйте mcp_toolset с default_config для отложенной загрузки инструментов MCP:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-4-6",
    "max_tokens": 2048,
    "mcp_servers": [
      {
        "type": "url",
        "name": "database-server",
        "url": "https://mcp-db.example.com"
      }
    ],
    "tools": [
      {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
      },
      {
        "type": "mcp_toolset",
        "mcp_server_name": "database-server",
        "default_config": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

Параметры конфигурации MCP:

• default_config.defer_loading: Установить значение по умолчанию для всех инструментов с сервера MCP
• 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. Этот подход позволяет вам использовать более сложные алгоритмы поиска, сохраняя совместимость с системой поиска инструментов.

Для полного примера с использованием встраиваний см. наш кулинарный рецепт поиска инструментов с встраиваниями.

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

Ошибки 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: Служба поиска инструментов временно недоступна

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

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

Поиск инструментов работает с кэшированием подсказок. Добавьте точки разрыва cache_control для оптимизации многооборотных разговоров:

import anthropic

client = anthropic.Anthropic()

# First request with tool search
messages = [{"role": "user", "content": "What's the weather in Seattle?"}]

response1 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=2048,
    messages=messages,
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
            "defer_loading": True,
        },
    ],
)

# Add Claude's response to conversation
messages.append({"role": "assistant", "content": response1.content})

# Second request with cache breakpoint
messages.append(
    {
        "role": "user",
        "content": "What about New York?",
        "cache_control": {"type": "ephemeral"},
    }
)

response2 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=2048,
    messages=messages,
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
            "defer_loading": True,
        },
    ],
)

print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

Система автоматически расширяет блоки 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.

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

Ограничения

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

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

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

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

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

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

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

• Сохраняйте 3-5 наиболее часто используемых инструментов как неотложенные
• Пишите четкие, описательные имена и описания инструментов
• Используйте семантические ключевые слова в описаниях, которые соответствуют тому, как пользователи описывают задачи
• Добавьте раздел системной подсказки, описывающий доступные категории инструментов: "Вы можете искать инструменты для взаимодействия со Slack, GitHub и Jira"
• Отслеживайте, какие инструменты обнаруживает Claude, чтобы уточнить описания

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

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

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