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

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

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

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

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

Вы также можете реализовать поиск инструментов на стороне клиента, возвращая блоки 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 выбирает из обнаруженных инструментов и вызывает их

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

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

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

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

{
  "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 в массиве содержимого:

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

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

Для полного примера с использованием встраиваний см. tool search with embeddings 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 use with prompt caching.

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

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

Ограничения

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

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

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

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

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

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

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

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

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

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

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

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