Pesquisa de ferramentas no Claude Code: como o agente encontra a ferramenta MCP de que precisa

Se ligou vários servidores MCP ao Claude Code, a pesquisa de ferramentas permite-lhe carregar as ferramentas de que precisa quando necessário, sem carregar antecipadamente todas as definições. No arranque, o agente recebe os nomes das ferramentas adiadas e as instruções dos servidores e, em seguida, pesquisa no catálogo aquilo de que precisa. Isto ajuda-o a trabalhar com um conjunto alargado de ferramentas: a documentação da Anthropic indica que a precisão da seleção diminui quando são carregadas mais de 30-50 ferramentas de uma só vez. Trata-se de uma orientação geral, não de uma medição da sua sessão. A pesquisa de ferramentas está ativada por predefinição quando o modelo a suporta, mas a plataforma, um proxy ou as definições podem desativá-la.

Documentação da Ailoot: API, chaves e configuração.

O que acontece ao contexto sem a pesquisa de ferramentas#

Cada servidor MCP ligado adiciona as respetivas ferramentas à lista de coisas que o agente pode chamar. Sem a pesquisa de ferramentas, as definições — nome, descrição e esquema dos parâmetros — são carregadas antecipadamente para o contexto. Os servidores ligam-se em segundo plano quando uma sessão é iniciada. Se for necessária uma ferramenta de um servidor que ainda não tenha terminado de estabelecer ligação, o Claude Code aguarda através da ferramenta interna WaitForMcpServers. Pode avaliar separadamente, para cada ligação, quantas ferramentas e tokens um determinado servidor acrescenta.

A documentação oficial da Anthropic apresenta dois valores aproximados (números gerais, sem método de medição especificado):

• 50 ferramentas podem ocupar 10-20 mil tokens de contexto;
• a precisão na seleção da ferramenta certa diminui quando são carregadas mais de 30-50 de uma só vez.

Como avaliar a pesquisa de ferramentas a partir das definições#

Para perceber se a pesquisa de ferramentas deverá funcionar na sessão atual, verifique estas condições:

• qual o modelo que está a responder — Sonnet/Haiku/Opus 4.5 ou posterior: o mecanismo está disponível; um modelo mais antigo: não está;
• se ANTHROPIC_BASE_URL está definido para um anfitrião não padrão — nesse caso, o mecanismo está desativado por predefinição, a menos que seja explicitamente ativado através de ENABLE_TOOL_SEARCH;
• o valor da variável ENABLE_TOOL_SEARCH — false desativa completamente o mecanismo; auto/auto:N ativa-o apenas quando o volume das definições atinge um limiar;
• se CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS está definido — sem as definições geridas da organização, mantém a pesquisa de ferramentas desativada, mesmo que o utilizador tenha definido ENABLE_TOOL_SEARCH;
• se a ferramenta ToolSearch está bloqueada através de permissions.deny nas definições — essa restrição desativa a pesquisa;
• qual a plataforma utilizada — o mecanismo não está disponível em implementações do Microsoft Foundry no Azure, enquanto na Google Cloud Agent Platform o seu comportamento depende da versão do Claude Code e do modelo.

Esta verificação permite avaliar o estado a partir da configuração, mas não observá-lo dentro da sessão. A secção sobre MCP e a secção sobre pesquisa de ferramentas na documentação do Agent SDK não descrevem um indicador direto de «pesquisa de ferramentas: ativada/desativada» na interface. A ausência de uma referência nestes dois documentos não prova que esse indicador não exista em mais lado nenhum.

Pode definir a variável antes de iniciar uma sessão, por exemplo, ENABLE_TOOL_SEARCH=auto:15 claude. Para garantir que as ferramentas de um servidor específico são sempre carregadas, utilize o campo alwaysLoad: true na configuração desse servidor. Está disponível para todos os tipos de servidor; as condições e limitações são descritas abaixo na secção alwaysLoad.

Como funciona a pesquisa de ferramentas#

Quando a pesquisa de ferramentas está ativada, no arranque da sessão só são carregados para o contexto os nomes das ferramentas adiadas e as instruções do servidor. As instruções do servidor descrevem as tarefas para as quais o servidor é útil. Quando uma tarefa exige uma capacidade que ainda não está no contexto, o próprio agente pesquisa no catálogo uma ferramenta adequada.

