Ferramenta de busca de ferramentas

A "tool search tool" (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ê ultrapassa 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 entre milhares de ferramentas.

Para os modelos que suportam a busca de ferramentas, 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 suportam a 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 buscar ferramentas.
• BM25 (tool_search_tool_bm25_20251119): 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 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; Claude pode definir um limit na entrada da busca).
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 a 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 da 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 no 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 por meio 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.

Os conjuntos de ferramentas de uso de computador e uso de navegador (computer_toolset_20260801 e browser_toolset_20260801) recebem defer_loading por ferramenta membro dentro do objeto configs da entrada, não na própria entrada; uma solicitação que o define no nível da entrada é rejeitada. Como um conjunto de ferramentas é adiado e expandido como uma unidade, defer_loading deve resolver para o mesmo valor em cada membro habilitado e, quando Claude descobre o conjunto de ferramentas por meio da busca, todos os membros habilitados são carregados de uma vez. Consulte Conjuntos de ferramentas do cliente para o formato de configs.

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 por meio 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á-lo 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 combinam sem recompilação da gramática.

Formato da 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",
        "limit": 10
      }
    },
    {
      "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_.... O input contém a busca (pattern para a variante regex, query para BM25) e pode incluir um limit opcional, um inteiro de 1 a 10.000 que limita quantas ferramentas correspondentes a busca retorna (padrão: 5).
• tool_search_tool_result: os resultados da busca, em um objeto tool_search_tool_search_result aninhado. 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 do 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 em todo o histórico da conversa, portanto Claude pode reutilizar ferramentas descobertas em turnos posteriores sem pesquisar novamente. Uma busca que não corresponde a 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 por meio 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 do 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 busca de ferramentas com embeddings.

Tratamento de erros

Erros HTTP (status 400)

Esses erros impedem a API de processar 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: 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 ter 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; Claude pode definir limit na entrada da busca como qualquer inteiro de 1 a 10.000
• 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 da 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 ao longo do tempo.

A chamada de ferramentas padrão, sem busca de ferramentas, é mais adequada 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 namespaces consistentes nos nomes das ferramentas: prefixe por serviço ou recurso (por exemplo, github_, slack_) para que uma única busca corresponda ao grupo inteiro.
• Use palavras-chave 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: "You can search for tools to interact with Slack, GitHub, and 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 um campo de busca de ferramentas, e as definições de ferramentas que a busca carrega no contexto contam como tokens de entrada, como qualquer outra definição de ferramenta.

Próximos passos