Ferramenta de busca de ferramentas

A ferramenta de busca de ferramentas permite que o Claude trabalhe com centenas ou milhares de ferramentas, descobrindo-as e carregando-as dinamicamente sob demanda. Em vez de carregar todas as definições de ferramentas na "context window" (janela de contexto) antecipadamente, o 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.

Essa abordagem resolve dois problemas que se agravam rapidamente à medida que as bibliotecas de ferramentas crescem:

• Inchaço de contexto: As definições de ferramentas consomem seu orçamento de contexto rapidamente. Uma configuração típica com múltiplos servidores (GitHub, Slack, Sentry, Grafana, Splunk) pode consumir cerca de 55 mil tokens em definições antes que o Claude faça qualquer trabalho real. A busca de ferramentas normalmente reduz isso em mais de 85%, carregando apenas as 3–5 ferramentas de que o Claude realmente precisa para uma determinada solicitação.
• Precisão na seleção de ferramentas: A capacidade do Claude de escolher corretamente a ferramenta certa degrada significativamente quando você excede 30–50 ferramentas disponíveis. Ao apresentar um conjunto focado de ferramentas relevantes sob demanda, a busca de ferramentas mantém a precisão de seleção alta mesmo com milhares de ferramentas.

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



Como a busca de ferramentas funciona

Existem duas variantes de busca de ferramentas:

• Regex (tool_search_tool_regex_20251119): O Claude constrói padrões regex para buscar ferramentas
• BM25 (tool_search_tool_bm25_20251119): O 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 de ferramentas.
2. Você fornece todas as definições de ferramentas com defer_loading: true para ferramentas que não devem ser carregadas imediatamente.
3. O Claude vê inicialmente apenas a ferramenta de busca de ferramentas e quaisquer ferramentas não adiadas.
4. Quando o Claude precisa de ferramentas adicionais, ele pesquisa usando uma ferramenta de busca de ferramentas.
5. A API retorna de 3 a 5 blocos tool_reference mais relevantes.
6. Essas referências são automaticamente expandidas em definições completas de ferramentas.
7. O Claude seleciona entre as ferramentas descobertas e as chama.

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 adiadas:

client = anthropic.Anthropic()

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



Definição da ferramenta

A ferramenta de busca de ferramentas tem duas variantes:

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

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



Carregamento adiado de ferramentas

Marque ferramentas para carregamento sob demanda adicionando defer_loading: true:

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

Pontos principais:

• Ferramentas sem defer_loading são carregadas no contexto imediatamente
• Ferramentas com defer_loading: true são carregadas apenas quando o Claude as descobre através da busca
• A própria ferramenta de busca de ferramentas nunca deve ter defer_loading: true
• Mantenha suas 3-5 ferramentas mais usadas como não adiadas para desempenho ideal

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

Como o adiamento funciona internamente: Ferramentas adiadas não são incluídas no prefixo do prompt do sistema. Quando o modelo descobre uma ferramenta adiada através 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á-la ao Claude. O prefixo permanece intocado, então o cache de prompt é preservado. A gramática para o modo estrito (as regras que restringem a saída de chamadas de ferramentas para corresponder aos seus schemas) é construída a partir do conjunto completo de ferramentas, então defer_loading e o modo estrito funcionam juntos sem recompilação de gramática.



Formato de resposta

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

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll search for tools to help with the weather information."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01ABC123",
      "name": "tool_search_tool_regex",
      "input": {
        "query": "weather"
      }
    },
    {
      "type": "tool_search_tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": {
        "type": "tool_search_tool_search_result",
        "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
      }
    },
    {
      "type": "text",
      "text": "I found a weather tool. Let me get the weather for San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01XYZ789",
      "name": "get_weather",
      "input": { "location": "San Francisco", "unit": "fahrenheit" }
    }
  ],
  "stop_reason": "tool_use"
}



Entendendo a resposta

• server_tool_use: Indica que o Claude está chamando a ferramenta de busca de ferramentas
• tool_search_tool_result: Contém os resultados da busca com um objeto tool_search_tool_search_result aninhado
• tool_references: Array de objetos tool_reference apontando para ferramentas descobertas
• tool_use: O Claude chamando a ferramenta descoberta

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



Integração com MCP

Para configurar mcp_toolset com defer_loading, consulte Conector MCP.



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 o Claude chama sua ferramenta de busca personalizada, retorne um tool_result padrão com blocos tool_reference no array de conteúdo:

{
  "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 com defer_loading: true. Essa 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, consulte o 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 adiadas:

{
  "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 da ferramenta retornam uma resposta 200 com informações de erro no corpo:

{
  "type": "tool_search_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 o limite de 200 caracteres
• unavailable: Serviço de busca de ferramentas temporariamente indisponível



Erros comuns



Cache de prompt

Para saber como defer_loading preserva o cache de prompt, consulte Uso de ferramentas com cache de prompt.

O sistema expande automaticamente os blocos tool_reference em todo o histórico da conversa, para que o Claude possa reutilizar ferramentas descobertas em turnos subsequentes sem pesquisar novamente.



Streaming

Com o streaming habilitado, 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"}}

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}

// Claude continues with discovered tools



Solicitações em lote

Você pode incluir a ferramenta de busca de ferramentas na Messages Batches API. As operações de busca de ferramentas através da Messages Batches API têm o mesmo preço que aquelas em solicitações regulares da Messages API.



Limites e melhores práticas



Limites

• Máximo de ferramentas: 10.000 ferramentas no seu catálogo
• Resultados de busca: Retorna de 3 a 5 ferramentas mais relevantes por busca
• Comprimento do padrão: Máximo de 200 caracteres para padrões regex
• Suporte de modelos: Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+, Haiku 4.5+



Quando usar a busca de ferramentas

Bons casos de uso:

• Mais de 10 ferramentas disponíveis no seu sistema
• Definições de ferramentas consumindo mais de 10 mil tokens
• Problemas de precisão na seleção de ferramentas com grandes conjuntos de ferramentas
• Construção de sistemas baseados em MCP com múltiplos servidores (mais de 200 ferramentas)
• Biblioteca de ferramentas crescendo ao longo do tempo

Quando a chamada de ferramentas tradicional pode ser melhor:

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



Dicas de otimização

• Mantenha de 3 a 5 ferramentas mais usadas como não adiadas
• Escreva nomes e descrições de ferramentas claros e descritivos
• Use namespacing consistente nos nomes de ferramentas: prefixe por serviço ou recurso (por exemplo, github_, slack_) para que as consultas de busca naturalmente revelem o grupo de ferramentas correto
• Use palavras-chave semânticas nas descrições que correspondam a como os usuários descrevem tarefas
• Adicione uma seção no prompt do sistema descrevendo as categorias de ferramentas disponíveis: "Você pode buscar ferramentas para interagir com Slack, GitHub e Jira"
• Monitore quais ferramentas o Claude descobre para refinar as descrições



Uso

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

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



Próximos passos