---
title: Ferramenta de busca de ferramentas
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool
description: Escale para centenas ou milhares de ferramentas permitindo que Claude pesquise seu catálogo de ferramentas e carregue apenas as ferramentas de que precisa.
---

A "tool search tool" (ferramenta de busca de ferramentas) permite que Claude trabalhe com centenas ou milhares de ferramentas, descobrindo-as e carregando-as sob demanda. Em vez de carregar todas as definições de ferramentas na "context window" (janela de contexto) antecipadamente, Claude pesquisa seu catálogo de ferramentas (incluindo nomes de ferramentas, descrições, nomes de argumentos e descrições de argumentos) e carrega apenas as ferramentas de que precisa.

Carregar todas as definições de ferramentas antecipadamente causa dois problemas à medida que uma biblioteca de ferramentas cresce:

* **Inchaço de contexto:** Uma configuração típica com múltiplos servidores (GitHub, Slack, Sentry, Grafana e Splunk) pode consumir \~55k tokens em definições antes que Claude faça qualquer trabalho. A busca de ferramentas normalmente reduz isso em mais de 85 por cento, carregando apenas as 3–5 ferramentas de que Claude precisa para uma determinada solicitação.
* **Precisão na seleção de ferramentas:** A capacidade de Claude de escolher a ferramenta certa se degrada quando você ultrapassa 30–50 ferramentas disponíveis. Como a busca de ferramentas carrega apenas um conjunto focado de ferramentas relevantes sob demanda, a precisão da seleção permanece alta mesmo entre milhares de ferramentas.