A documentação do Agent SDK descreve o mecanismo de pesquisa com mais detalhe: por predefinição, uma única pesquisa carrega até cinco das ferramentas mais relevantes do catálogo. Estas permanecem disponíveis nos turnos seguintes da sessão até que o SDK compacte as mensagens em que o agente as encontrou. Após a compactação, as ferramentas descobertas anteriormente podem sair do contexto, e o agente volta a pesquisá-las da próxima vez que forem necessárias. O catálogo suporta até 10 000 ferramentas. A documentação de MCP do próprio Claude Code não apresenta estes valores específicos, mas descreve o mesmo princípio de carregamento adiado.

De acordo com a documentação do Agent SDK, cada pesquisa acrescenta uma interação adicional. A documentação não especifica exatamente o que essa interação inclui. Para o Claude Code, a documentação de MCP também descreve uma diferença no reporte de erros: sem a pesquisa de ferramentas, o Claude Code não informa o modelo sobre falhas nas ligações aos servidores. Com a pesquisa ativada, o modelo recebe informação sobre o servidor cuja ligação falhou e qual foi o erro.

O Claude Code não impõe um limite fixo ao número de ferramentas de um único servidor. O limite prático é o orçamento da janela de contexto para a sessão específica.

A configuração de ferramentas é uma das tarefas envolvidas na gestão do contexto de um agente de IA.

Quando a pesquisa de ferramentas está desativada por predefinição#

O mecanismo está ativado por predefinição, mas o seu funcionamento depende do modelo, do anfitrião da API e da plataforma.

Modelo. A pesquisa de ferramentas requer um modelo que suporte blocos tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 ou posterior. Nos modelos mais antigos, o Claude Code carrega antecipadamente as definições das ferramentas.

Anfitrião da API. O Claude Code desativa a pesquisa de ferramentas quando a variável ANTHROPIC_BASE_URL aponta para um anfitrião de terceiros: a maioria dos proxies não transmite os blocos especiais tool_reference. Isto aplica-se quando se liga ao Claude através do seu próprio gateway ou servidor proxy, em vez de diretamente pelo endereço da Anthropic. A razão para a desativação é um ANTHROPIC_BASE_URL não padrão; a forma de pagamento da subscrição não é, por si só, a causa. Pode definir explicitamente ENABLE_TOOL_SEARCH para substituir este comportamento. Se o próprio proxy não suportar blocos tool_reference, forçar a ativação do mecanismo resulta num erro do pedido. Neste caso, não haverá um fallback para o carregamento antecipado das definições.

Plataforma de implementação. A pesquisa de ferramentas não funciona em implementações do Microsoft Foundry alojadas no Azure: o servidor rejeita o pedido e ENABLE_TOOL_SEARCH não substitui este comportamento. Na Google Cloud Agent Platform, antes da versão 2.1.221 do Claude Code, o mecanismo estava desativado para todos os modelos, a menos que ENABLE_TOOL_SEARCH=true fosse definido explicitamente. A partir dessa versão, está ativado por predefinição para Opus/Sonnet/Haiku 4.5 e posteriores. Para modelos mais antigos na plataforma, o Claude Code continua a carregar todas as ferramentas antecipadamente, porque a infraestrutura dos respetivos servidores rejeita o cabeçalho interno necessário.

A variável ENABLE_TOOL_SEARCH tem cinco configurações possíveis:

• não definida — comportamento padrão, com as exceções indicadas acima;
• true — o mecanismo está ativado nos modelos que o suportam, exceto em dois casos: Azure Foundry e modelos mais antigos da Agent Platform; os pedidos enviados através de um proxy sem suporte para blocos tool_reference falharão;
• auto — o Claude Code carrega antecipadamente as ferramentas enquanto as respetivas definições, em conjunto, ocuparem menos de 10% da janela de contexto e muda para o carregamento adiado quando esse limiar é atingido;
• auto:N — o mesmo princípio, com um limiar percentual especificado manualmente;
• false — o mecanismo está completamente desativado e todas as ferramentas são carregadas antecipadamente.

