Ferramenta de busca de ferramentas

A ferramenta de busca de ferramentas permite que o 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, 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 rapidamente seu orçamento de contexto. Uma configuração típica de múltiplos servidores (GitHub, Slack, Sentry, Grafana, Splunk) pode consumir ~55k 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 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ê ultrapassa 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 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 personalizada de busca de ferramentas para obter detalhes.

Você também pode implementar busca de ferramentas do lado do cliente retornando blocos tool_reference da 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): O Claude constrói padrões regex para pesquisar ferramentas
• BM25 (tool_search_tool_bm25_20251119): O Claude usa consultas em linguagem natural para pesquisar 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 3-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 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 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 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: As 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 é alterado, portanto o cache de prompt é preservado. A gramática para o modo estrito é construída a partir do conjunto completo de ferramentas, portanto defer_loading e o modo estrito se compõem 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á 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 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 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_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 de conversas, para que o Claude possa reutilizar ferramentas descobertas em turnos subsequentes sem precisar 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"}}

// 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 da busca transmitidos
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 continua com as ferramentas descobertas

Solicitações em lote

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

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 do 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 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 no seu catálogo
• Resultados de busca: Retorna 3-5 ferramentas mais relevantes por busca
• Comprimento do padrão: Máximo de 200 caracteres para padrões regex
• Suporte a modelos: Apenas Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+ (sem Haiku)

Quando usar a busca de ferramentas

Bons casos de uso:

• 10+ ferramentas disponíveis no 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 com MCP com múltiplos servidores (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 3-5 ferramentas mais usadas como não adiadas
• Escreva nomes e descrições de ferramentas claros e descritivos
• Use namespacing consistente nos nomes das ferramentas: prefixe por serviço ou recurso (por exemplo, github_, slack_) para que as consultas de busca naturalmente apresentem o grupo de ferramentas correto
• Use palavras-chave semânticas 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: "Você pode pesquisar 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