---
title: Инструмент поиска инструментов
url: https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-search-tool
description: Масштабируйтесь до сотен или тысяч инструментов, позволив Claude искать по вашему каталогу инструментов и загружать только те инструменты, которые ему нужны.
---

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

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

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

Модели, поддерживающие поиск инструментов, перечислены в разделе [Совместимость моделей](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-search-tool#model-compatibility).

<Tip>
  Подробнее о проблемах масштабирования, которые решает поиск инструментов, см. в статье [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use). Загрузка по требованию в поиске инструментов также является примером более общего принципа извлечения «точно в срок» (just-in-time retrieval), описанного в статье [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
</Tip>

Поиск инструментов работает как серверный инструмент, но вы также можете реализовать собственный клиентский поиск инструментов. Подробности см. в разделе [Пользовательская реализация поиска инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-search-tool#custom-tool-search-implementation).

<Note>
  Поделитесь отзывом об этой функции через [форму обратной связи](https://forms.gle/MhcGFFwLxuwnWTkYA).
</Note>

<Note>
  Чтобы узнать, как «zero data retention» (нулевое хранение данных), или ZDR, применяется к этой функции, см. раздел [API и хранение данных](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention).
</Note>

<Warning>
  В Amazon Bedrock серверный поиск инструментов доступен только через [InvokeModel API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_InvokeModel_AnthropicClaude_section.html), а не через Converse API.
</Warning>

<Note>
  В [Claude Platform на AWS](https://platform.claude.com/docs/ru/build-with-claude/claude-platform-on-aws) серверный поиск инструментов работает идентично Claude API. Claude Platform на AWS использует Anthropic Messages API напрямую, поэтому различия между InvokeModel и Converse нет.
</Note>

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

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

| Модель                                                                                                                           | Версии инструмента                                                  |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Claude Fable 5.1 (claude-fable-5-1)                                                                                              | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Mythos 5.1 (claude-mythos-5-1)                                                                                            | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Fable 5 (claude-fable-5)                                                                                                  | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Mythos 5 (claude-mythos-5)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 5.5 (claude-opus-5-5)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 5 (claude-opus-5)                                                                                                    | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 5.5 (claude-sonnet-5-5)                                                                                            | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 5 (claude-sonnet-5)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Haiku 5.5 (claude-haiku-5-5)                                                                                              | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.8 (claude-opus-4-8)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.7 (claude-opus-4-7)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.6 (claude-opus-4-6)                                                                                                | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 4.6 (claude-sonnet-4-6)                                                                                            | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.5 (claude-opus-4-5-20251101)                                                                                       | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) ([устарела](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Haiku 4.5 (claude-haiku-4-5-20251001)                                                                                     | `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 использует запросы на естественном языке для поиска инструментов.

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

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 выбирает из обнаруженных инструментов и вызывает их.

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

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

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{
          "model": "claude-opus-5-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
              }
          ]
      }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-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
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

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

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-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" as const,
          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" as const,
          properties: {
            query: { type: "string" },
            file_types: {
              type: "array",
              items: { type: "string" }
            }
          },
          required: ["query"]
        },
        defer_loading: true
      }
    ]
  });

  console.log(response);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 2048,
      Messages = [
          new() {
              Role = Role.User,
              Content = "What is the weather in San Francisco?"
          }
      ],
      Tools = [
          new ToolUnion(new ToolSearchToolRegex20251119
          {
              Type = ToolSearchToolRegex20251119Type.ToolSearchToolRegex20251119
          }),
          new ToolUnion(new Tool()
          {
              Name = "get_weather",
              Description = "Get the weather at a specific location",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["location"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                      ["unit"] = JsonSerializer.SerializeToElement(new { type = "string", @enum = new[] { "celsius", "fahrenheit" } }),
                  },
                  Required = ["location"],
              },
              DeferLoading = true,
          }),
          new ToolUnion(new Tool()
          {
              Name = "search_files",
              Description = "Search through files in the workspace",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["query"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                      ["file_types"] = JsonSerializer.SerializeToElement(new { type = "array", items = new { type = "string" } }),
                  },
                  Required = ["query"],
              },
              DeferLoading = true,
          }),
      ]
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 2048,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather in San Francisco?")),
  	},
  	Tools: []anthropic.ToolUnionParam{
  		{OfToolSearchToolRegex20251119: &anthropic.ToolSearchToolRegex20251119Param{
  			Type: anthropic.ToolSearchToolRegex20251119TypeToolSearchToolRegex20251119,
  		}},
  		{OfTool: &anthropic.ToolParam{
  			Name:        "get_weather",
  			Description: anthropic.String("Get the weather at a specific location"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"location": map[string]any{"type": "string"},
  					"unit": map[string]any{
  						"type": "string",
  						"enum": []string{"celsius", "fahrenheit"},
  					},
  				},
  				Required: []string{"location"},
  			},
  			DeferLoading: anthropic.Bool(true),
  		}},
  		{OfTool: &anthropic.ToolParam{
  			Name:        "search_files",
  			Description: anthropic.String("Search through files in the workspace"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"query":      map[string]any{"type": "string"},
  					"file_types": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
  				},
  				Required: []string{"query"},
  			},
  			DeferLoading: anthropic.Bool(true),
  		}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.ToolSearchToolRegex20251119;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      InputSchema weatherSchema = InputSchema.builder()
          .properties(JsonValue.from(Map.of(
              "location", Map.of("type", "string"),
              "unit", Map.of(
                  "type", "string",
                  "enum", List.of("celsius", "fahrenheit")
              )
          )))
          .putAdditionalProperty("required", JsonValue.from(List.of("location")))
          .build();

      InputSchema searchSchema = InputSchema.builder()
          .properties(JsonValue.from(Map.of(
              "query", Map.of("type", "string"),
              "file_types", Map.of(
                  "type", "array",
                  "items", Map.of("type", "string")
              )
          )))
          .putAdditionalProperty("required", JsonValue.from(List.of("query")))
          .build();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(2048L)
          .addUserMessage("What is the weather in San Francisco?")
          .addTool(ToolSearchToolRegex20251119.builder()
              .type(ToolSearchToolRegex20251119.Type.TOOL_SEARCH_TOOL_REGEX_20251119)
              .build())
          .addTool(Tool.builder()
              .name("get_weather")
              .description("Get the weather at a specific location")
              .inputSchema(weatherSchema)
              .deferLoading(true)
              .build())
          .addTool(Tool.builder()
              .name("search_files")
              .description("Search through files in the workspace")
              .inputSchema(searchSchema)
              .deferLoading(true)
              .build())
          .build();

      Message response = client.messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 2048,
      messages: [
          ['role' => 'user', 'content' => 'What is the weather in San Francisco?'],
      ],
      model: 'claude-opus-5-5',
      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,
          ],
      ],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: "claude-opus-5-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
      }
    ]
  )

  puts message
  ```
</CodeGroup>

Claude выполняет поиск по каталогу, обнаруживает `get_weather` и вызывает его. Ответ завершается с `stop_reason: "tool_use"`. Выполните обнаруженный инструмент и верните `tool_result`, как описано в разделе [Обработка вызовов инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/handle-tool-calls). В разделе [Формат ответа](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-search-tool#response-format) показаны блоки, которые вы получаете, и что отправлять дальше.

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

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

```json JSON
{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}
```

```json JSON
{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}
```

<Warning>
  **Формат запроса для варианта 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 символов
</Warning>

<Note>
  **Формат запроса для варианта BM25: естественный язык**

  При использовании `tool_search_tool_bm25_20251119` Claude выполняет поиск с помощью запросов на естественном языке. Максимальная длина запроса: 500 символов.
</Note>

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

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

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

Наборы инструментов для использования компьютера и браузера (`computer_toolset_20260801` и `browser_toolset_20260801`) принимают `defer_loading` для каждого входящего в набор инструмента внутри объекта `configs` записи, а не на уровне самой записи; запрос, устанавливающий его на уровне записи, отклоняется. Поскольку набор инструментов откладывается и разворачивается как единое целое, `defer_loading` должен иметь одинаковое значение для каждого включённого участника набора, и когда Claude обнаруживает набор инструментов через поиск, все включённые участники загружаются одновременно. Формат `configs` см. в разделе [Клиентские наборы инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-reference#client-toolsets).

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

Внутренне API исключает отложенные инструменты из префикса системной подсказки. Когда Claude обнаруживает отложенный инструмент через поиск инструментов, API добавляет блок `tool_reference` непосредственно в разговор, а затем разворачивает его в полное определение инструмента перед передачей Claude. Префикс остаётся нетронутым, поэтому «prompt caching» (кэширование подсказок) сохраняется. Грамматика для [строгого режима](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/strict-tool-use) (правила, ограничивающие вывод вызовов инструментов соответствием вашим схемам) строится на основе полного набора инструментов, поэтому `defer_loading` и строгий режим сочетаются без перекомпиляции грамматики.

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

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

```json 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",
        "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](https://platform.claude.com/docs/ru/agents-and-tools/mcp-connector), вы не устанавливаете `defer_loading` для отдельных определений инструментов. Вместо этого установите его один раз в `default_config` записи `mcp_toolset` для всего сервера или для каждого инструмента в его `configs`. См. раздел [Конфигурация набора инструментов MCP](https://platform.claude.com/docs/ru/agents-and-tools/mcp-connector#mcp-toolset-configuration).

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

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

```json 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` таким же образом.

<Note>
  Формат `tool_search_tool_result`, показанный в разделе [Формат ответа](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-search-tool#response-format), — это серверный формат, используемый внутренне встроенным поиском инструментов Anthropic. Для пользовательских клиентских реализаций всегда используйте стандартный формат `tool_result` с блоками содержимого `tool_reference`, как показано в предыдущем примере.
</Note>

Полный пример с использованием эмбеддингов см. в рецепте [поиск инструментов с эмбеддингами](https://platform.claude.com/cookbook/tool-use-tool-search-with-embeddings).

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

<Note>
  [Примеры использования инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) работают с поиском инструментов: когда Claude обнаруживает отложенный инструмент, API разворачивает его `input_examples` вместе с его определением.
</Note>

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

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

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

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

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

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

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

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

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

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

<Accordion title="Ошибка 400: все инструменты отложены">
  **Причина:** вы установили `defer_loading: true` для каждого инструмента, включая инструмент поиска инструментов.

  **Исправление:** удалите `defer_loading` из инструмента поиска инструментов:

  ```json
  {
    "type": "tool_search_tool_regex_20251119",
    "name": "tool_search_tool_regex"
  }
  ```
</Accordion>

<Accordion title="Ошибка 400: отсутствует определение инструмента">
  **Причина:** `tool_reference` указывает на инструмент, отсутствующий в вашем массиве `tools`.

  **Исправление:** убедитесь, что каждый инструмент, который может быть обнаружен, имеет полное определение:

  ```json
  {
    "name": "my_tool",
    "description": "Full description here",
    "input_schema": {
      "type": "object"
    },
    "defer_loading": true
  }
  ```
</Accordion>

<Accordion title="Claude не находит ожидаемые инструменты">
  **Причина:** шаблон регулярного выражения не соответствует имени инструмента, описанию, именам аргументов или описаниям аргументов.

  **Шаги отладки:**

  1. Проверьте имя инструмента, описание, имена аргументов и описания аргументов. Claude выполняет поиск по всем этим полям.
  2. Протестируйте свой шаблон: `import re; re.search(r"your_pattern", "tool_name", re.IGNORECASE)`.
  3. Сопоставление нечувствительно к регистру, поэтому различия в регистре не являются проблемой.
  4. Claude использует широкие шаблоны, такие как `".*weather.*"`, а не точные совпадения.

  **Совет:** добавьте распространённые ключевые слова в описания инструментов, чтобы улучшить их обнаруживаемость.
</Accordion>

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

Чтобы узнать, как `defer_loading` сохраняет кэширование подсказок, см. раздел [Использование инструментов с кэшированием подсказок](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-use-with-prompt-caching).

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

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

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

```sse
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](https://platform.claude.com/docs/ru/build-with-claude/batch-processing).

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

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

* **Максимальное количество отложенных инструментов:** 10 000 инструментов с `defer_loading: true` на запрос
* **Результаты поиска:** каждый поиск по умолчанию возвращает до 5 подходящих инструментов; Claude может задать `limit` во входных данных поиска любым целым числом от 1 до 10 000
* **Длина шаблона и запроса:** максимум 200 символов для шаблонов регулярных выражений и 500 символов для запросов BM25
* **Поддержка моделей:** см. раздел [Совместимость моделей](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-search-tool#model-compatibility)

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

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

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

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

<CardGroup cols={2}>
  <Card title="Инструмент памяти" icon="brain" href="https://platform.claude.com/docs/ru/agents-and-tools/tool-use/memory-tool">
    Позвольте Claude сохранять и извлекать информацию между разговорами, реализовав файловые операции инструмента памяти в вашем приложении.
  </Card>

  <Card title="Справочник по инструментам" icon="book" href="https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-reference">
    Каталог инструментов, предоставляемых Anthropic, и справочник по необязательным свойствам определения инструментов.
  </Card>

  <Card title="Коннектор MCP" icon="link" href="https://platform.claude.com/docs/ru/agents-and-tools/mcp-connector">
    Настройте наборы инструментов MCP с отложенной загрузкой.
  </Card>

  <Card title="Использование инструментов с кэшированием подсказок" icon="bolt" href="https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-use-with-prompt-caching">
    Кэшируйте определения инструментов между ходами и узнайте, что делает ваш кэш недействительным.
  </Card>

  <Card title="Определение инструментов" icon="hammer" href="https://platform.claude.com/docs/ru/agents-and-tools/tool-use/define-tools">
    Задавайте схемы инструментов, пишите эффективные описания и управляйте тем, когда Claude вызывает ваши инструменты.
  </Card>
</CardGroup>