Existe também a variável CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: se estiver definida, a pesquisa de ferramentas permanece desativada, e o utilizador não altera esse estado ao definir ENABLE_TOOL_SEARCH. A exceção é quando a organização mantém a pesquisa de ferramentas ativada através das definições geridas, disponíveis a partir da versão 2.1.227 do Claude Code.

O que faz alwaysLoad e como afeta o contexto e o arranque#

O campo alwaysLoad: true na configuração de um servidor está disponível para todos os tipos de servidor. Com ele, todas as ferramentas desse servidor são carregadas para o contexto no arranque, independentemente da configuração de ENABLE_TOOL_SEARCH. O agente não precisa de as pesquisar antes de as utilizar.

Carregar sempre as ferramentas tem duas consequências. Cada ferramenta carregada antecipadamente ocupa parte do contexto que, de outra forma, estaria disponível para a própria tarefa. Além disso, o arranque da sessão aguarda que este servidor estabeleça ligação, dentro do limite padrão de cinco segundos.

A exceção é um servidor remoto com uma entrada válida em cache: disponibiliza as ferramentas a partir da cache sem estabelecer ligação e não atrasa o arranque. A cache de descoberta está desativada por predefinição, a menos que já tenha sido ativada para a conta durante a implementação gradual da funcionalidade. Também pode ativá-la explicitamente através de MCP_DISCOVERY_CACHE=1. A exceção de arranque rápido aplica-se quando a cache está ativa e contém uma entrada válida. As ferramentas com alwaysLoad continuam a ocupar o contexto permanentemente, independentemente de o agente precisar delas ao trabalhar através da pesquisa.

Para quem escreve o seu próprio servidor MCP: as instruções do servidor ajudam o Claude a perceber quando deve pesquisar as respetivas ferramentas, tal como as Skills. Por predefinição, o Claude Code trunca a descrição de cada ferramenta e as instruções de cada servidor para 2048 caracteres; por isso, coloque os detalhes importantes no início.

A escolha de como expandir o Claude Code depende de mais do que o número de servidores MCP ligados. Os guias Claude Code: quantas extensões manter de cada vez e O que escolher no Claude Code: Skills, Subagents, MCP ou Plugins analisam Skills, Subagents, MCP e Plugins para diferentes tarefas. Para obter instruções passo a passo sobre a configuração de servidores MCP específicos, consulte Servidores MCP para Claude Code: combinações prontas.

O que fazer a seguir#

Para um conjunto com menos de cerca de 10 ferramentas cujas definições cabem facilmente no contexto, a documentação do Agent SDK refere que, normalmente, é mais rápido carregá-las todas de uma só vez. No entanto, no comportamento padrão do Claude Code, quando a variável não está definida e nenhuma das limitações acima se aplica, a pesquisa de ferramentas está ativada e o carregamento das ferramentas MCP é adiado até à pesquisa, exceto para servidores com alwaysLoad.

Neste caso, pode definir explicitamente ENABLE_TOOL_SEARCH=auto: as definições serão carregadas antecipadamente enquanto o respetivo volume combinado for inferior a 10% da janela de contexto, e a pesquisa será ativada quando o limiar for atingido. Outra opção é ENABLE_TOOL_SEARCH=false, se souber que o conjunto não vai aumentar. Nesse caso, o Claude Code deixará de informar o modelo sobre falhas nas ligações dos servidores, conforme descrito acima.

Nos outros casos, volte a verificar as condições de funcionamento quando o ambiente mudar:

• mude para Sonnet/Haiku/Opus 4.5 ou posterior se a sessão estiver a utilizar um modelo mais antigo;
• se a ligação utilizar um ANTHROPIC_BASE_URL não padrão, defina explicitamente ENABLE_TOOL_SEARCH=true apenas quando o próprio proxy transmitir blocos tool_reference;
• certifique-se de que a plataforma de implementação não está na lista de exceções: Azure Foundry ou modelos mais antigos da Google Cloud Agent Platform.

Se as condições forem cumpridas e a pesquisa não estiver bloqueada pelas definições, pode ligar os servidores MCP de que precisa. Utilize alwaysLoad apenas para os servidores cujas ferramentas são necessárias em todos os turnos da sessão; deixe os restantes serem carregados através da pesquisa.

Se precisar de aceder a modelos de IA através da Ailoot, consulte a Ailoot.