Ferramentas

Ferramenta de busca de ferramentas

Permita que Claude descubra e carregue ferramentas dinamicamente sob demanda, em vez de carregar todas as definições de ferramentas antecipadamente.

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

Esta abordagem resolve dois desafios críticos conforme as bibliotecas de ferramentas crescem:

Eficiência de contexto: As definições de ferramentas podem consumir porções massivas de sua janela de contexto (50 ferramentas ≈ 10-20K tokens), deixando menos espaço para trabalho real
Precisão na seleção de ferramentas: A capacidade do Claude de selecionar corretamente ferramentas se degrada significativamente com mais de 30-50 ferramentas convencionalmente disponíveis

Embora isso seja fornecido como uma ferramenta do lado do servidor, você também pode implementar sua própria funcionalidade de busca de ferramentas do lado do cliente. Veja Implementação de busca de ferramentas personalizada para detalhes.

A ferramenta de busca de ferramentas está atualmente em beta público.

Para usar este recurso, adicione o cabeçalho beta "advanced-tool-use-2025-11-20" às suas solicitações de API.

Entre em contato através do nosso formulário de feedback para compartilhar sua experiência com a ferramenta de busca de ferramentas.

Suporte de plataforma e modelo

Plataforma	Modelos suportados
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

No Amazon Bedrock, a busca de ferramentas do lado do servidor está disponível apenas através da API invoke, não da API converse.

Você também pode implementar busca de ferramentas do lado do cliente retornando blocos tool_reference de sua própria implementação de busca.

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ê ativa a ferramenta de busca de ferramentas:

Você inclui uma ferramenta de busca de ferramentas (por exemplo, tool_search_tool_regex_20251119 ou tool_search_tool_bm25_20251119) em sua lista de ferramentas
Você fornece todas as definições de ferramentas com defer_loading: true para ferramentas que não devem ser carregadas imediatamente
Claude vê apenas a ferramenta de busca de ferramentas e quaisquer ferramentas não-diferidas inicialmente
Quando Claude precisa de ferramentas adicionais, ele busca usando uma ferramenta de busca de ferramentas
A API retorna 3-5 blocos tool_reference mais relevantes
Essas referências são automaticamente expandidas em definições de ferramentas completas
Claude seleciona das ferramentas descobertas e as invoca

Isso mantém sua janela de contexto eficiente enquanto mantém alta precisão na seleção de ferramentas.

Início rápido

Aqui está um exemplo simples com ferramentas diferidas:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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
            }
        ]
    }'

Definição de ferramenta

A ferramenta de busca de ferramentas tem duas variantes:

JSON

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

JSON

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

Formato de consulta da variante Regex: Regex Python, NÃO linguagem natural

Ao usar tool_search_tool_regex_20251119, Claude constrói padrões regex usando a sintaxe re.search() do Python, não consultas em linguagem natural. Padrões comuns:

"weather" - corresponde a nomes/descrições de ferramentas contendo "weather"
"get_.*_data" - corresponde a ferramentas como get_user_data, get_weather_data
"database.*query|query.*database" - padrões OR para flexibilidade
"(?i)slack" - busca insensível a maiúsculas/minúsculas

Comprimento máximo de consulta: 200 caracteres

Formato de consulta da variante BM25: Linguagem natural

Ao usar tool_search_tool_bm25_20251119, Claude usa consultas em linguagem natural para buscar ferramentas.

Carregamento diferido de ferramentas

Marque ferramentas para carregamento sob demanda adicionando defer_loading: true:

JSON

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}

Pontos-chave:

Ferramentas sem defer_loading são carregadas no contexto imediatamente
Ferramentas com defer_loading: true são carregadas apenas quando Claude as descobre via busca
A ferramenta de busca de ferramentas em si nunca deve ter defer_loading: true
Mantenha suas 3-5 ferramentas mais usadas como não-diferidas para desempenho ideal

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