Para os modelos que suportam a busca de ferramentas, consulte [Compatibilidade de modelos](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool#model-compatibility).

<Tip>
  Para contexto sobre os desafios de escala que a busca de ferramentas resolve, consulte [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use). O carregamento sob demanda da busca de ferramentas também é uma instância do princípio mais amplo de recuperação just-in-time descrito em [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
</Tip>

A busca de ferramentas é executada como uma ferramenta do lado do servidor, mas você também pode implementar sua própria busca de ferramentas do lado do cliente. Consulte [Implementação personalizada de busca de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool#custom-tool-search-implementation) para detalhes.

<Note>
  Compartilhe feedback sobre este recurso por meio do [formulário de feedback](https://forms.gle/MhcGFFwLxuwnWTkYA).
</Note>

<Note>
  Para saber como a "zero data retention" (retenção zero de dados), ou ZDR, se aplica a este recurso, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention).
</Note>

<Warning>
  No Amazon Bedrock, a busca de ferramentas do lado do servidor está disponível apenas por meio da [API InvokeModel](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_InvokeModel_AnthropicClaude_section.html), não da API Converse.
</Warning>

<Note>
  Na [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), a busca de ferramentas do lado do servidor funciona de forma idêntica à Claude API. A Claude Platform on AWS usa a Messages API da Anthropic diretamente, portanto não há distinção entre InvokeModel e Converse.
</Note>

## Compatibilidade de modelos

Ambas as variantes de busca de ferramentas estão disponíveis nos seguintes modelos:

| Modelo                                                                                                                                   | Versões da ferramenta                                               |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 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) ([descontinuado](https://platform.claude.com/docs/pt-BR/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 e modelos anteriores não oferecem suporte à ferramenta de busca de ferramentas.

## Como a busca de ferramentas funciona

Existem duas variantes de busca de ferramentas:

* **Regex** (`tool_search_tool_regex_20251119`): Claude constrói padrões regex para buscar ferramentas.
* **BM25** (`tool_search_tool_bm25_20251119`): Claude usa consultas em linguagem natural para buscar ferramentas.

Quando você habilita a ferramenta de busca de ferramentas:

1. Você inclui uma ferramenta de busca de ferramentas (por exemplo, `tool_search_tool_regex_20251119` ou `tool_search_tool_bm25_20251119`) na sua lista `tools`.
2. Você fornece todas as definições de ferramentas no array `tools` e define `defer_loading: true` nas ferramentas que não devem ser carregadas antecipadamente. Pelo menos uma ferramenta, normalmente a própria ferramenta de busca de ferramentas, deve permanecer não adiada.
3. Inicialmente, o contexto de Claude contém apenas a ferramenta de busca de ferramentas e quaisquer ferramentas não adiadas.
4. Quando Claude precisa de ferramentas adicionais, ele pesquisa usando uma ferramenta de busca de ferramentas.
5. A API executa a busca e retorna as ferramentas correspondentes como blocos `tool_reference` (até 5 por padrão; Claude pode definir um `limit` na entrada da busca).
6. A API expande automaticamente essas referências em definições completas de ferramentas.
7. Claude seleciona entre as ferramentas descobertas e as chama.

## Início rápido

O exemplo a seguir inclui a ferramenta de busca de ferramentas e duas ferramentas adiadas:

<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 pesquisa o catálogo, descobre `get_weather` e a chama. A resposta termina com `stop_reason: "tool_use"`. Execute a ferramenta descoberta e retorne um `tool_result` como em [Lidar com chamadas de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls). [Formato da resposta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool#response-format) mostra os blocos que você recebe de volta e o que enviar em seguida.

## Definição da ferramenta

A ferramenta de busca de ferramentas tem duas variantes:

```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>
  **Formato de consulta da variante regex: regex Python, não linguagem natural**

  Com `tool_search_tool_regex_20251119`, Claude escreve padrões Python `re.search()`, não consultas em linguagem natural. A correspondência não diferencia maiúsculas de minúsculas. Padrões comuns incluem os seguintes:

  * `"weather"`: corresponde a nomes e descrições de ferramentas contendo "weather"
  * `"get_.*_data"`: corresponde a ferramentas como `get_user_data` e `get_weather_data`
  * `"database.*query|query.*database"`: corresponde a qualquer ordem das palavras

  Comprimento máximo do padrão: 200 caracteres
</Warning>

<Note>
  **Formato de consulta da variante BM25: linguagem natural**

  Com `tool_search_tool_bm25_20251119`, Claude pesquisa com consultas em linguagem natural. Comprimento máximo da consulta: 500 caracteres.
</Note>

### Carregamento adiado de ferramentas

Marque ferramentas para carregamento sob demanda adicionando `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` controla o que entra na janela de contexto, não o que você envia na solicitação:

* Você ainda envia a definição completa de cada ferramenta no array `tools` em cada solicitação, incluindo as adiadas. A API precisa delas no lado do servidor para executar a busca e expandir os blocos `tool_reference`.
* Ferramentas sem `defer_loading` são carregadas no contexto imediatamente.
* Ferramentas com `defer_loading: true` são carregadas apenas quando Claude as descobre por meio da busca.
* Nunca defina `defer_loading: true` na própria ferramenta de busca de ferramentas.
* Mantenha suas 3–5 ferramentas mais usadas como não adiadas para que Claude possa chamá-las sem pesquisar primeiro.

Os conjuntos de ferramentas de uso de computador e uso de navegador (`computer_toolset_20260801` e `browser_toolset_20260801`) recebem `defer_loading` por ferramenta membro dentro do objeto `configs` da entrada, não na própria entrada; uma solicitação que o define no nível da entrada é rejeitada. Como um conjunto de ferramentas é adiado e expandido como uma unidade, `defer_loading` deve resolver para o mesmo valor em cada membro habilitado e, quando Claude descobre o conjunto de ferramentas por meio da busca, todos os membros habilitados são carregados de uma vez. Consulte [Conjuntos de ferramentas do cliente](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets) para o formato de `configs`.

Ambas as variantes de busca de ferramentas (`regex` e `bm25`) pesquisam nomes de ferramentas, descrições, nomes de argumentos e descrições de argumentos.

Internamente, a API exclui as ferramentas adiadas do prefixo do prompt do sistema. Quando Claude descobre uma ferramenta adiada por meio da busca de ferramentas, a API anexa um bloco `tool_reference` inline na conversa e, em seguida, o expande na definição completa da ferramenta antes de passá-lo para Claude. O prefixo permanece intocado, portanto o "prompt caching" (cache de prompt) é preservado. A gramática do [modo estrito](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use) (as regras que restringem a saída de chamadas de ferramentas para corresponder aos seus esquemas) é construída a partir do conjunto completo de ferramentas, portanto `defer_loading` e o modo estrito se combinam sem recompilação da gramática.

## Formato da resposta

Quando Claude usa a ferramenta de busca de ferramentas, a resposta inclui os seguintes tipos de bloco:

```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"
}
```

### Entendendo a resposta

* **`server_tool_use`:** a chamada de Claude à ferramenta de busca de ferramentas. A busca é executada nos servidores da Anthropic. Nunca retorne um `tool_result` para seu ID `srvtoolu_...`. O `input` contém a busca (`pattern` para a variante regex, `query` para BM25) e pode incluir um `limit` opcional, um inteiro de 1 a 10.000 que limita quantas ferramentas correspondentes a busca retorna (padrão: 5).
* **`tool_search_tool_result`:** os resultados da busca, em um objeto `tool_search_tool_search_result` aninhado. Mantenha-o no histórico de mensagens como está.
* **`tool_references`:** um array de objetos `tool_reference` apontando para as ferramentas descobertas. A API os expande para Claude. Você nunca os expande por conta própria.
* **`tool_use`:** a chamada de Claude a uma ferramenta descoberta. Execute-a e retorne um `tool_result` exatamente como no uso de ferramentas padrão.

A API expande automaticamente os blocos `tool_reference` em definições completas de ferramentas antes de mostrá-los a Claude. Você não precisa lidar com essa expansão por conta própria, desde que forneça todas as definições de ferramentas correspondentes no parâmetro `tools`.

### Continuando a conversa

Na próxima solicitação, passe o conteúdo do assistente de volta sem alterações, incluindo os blocos `server_tool_use` e `tool_search_tool_result`. Adicione seu `tool_result` para a ferramenta descoberta em uma mensagem do usuário e envie o mesmo array `tools`: a ferramenta de busca mais todas as definições adiadas. Não retorne um `tool_result` para o ID `srvtoolu_...`: a API rejeita a solicitação. A API expande os blocos `tool_reference` em todo o histórico da conversa, portanto Claude pode reutilizar ferramentas descobertas em turnos posteriores sem pesquisar novamente. Uma busca que não corresponde a nada retorna um `tool_search_tool_search_result` com um array `tool_references` vazio, não um erro.

## Integração com MCP

Se suas ferramentas vêm de servidores MCP por meio do [conector MCP](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector), você não define `defer_loading` em definições de ferramentas individuais. Em vez disso, defina-o uma vez no `default_config` da entrada `mcp_toolset` para o servidor inteiro, ou por ferramenta em seus `configs`. Consulte [Configuração do conjunto de ferramentas MCP](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector#mcp-toolset-configuration).

## Implementação personalizada de busca de ferramentas

Você pode implementar sua própria lógica de busca de ferramentas (por exemplo, usando embeddings ou busca semântica) retornando blocos `tool_reference` de uma ferramenta personalizada. Quando Claude chama sua ferramenta de busca personalizada, retorne um `tool_result` padrão com blocos `tool_reference` no array de conteúdo:

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

Cada ferramenta referenciada deve ter uma definição de ferramenta correspondente no parâmetro `tools` de nível superior, normalmente com `defer_loading: true`. Isso permite que você use métodos de busca que as variantes integradas não fornecem, como recuperação baseada em embeddings, e a API expande os blocos `tool_reference` retornados da mesma forma.

<Note>
  O formato `tool_search_tool_result` mostrado na seção [Formato da resposta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool#response-format) é o formato do lado do servidor usado internamente pela busca de ferramentas integrada da Anthropic. Para implementações personalizadas do lado do cliente, sempre use o formato `tool_result` padrão com blocos de conteúdo `tool_reference`, como mostrado no exemplo anterior.
</Note>

Para um exemplo completo usando embeddings, consulte a receita [busca de ferramentas com embeddings](https://platform.claude.com/cookbook/tool-use-tool-search-with-embeddings).

## Tratamento de erros

<Note>
  [Exemplos de uso de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) funcionam com a busca de ferramentas: quando Claude descobre uma ferramenta adiada, a API expande seus `input_examples` junto com sua definição.
</Note>

### Erros HTTP (status 400)

Esses erros impedem a API de processar a solicitação:

**Todas as ferramentas adiadas:**

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

**Definição de ferramenta ausente:**

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

### Erros de resultado de ferramenta (status 200)

Quando uma operação de busca de ferramentas falha durante a execução, a API retorna uma resposta 200 com o erro no corpo:

```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"
  }
}
```

O campo `error_code` tem quatro valores possíveis:

* `invalid_tool_input`: a entrada da busca era inválida, por exemplo um padrão regex malformado ou um padrão acima do limite de 200 caracteres
* `unavailable`: a busca não pôde ser executada, por exemplo porque expirou o tempo limite ou o serviço estava indisponível
* `too_many_requests`: limite de taxa excedido para operações de busca de ferramentas
* `execution_time_exceeded`: a busca excedeu seu limite de tempo de execução

### Erros comuns

<Accordion title="Erro 400: todas as ferramentas estão adiadas">
  **Causa:** Você definiu `defer_loading: true` em todas as ferramentas, incluindo a ferramenta de busca de ferramentas.

  **Correção:** Remova `defer_loading` da ferramenta de busca de ferramentas:

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

<Accordion title="Erro 400: definição de ferramenta ausente">
  **Causa:** Um `tool_reference` aponta para uma ferramenta que não está no seu array `tools`.

  **Correção:** Garanta que toda ferramenta que possa ser descoberta tenha uma definição completa:

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

<Accordion title="Claude não encontra as ferramentas esperadas">
  **Causa:** O padrão regex não corresponde ao nome, à descrição, aos nomes de argumentos ou às descrições de argumentos da ferramenta.

  **Etapas de depuração:**

  1. Verifique o nome da ferramenta, a descrição, os nomes de argumentos e as descrições de argumentos. Claude pesquisa todos esses campos.
  2. Teste seu padrão: `import re; re.search(r"your_pattern", "tool_name", re.IGNORECASE)`.
  3. A correspondência não diferencia maiúsculas de minúsculas, portanto diferenças de capitalização não são o problema.
  4. Claude usa padrões amplos como `".*weather.*"`, não correspondências exatas.

  **Dica:** Adicione palavras-chave comuns às descrições das ferramentas para melhorar a capacidade de descoberta.
</Accordion>

## Cache de prompt

Para saber como `defer_loading` preserva o cache de prompt, consulte [Uso de ferramentas com cache de prompt](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-use-with-prompt-caching).

Uma ferramenta com `defer_loading: true` não pode também ter `cache_control`: a API retorna um 400. Coloque o ponto de interrupção do cache em uma ferramenta não adiada.

## Streaming

Com o streaming habilitado, você receberá eventos de busca de ferramentas como parte do stream:

```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
```

## Solicitações em lote

Você pode incluir a ferramenta de busca de ferramentas na [Messages Batches API](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing).

## Limites e melhores práticas

### Limites

* **Máximo de ferramentas adiadas:** 10.000 ferramentas com `defer_loading: true` por solicitação
* **Resultados da busca:** cada busca retorna até 5 ferramentas correspondentes por padrão; Claude pode definir `limit` na entrada da busca como qualquer inteiro de 1 a 10.000
* **Comprimento de padrão e consulta:** máximo de 200 caracteres para padrões regex e 500 caracteres para consultas BM25
* **Suporte de modelos:** consulte [Compatibilidade de modelos](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool#model-compatibility)

### Quando usar a busca de ferramentas

Use a busca de ferramentas quando qualquer uma das seguintes condições se aplicar:

* Você tem 10 ou mais ferramentas disponíveis.
* Suas definições de ferramentas consomem mais de 10k tokens.
* A precisão da seleção de ferramentas cai à medida que seu conjunto de ferramentas cresce.
* Você agrega múltiplos servidores MCP (200+ ferramentas).
* Sua biblioteca de ferramentas cresce ao longo do tempo.

A chamada de ferramentas padrão, sem busca de ferramentas, é mais adequada quando você tem menos de 10 ferramentas, todas as ferramentas são usadas em todas as solicitações ou suas definições de ferramentas são pequenas (menos de 100 tokens no total).

### Dicas de otimização

* Mantenha suas 3–5 ferramentas mais usadas como não adiadas.
* Escreva nomes e descrições de ferramentas claros e descritivos.
* Use namespaces consistentes nos nomes das ferramentas: prefixe por serviço ou recurso (por exemplo, `github_`, `slack_`) para que uma única busca corresponda ao grupo inteiro.
* Use palavras-chave nas descrições que correspondam à forma como os usuários descrevem as tarefas.
* Adicione uma seção no prompt do sistema descrevendo as categorias de ferramentas disponíveis: "You can search for tools to interact with Slack, GitHub, and Jira."
* Monitore quais ferramentas Claude descobre para refinar suas descrições.

## Uso

A busca de ferramentas não é medida como uma ferramenta de servidor separada. O objeto `usage.server_tool_use` da resposta não tem um campo de busca de ferramentas, e as definições de ferramentas que a busca carrega no contexto contam como tokens de entrada, como qualquer outra definição de ferramenta.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Ferramenta de memória" icon="brain" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/memory-tool">
    Permita que Claude armazene e recupere informações entre conversas implementando as operações de arquivo da ferramenta de memória na sua aplicação.
  </Card>

  <Card title="Referência de ferramentas" icon="book" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference">
    Diretório de ferramentas fornecidas pela Anthropic e referência para propriedades opcionais de definição de ferramentas.
  </Card>

  <Card title="Conector MCP" icon="link" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector">
    Configure conjuntos de ferramentas MCP com carregamento adiado.
  </Card>

  <Card title="Uso de ferramentas com cache de prompt" icon="bolt" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-use-with-prompt-caching">
    Armazene em cache definições de ferramentas entre turnos e entenda o que invalida seu cache.
  </Card>

  <Card title="Definir ferramentas" icon="hammer" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools">
    Especifique esquemas de ferramentas, escreva descrições eficazes e controle quando Claude chama suas ferramentas.
  </Card>
</CardGroup>