Ferramenta de busca de ferramentas

A 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ê excede 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 com milhares de ferramentas.

A busca de ferramentas está disponível de forma geral na Claude API. Para modelos compatíveis, consulte Compatibilidade de modelos.

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 para detalhes.



Compatibilidade de modelos

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

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 pesquisar ferramentas.
• BM25 (tool_search_tool_bm25_20251119): 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 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).
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:

client = anthropic.Anthropic()

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

Claude pesquisa o catálogo, descobre get_weather e o 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. Formato de resposta 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:

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

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 do 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 através 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.

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 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 para Claude. O prefixo permanece intocado, portanto o "prompt caching" (cache de prompt) é preservado. A gramática do modo estrito (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 compõem sem recompilação da gramática.



Formato de resposta

Quando Claude usa a ferramenta de busca de ferramentas, a resposta inclui os seguintes 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": {
        "pattern": "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: 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_....
• tool_search_tool_result: os resultados da busca, em um objeto aninhado tool_search_tool_search_result. 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 de 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 ao longo do histórico da conversa, para que Claude possa reutilizar as ferramentas descobertas em turnos posteriores sem pesquisar novamente. Uma busca que não encontra 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 através do conector MCP, 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 de conjunto de ferramentas 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 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, 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.

Para um exemplo completo usando embeddings, consulte a receita de busca de ferramentas com embeddings.



Tratamento de erros



Erros HTTP (status 400)

Esses erros impedem que a API processe a solicitação:

Todas as ferramentas adiadas:

{
  "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:

{
  "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:

{
  "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: "rate limit" (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



Cache de prompt

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

Uma ferramenta com defer_loading: true não pode também carregar 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:

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.



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



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 na 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 com o tempo.

A chamada de ferramentas padrão, sem busca de ferramentas, é uma opção melhor 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 namespacing consistente nos nomes das ferramentas: prefixe por serviço ou recurso (por exemplo, github_, slack_) para que uma busca corresponda ao grupo inteiro.
• Use palavras-chave nas descrições que correspondam a 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 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 campo de busca de ferramentas, e as definições de ferramentas que a busca carrega no contexto contam como input_tokens como qualquer outra definição de ferramenta.



Próximos passos