Formato de resposta

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

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": {
        "query": "weather"
      }
    },
    {
      "type": "tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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: Indica que Claude está invocando a ferramenta de busca de ferramentas
tool_result com tool_reference: Os resultados da busca contendo referências a ferramentas descobertas
tool_use: Claude invocando a ferramenta descoberta

Os blocos tool_reference são automaticamente expandidos em definições de ferramentas completas antes de serem mostrados ao Claude. Você não precisa lidar com essa expansão você mesmo. Isso acontece automaticamente na API desde que você forneça todas as definições de ferramentas correspondentes no parâmetro tools.

Integração MCP

A ferramenta de busca de ferramentas funciona com servidores MCP. Adicione o cabeçalho beta "mcp-client-2025-11-20" à sua solicitação de API e, em seguida, use mcp_tool_set com default_configs para diferir o carregamento de ferramentas MCP:

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

Opções de configuração MCP:

default_configs.defer_loading: Define padrão para todas as ferramentas do servidor MCP
configs: Substitui padrões para ferramentas específicas por nome
Combine múltiplos servidores MCP com busca de ferramentas para bibliotecas de ferramentas massivas

Implementação de busca de ferramentas personalizada

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:

JSON

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

Toda ferramenta referenciada deve ter uma definição de ferramenta correspondente no parâmetro tools de nível superior com defer_loading: true. Esta abordagem permite que você use algoritmos de busca mais sofisticados enquanto mantém compatibilidade com o sistema de busca de ferramentas.

Para um exemplo completo usando embeddings, veja nosso cookbook de busca de ferramentas com embeddings.

Tratamento de erros

A ferramenta de busca de ferramentas não é compatível com exemplos de uso de ferramentas. Se você precisar fornecer exemplos de uso de ferramentas, use chamada de ferramentas padrão sem busca de ferramentas.

Erros HTTP (status 400)

Esses erros impedem que a solicitação seja processada:

Todas as ferramentas diferidas:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

Definição de ferramenta ausente:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

Erros de resultado de ferramenta (status 200)

Erros durante a execução de ferramentas retornam uma resposta 200 com informações de erro no corpo:

JSON

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

Códigos de erro:

too_many_requests: Limite de taxa excedido para operações de busca de ferramentas
invalid_pattern: Padrão regex malformado
pattern_too_long: Padrão excede limite de 200 caracteres
unavailable: Serviço de busca de ferramentas temporariamente indisponível

Erros comuns

Cache de prompt

A busca de ferramentas funciona com cache de prompt. Adicione pontos de interrupção cache_control para otimizar conversas multi-turno:

Python

import anthropic

client = anthropic.Anthropic()

# Primeira solicitação com busca de ferramentas
messages = [
    {
        "role": "user",
        "content": "What's the weather in Seattle?"
    }
]

response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

# Adicione a resposta do Claude à conversa
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Segunda solicitação com ponto de interrupção de cache
messages.append({
    "role": "user",
    "content": "What about New York?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

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

O sistema automaticamente expande blocos tool_reference em todo o histórico de conversa, então Claude pode reutilizar ferramentas descobertas em turnos subsequentes sem re-buscar.

Streaming

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

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

// Consulta de busca transmitida
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// Pausa enquanto a busca é executada

// Resultados de busca transmitidos
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}

// Claude continua com ferramentas descobertas

Solicitações em lote

Você pode incluir a ferramenta de busca de ferramentas na API de Lotes de Mensagens. Operações de busca de ferramentas através da API de Lotes de Mensagens são precificadas da mesma forma que aquelas em solicitações regulares da API de Mensagens.

Limites e melhores práticas

Limites

Máximo de ferramentas: 10.000 ferramentas em seu catálogo
Resultados de busca: Retorna 3-5 ferramentas mais relevantes por busca
Comprimento de padrão: Máximo de 200 caracteres para padrões regex
Suporte de modelo: Apenas Sonnet 4.0+, Opus 4.0+ (sem Haiku)

Quando usar busca de ferramentas

Bons casos de uso:

10+ ferramentas disponíveis em seu sistema
Definições de ferramentas consumindo >10K tokens
Experimentando problemas de precisão na seleção de ferramentas com grandes conjuntos de ferramentas
Construindo sistemas alimentados por MCP com múltiplos servidores (200+ ferramentas)
Biblioteca de ferramentas crescendo ao longo do tempo

Quando chamada de ferramentas tradicional pode ser melhor:

Menos de 10 ferramentas no total
Todas as ferramentas são frequentemente usadas em cada solicitação
Definições de ferramentas muito pequenas (<100 tokens no total)

Dicas de otimização

Mantenha 3-5 ferramentas mais usadas como não-diferidas
Escreva nomes e descrições de ferramentas claros e descritivos
Use palavras-chave semânticas em descrições que correspondam a como os usuários descrevem tarefas
Adicione uma seção de prompt do sistema descrevendo categorias de ferramentas disponíveis: "Você pode buscar ferramentas para interagir com Slack, GitHub e Jira"
Monitore quais ferramentas Claude descobre para refinar descrições

Uso e preços

O uso da ferramenta de busca de ferramentas é rastreado no objeto de uso da resposta:

JSON

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

Para informações de preços atuais, veja a página de preços.

Ferramentas

Ferramenta de busca de ferramentas

Permita que Claude descubra e carregue ferramentas dinamicamente sob demanda, em vez de carregar todas as definições de ferramentas antecipadamente.

Esta abordagem resolve dois desafios críticos conforme as bibliotecas de ferramentas crescem:

Eficiência de contexto: As definições de ferramentas podem consumir porções massivas de sua janela de contexto (50 ferramentas ≈ 10-20K tokens), deixando menos espaço para trabalho real
Precisão na seleção de ferramentas: A capacidade do Claude de selecionar corretamente ferramentas se degrada significativamente com mais de 30-50 ferramentas convencionalmente disponíveis

A ferramenta de busca de ferramentas está atualmente em beta público.

Para usar este recurso, adicione o cabeçalho beta "advanced-tool-use-2025-11-20" às suas solicitações de API.

Entre em contato através do nosso formulário de feedback para compartilhar sua experiência com a ferramenta de busca de ferramentas.

Suporte de plataforma e modelo

Plataforma	Modelos suportados
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

No Amazon Bedrock, a busca de ferramentas do lado do servidor está disponível apenas através da API invoke, não da API converse.

Você também pode implementar busca de ferramentas do lado do cliente retornando blocos tool_reference de sua própria implementação de busca.

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ê ativa a ferramenta de busca de ferramentas:

Você inclui uma ferramenta de busca de ferramentas (por exemplo, tool_search_tool_regex_20251119 ou tool_search_tool_bm25_20251119) em sua lista de ferramentas
Você fornece todas as definições de ferramentas com defer_loading: true para ferramentas que não devem ser carregadas imediatamente
Claude vê apenas a ferramenta de busca de ferramentas e quaisquer ferramentas não-diferidas inicialmente
Quando Claude precisa de ferramentas adicionais, ele busca usando uma ferramenta de busca de ferramentas
A API retorna 3-5 blocos tool_reference mais relevantes
Essas referências são automaticamente expandidas em definições de ferramentas completas
Claude seleciona das ferramentas descobertas e as invoca

Isso mantém sua janela de contexto eficiente enquanto mantém alta precisão na seleção de ferramentas.

Início rápido

Aqui está um exemplo simples com ferramentas diferidas:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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
            }
        ]
    }'

