Ferramenta de busca de ferramentas

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 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 que precisa.

Esta abordagem resolve dois problemas que se agravam rapidamente conforme as bibliotecas de ferramentas aumentam:

• Inchaço de contexto: As definições de ferramentas consomem seu orçamento de contexto rapidamente. Uma configuração típica de múltiplos servidores (GitHub, Slack, Sentry, Grafana, Splunk) pode consumir ~55k tokens em definições antes de Claude fazer qualquer trabalho real. A busca de ferramentas normalmente reduz isso em mais de 85%, carregando apenas as 3–5 ferramentas que Claude realmente precisa para uma determinada solicitação.
• Precisão da seleção de ferramentas: A capacidade do Claude de escolher corretamente a ferramenta certa se degrada significativamente uma vez que 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 da seleção alta mesmo em milhares de ferramentas.

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. Consulte Implementação de busca de ferramentas personalizada para obter detalhes.

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 funciona a busca de ferramentas

Existem duas variantes de busca de ferramentas:

• Regex (tool_search_tool_regex_20251119): Claude constrói padrões regex para pesquisar ferramentas
• BM25 (tool_search_tool_bm25_20251119): Claude usa consultas em linguagem natural para pesquisar ferramentas

Quando você ativa 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) em 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. Claude vê apenas a ferramenta de busca de ferramentas e quaisquer ferramentas não adiadas inicialmente
4. Quando Claude precisa de ferramentas adicionais, ele pesquisa usando uma ferramenta de busca de ferramentas
5. A API retorna 3-5 blocos tool_reference mais relevantes
6. Essas referências são automaticamente expandidas em definições de ferramentas completas
7. Claude seleciona entre as 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 adiadas:

Definição de 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-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 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 definição da ferramenta é anexada inline como um bloco tool_reference na conversa. O prefixo não é tocado, então o cache de prompt é preservado. A gramática para modo estrito é construída a partir do conjunto completo de ferramentas, então defer_loading e modo estrito se compõem sem recompilação de gramática.

Formato de resposta

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

{
  "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 Claude está invocando 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: 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 contanto que você forneça todas as definições de ferramentas correspondentes no parâmetro tools.

Integração MCP

Para configurar mcp_toolset com defer_loading, consulte Conector MCP.

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. Quando 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" }]
}

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, consulte o cookbook de busca de ferramentas com embeddings.

Tratamento de erros

Erros HTTP (status 400)

Estes 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_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

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

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 pesquisar novamente.

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

// 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 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 as solicitações da API de Mensagens regular.

Retenção de dados

A busca de ferramentas do lado do servidor (ferramenta tool_search) indexa e armazena dados do catálogo de ferramentas (nomes de ferramentas, descrições e metadados de argumentos) além da resposta imediata da API; esses dados de catálogo são retidos de acordo com a política de retenção padrão da Anthropic. Implementações personalizadas de busca de ferramentas do lado do cliente que usam a API de Mensagens padrão são totalmente elegíveis para ZDR.

Para elegibilidade de ZDR em todos os recursos, consulte API e retenção de dados.

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: Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+ apenas (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 frequentemente usadas como não adiadas
• Escreva nomes e descrições de ferramentas claros e descritivos
• Use namespacing consistente em nomes de ferramentas: prefixo por serviço ou recurso (por exemplo, github_, slack_) para que consultas de busca naturalmente apresentem o grupo de ferramentas certo
• 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 pesquisar ferramentas para interagir com Slack, GitHub e Jira"
• Monitore quais ferramentas Claude descobre para refinar 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