Skip to main content
A busca de ferramentas permite que seu agente 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 agente pesquisa seu catálogo de ferramentas e carrega apenas as ferramentas de que precisa. Esta abordagem resolve dois desafios conforme as bibliotecas de ferramentas se dimensionam:
  • Eficiência de contexto: As definições de ferramentas podem consumir grandes porções da janela de contexto (50 ferramentas podem usar 10-20K tokens), deixando menos espaço para o trabalho real.
  • Precisão da seleção de ferramentas: A precisão da seleção de ferramentas se degrada com mais de 30-50 ferramentas carregadas simultaneamente.

Como funciona a busca de ferramentas

A busca de ferramentas está ativada por padrão, com as exceções listadas em Configurar busca de ferramentas. Quando está ativa, as definições de ferramentas são retidas da janela de contexto. O agente recebe um resumo das ferramentas disponíveis e pesquisa as relevantes quando a tarefa requer uma capacidade não carregada. Até cinco das ferramentas mais relevantes são carregadas no contexto por padrão, onde permanecem disponíveis para turnos subsequentes até que o SDK compacte as mensagens onde o agente as descobriu. Após essa compactação, o agente pesquisa essas ferramentas novamente quando precisar delas. A busca de ferramentas adiciona uma viagem extra de ida e volta cada vez que Claude pesquisa ferramentas, mas para grandes conjuntos de ferramentas isso é compensado por um contexto menor a cada turno. Com menos de ~10 ferramentas cujas definições se encaixam confortavelmente na janela de contexto, carregar tudo antecipadamente é geralmente mais rápido. Para detalhes sobre o mecanismo de API subjacente, consulte Busca de ferramentas na API.
A busca de ferramentas não é suportada em implantações do Microsoft Foundry hospedadas no Azure, que a rejeitam no lado do servidor: o SDK detecta a rejeição e carrega as definições de ferramentas antecipadamente para essa implantação. ENABLE_TOOL_SEARCH não pode substituir isso, pois a rejeição vem da implantação em si.
A busca de ferramentas está ativada por padrão. Para modelos na lista de modelos não suportados do SDK, o SDK carrega as definições de ferramentas antecipadamente, e nenhum valor ENABLE_TOOL_SEARCH sobrescreve isso. Na Agent Platform do Google Cloud, o SDK decide por geração de modelo:
  • Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 e posterior: a busca de ferramentas está ativada por padrão.
  • Modelos anteriores da Agent Platform: o SDK carrega as definições de ferramentas antecipadamente, porque suas pilhas de serviço rejeitam o cabeçalho beta necessário. ENABLE_TOOL_SEARCH não pode sobrescrever isso.
Antes do Claude Code v2.1.221, o SDK desativava a busca de ferramentas para todos os modelos na Agent Platform do Google Cloud, a menos que você definisse ENABLE_TOOL_SEARCH. O SDK também desativa a busca de ferramentas quando ANTHROPIC_BASE_URL aponta para um host não de primeira parte, já que a maioria dos proxies não encaminha blocos tool_reference. Você pode sobrescrever esse padrão com a variável de ambiente ENABLE_TOOL_SEARCH: Definir CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS mantém a busca de ferramentas desativada. Você não pode sobrescrever isso definindo ENABLE_TOOL_SEARCH você mesmo. No Claude Code v2.1.227 ou posterior, sua organização pode manter a busca de ferramentas ativada sob essa variável por meio de configurações gerenciadas. Em uma sessão que recebe a configuração HIPAA, a busca de ferramentas fica desativada, e nem ENABLE_TOOL_SEARCH nem as configurações gerenciadas a reativam. Desabilitar capacidades de pré-lançamento cobre onde a substituição se aplica e o que a variável remove. A busca de ferramentas se aplica a todas as ferramentas registradas, sejam elas provenientes de servidores MCP remotos ou servidores MCP SDK personalizados. Quando você usa auto, o SDK conta todas as definições que a busca de ferramentas pode adiar em relação a um limite combinado: cada ferramenta MCP que não está marcada como alwaysLoad, de qualquer servidor, mais as ferramentas integradas que carregam sob demanda. O SDK carrega ferramentas integradas principais, como Bash, Read e Edit, antecipadamente e não as conta em relação ao limite. Um mod em um dos seus plugins também pode adiar uma ferramenta ou carregá-la antecipadamente, o que altera essa contagem. Defina o valor na opção env em query(). Em TypeScript, env substitui o ambiente do subprocesso, portanto espalhe ...process.env para manter as variáveis herdadas. Em Python, env é mesclado no topo do ambiente herdado. Este exemplo se conecta a um servidor MCP remoto que expõe muitas ferramentas, pré-aprova todas elas com um curinga e usa auto:5 para que a busca de ferramentas seja ativada quando as definições que ela pode adiar atingem 5% da janela de contexto:
Para executar este exemplo, substitua https://tools.example.com/mcp pela URL do seu próprio servidor MCP. Em caso de sucesso, o texto do resultado é impresso no console. Como esta é uma chamada query() de uma única vez, o SDK lança uma exceção após gerar um resultado de erro, portanto o exemplo envolve o loop em um bloco try. Para ver por que uma execução falhou, verifique o subtype da mensagem de resultado, como error_during_execution, dentro do loop. Para mais informações sobre mensagens de resultado, consulte Lidar com o resultado.

Otimizar descoberta de ferramentas

O mecanismo de pesquisa corresponde consultas com nomes e descrições de ferramentas. Nomes como search_slack_messages aparecem para uma gama mais ampla de solicitações do que query_slack. Descrições com palavras-chave específicas (“Pesquisar mensagens do Slack por palavra-chave, canal ou intervalo de datas”) correspondem a mais consultas do que genéricas (“Consultar Slack”). Você também pode adicionar uma seção de prompt do sistema listando categorias de ferramentas disponíveis. Isso dá ao agente contexto sobre que tipos de ferramentas estão disponíveis para pesquisar. Passe o texto através da opção systemPrompt em TypeScript ou system_prompt em Python, usando a predefinição claude_code com append, que adiciona seu texto ao prompt da predefinição em vez de substituí-lo:
Para o conjunto completo de opções de prompt do sistema, consulte Modificando prompts do sistema.

Limites

  • Ferramentas máximas: 10.000 ferramentas em seu catálogo
  • Resultados de pesquisa: retorna até cinco ferramentas mais relevantes por pesquisa por padrão
  • Suporte de modelo: Opus 4, Sonnet 4, Haiku 4.5 e modelos posteriores, ou Opus 4.5, Sonnet 4.5, Haiku 4.5 e modelos posteriores na Agent Platform do Google Cloud. Em modelos anteriores, o SDK carrega as definições de ferramentas antecipadamente, conforme descrito em Configurar a pesquisa de ferramentas.