Definição de ferramenta

A ferramenta de busca de ferramentas tem duas variantes:

JSON

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

JSON

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

Formato de consulta da variante Regex: Regex Python, NÃO linguagem natural

Ao usar tool_search_tool_regex_20251119, Claude constrói padrões regex usando a sintaxe re.search() do Python, não consultas em linguagem natural. Padrões comuns:

"weather" - corresponde a nomes/descrições de ferramentas contendo "weather"
"get_.*_data" - corresponde a ferramentas como get_user_data, get_weather_data
"database.*query|query.*database" - padrões OR para flexibilidade
"(?i)slack" - busca insensível a maiúsculas/minúsculas

Comprimento máximo de consulta: 200 caracteres

Formato de consulta da variante BM25: Linguagem natural

Ao usar tool_search_tool_bm25_20251119, Claude usa consultas em linguagem natural para buscar ferramentas.

Carregamento diferido de ferramentas

Marque ferramentas para carregamento sob demanda adicionando defer_loading: true:

JSON

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}

Pontos-chave:

Ferramentas sem defer_loading são carregadas no contexto imediatamente
Ferramentas com defer_loading: true são carregadas apenas quando Claude as descobre via busca
A ferramenta de busca de ferramentas em si nunca deve ter defer_loading: true
Mantenha suas 3-5 ferramentas mais usadas como não-diferidas para desempenho ideal

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

