# Pesquisa de ferramentas no Claude Code: como o agente encontra a ferramenta MCP de que precisa > Como funciona a pesquisa de ferramentas no Claude Code: o que é carregado imediatamente para o contexto, quando o mecanismo se desativa e como configurar ENABLE_TOOL_SEARCH e alwaysLoad. Source: https://ailoot.ai/blog/pt-pt/claude-code-tool-search-mcp-limit/ Canonical: https://ailoot.ai/blog/pt-pt/claude-code-tool-search-mcp-limit/ Language: pt-PT Publisher: Ailoot (https://ailoot.ai/) Translation: guide-055 Revision: sha256-0aec38211e90c8f5aa6b183b69f8b6cb539800512fc9e8b075dba459224c3997 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](https://ailoot.ai/docs/). ## 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](https://ailoot.ai/blog/pt-pt/claude-code-skills-subagents-mcp-plugins/) e [O que escolher no Claude Code: Skills, Subagents, MCP ou Plugins](https://ailoot.ai/blog/pt-pt/skills-subagents-mcp-plugins-claude-code/) 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](https://ailoot.ai/blog/pt-pt/mcp-servers-claude-code/). ## 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.
### Fontes - [MCP no Claude Code, secção “Scale with MCP tool search” — documentação oficial da Anthropic](https://code.claude.com/docs/en/mcp.md) - [Pesquisa de ferramentas no Agent SDK — documentação oficial da Anthropic](https://code.claude.com/docs/en/agent-sdk/tool-search.md)
Se precisar de aceder a modelos de IA através da Ailoot, consulte a [Ailoot](https://ailoot.ai/). ## Perguntas frequentes ### Porque pode a pesquisa de ferramentas falhar por um proxy mesmo estando ativada? O servidor API de terceiros tem de suportar blocos tool_reference. Forçar ENABLE_TOOL_SEARCH não acrescenta esse suporte; um proxy incompatível pode rejeitar o pedido em vez de carregar antecipadamente as ferramentas. ### Quando devo definir alwaysLoad num servidor MCP? Use-o quando precisar das ferramentas desse servidor em todos os turnos. Todas as definições passam a ocupar contexto no arranque e este pode esperar pela ligação, salvo quando existir uma entrada válida na cache de descoberta. ## Ailoot · A empresa e a sua carteira de projetos A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI. A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões. A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.