Formato de resposta

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

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": {
        "query": "weather"
      }
    },
    {
      "type": "tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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: Indica que Claude está invocando a ferramenta de busca de ferramentas
tool_result com tool_reference: Os resultados da busca contendo referências a ferramentas descobertas
tool_use: Claude invocando a ferramenta descoberta

Integração MCP

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

Opções de configuração MCP:

default_configs.defer_loading: Define padrão para todas as ferramentas do servidor MCP
configs: Substitui padrões para ferramentas específicas por nome
Combine múltiplos servidores MCP com busca de ferramentas para bibliotecas de ferramentas massivas

Implementação de busca de ferramentas personalizada

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:

JSON

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

Para um exemplo completo usando embeddings, veja nosso cookbook de busca de ferramentas com embeddings.

Tratamento de erros

Erros HTTP (status 400)

Esses erros impedem que a solicitação seja processada:

Todas as ferramentas diferidas:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

Definição de ferramenta ausente:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

Erros de resultado de ferramenta (status 200)

Erros durante a execução de ferramentas retornam uma resposta 200 com informações de erro no corpo:

JSON

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

Códigos de erro:

too_many_requests: Limite de taxa excedido para operações de busca de ferramentas
invalid_pattern: Padrão regex malformado
pattern_too_long: Padrão excede limite de 200 caracteres
unavailable: Serviço de busca de ferramentas temporariamente indisponível

Erros comuns

Cache de prompt

A busca de ferramentas funciona com cache de prompt. Adicione pontos de interrupção cache_control para otimizar conversas multi-turno:

Python

import anthropic

client = anthropic.Anthropic()

# Primeira solicitação com busca de ferramentas
messages = [
    {
        "role": "user",
        "content": "What's the weather in Seattle?"
    }
]

response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

# Adicione a resposta do Claude à conversa
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Segunda solicitação com ponto de interrupção de cache
messages.append({
    "role": "user",
    "content": "What about New York?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

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

O sistema automaticamente expande blocos tool_reference em todo o histórico de conversa, então Claude pode reutilizar ferramentas descobertas em turnos subsequentes sem re-buscar.

Streaming

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

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

// Consulta de busca transmitida
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// Pausa enquanto a busca é executada

// Resultados de busca transmitidos
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}

// Claude continua com ferramentas descobertas

Solicitações em lote

Limites e melhores práticas

Limites

Máximo de ferramentas: 10.000 ferramentas em seu catálogo
Resultados de busca: Retorna 3-5 ferramentas mais relevantes por busca
Comprimento de padrão: Máximo de 200 caracteres para padrões regex
Suporte de modelo: Apenas Sonnet 4.0+, Opus 4.0+ (sem Haiku)

Quando usar busca de ferramentas

Bons casos de uso:

10+ ferramentas disponíveis em seu sistema
Definições de ferramentas consumindo >10K tokens
Experimentando problemas de precisão na seleção de ferramentas com grandes conjuntos de ferramentas
Construindo sistemas alimentados por MCP com múltiplos servidores (200+ ferramentas)
Biblioteca de ferramentas crescendo ao longo do tempo

Quando chamada de ferramentas tradicional pode ser melhor:

Menos de 10 ferramentas no total
Todas as ferramentas são frequentemente usadas em cada solicitação
Definições de ferramentas muito pequenas (<100 tokens no total)

Dicas de otimização

Mantenha 3-5 ferramentas mais usadas como não-diferidas
Escreva nomes e descrições de ferramentas claros e descritivos
Use palavras-chave semânticas em descrições que correspondam a como os usuários descrevem tarefas
Adicione uma seção de prompt do sistema descrevendo categorias de ferramentas disponíveis: "Você pode buscar ferramentas para interagir com Slack, GitHub e Jira"
Monitore quais ferramentas Claude descobre para refinar descrições

Uso e preços

O uso da ferramenta de busca de ferramentas é rastreado no objeto de uso da resposta:

JSON

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

Para informações de preços atuais, veja a página de preços.

Suporte de plataforma e modelo

Como a busca de ferramentas funciona

Início rápido

Definição de ferramenta

Carregamento diferido de ferramentas

Formato de resposta

Entendendo a resposta

Integração MCP

Implementação de busca de ferramentas personalizada

Tratamento de erros

Erros HTTP (status 400)

Erros de resultado de ferramenta (status 200)

Erros comuns

Erro 400: Todas as ferramentas estão diferidas

Erro 400: Definição de ferramenta ausente

Claude não encontra ferramentas esperadas

Cache de prompt

Streaming

Solicitações em lote

Limites e melhores práticas

Limites

Quando usar busca de ferramentas

Dicas de otimização

Uso e preços

Suporte de plataforma e modelo

Como a busca de ferramentas funciona

Início rápido

Definição de ferramenta

Carregamento diferido de ferramentas

Formato de resposta

Entendendo a resposta

Integração MCP

Implementação de busca de ferramentas personalizada

Tratamento de erros

Erros HTTP (status 400)

Erros de resultado de ferramenta (status 200)

Erros comuns

Erro 400: Todas as ferramentas estão diferidas

Erro 400: Definição de ferramenta ausente

Claude não encontra ferramentas esperadas

Cache de prompt

Streaming

Solicitações em lote

Limites e melhores práticas

Limites

Quando usar busca de ferramentas

Dicas de otimização

Uso e preços