Design de ferramentas para agentes: o que ele consegue usar de verdade

Com dez ferramentas disponíveis, o agente acerta tudo. Com vinte, acerta dezenove de vinte. Com cento e sete, falha por completo — e não só os modelos pequenos. Os grandes também.

O detalhe importante está entre esses três pontos. Não existe ladeira ali. O modelo vai bem até certo limiar e despenca depois dele.

Quem está com um agente que escolhe a ferramenta errada costuma procurar um modelo melhor. Na maioria dos casos, o problema está no cardápio.

Uma API é um contrato entre dois sistemas determinísticos. Se o campo se chama usr_id e o tipo é inteiro, o cliente manda um inteiro. O nome não importa para a máquina.

Uma ferramenta de agente é outra coisa. Do outro lado está um consumidor que lê a descrição, decide se aquela é a ferramenta certa e inventa os parâmetros a partir do que entendeu. O nome importa. A descrição importa. O formato da resposta importa.

A consequência prática vale ser dita com todas as letras: a documentação virou parte da execução. Num sistema comum, uma descrição ruim atrapalha o desenvolvedor uma vez, e depois ele aprende. Num agente, ela atrapalha em toda chamada, para sempre.

Conectar a ferramenta é a parte resolvida. O guia de MCP na prática cobre o transporte. O que fica do outro lado da conexão continua sendo problema de quem desenha.

A equipe da Speakeasy rodou um experimento controlado com a API do Pet Store, medindo acerto de tarefa conforme aumentava o número de ferramentas expostas ao agente (Speakeasy, acesso em 27/08/2026).

O mecanismo é simples de entender. Nome, descrição e esquema de parâmetro de cada ferramenta ocupam espaço na janela em toda requisição, mesmo nas chamadas em que aquela ferramenta não tem nada a ver com a tarefa. Vinte ferramentas mal descritas custam mais contexto do que muita gente imagina, e o espaço que elas ocupam sai do raciocínio.

Esse é o mesmo orçamento de janela que o agente usa para lembrar o que está fazendo. Ferramenta e memória disputam o mesmo lugar.

Há um número que fecha o argumento. No baseline do estudo RAG-MCP, com muitas ferramentas na janela, a acurácia de escolha ficou em 13,62% — perto de sorteio.

O julgamento explícito deste post: conectar mais um servidor MCP tem custo, e ele é cobrado em toda chamada, não apenas quando a ferramenta é usada. Vale tratar isso como decisão de arquitetura, e não como instalação. Quem paga por token sente isso direto na fatura, pelo mesmo mecanismo descrito em quanto custa cada padrão de uso.

Faça a conta do seu cardápio

A pergunta útil depois desse gráfico não é quantas ferramentas existem no seu servidor. É quantas o agente enxerga numa requisição, somando todos os servidores conectados. Quase sempre o número surpreende, porque cada integração parecia barata quando entrou.

Contado o total, a triagem tem três cortes fáceis:

O que nunca foi chamado. Olhe o registro das últimas semanas. Ferramenta que ninguém acionou está pagando aluguel de contexto sem entregar nada. Desconecte e veja se falta.

O que veio junto sem ser pedido. Um servidor MCP costuma expor dezenas de ferramentas para você usar duas. Quando o servidor permite escolher o que publicar, publique só as duas. Quando não permite, esse é um argumento contra ele.

O que o próprio agente confunde. Se duas ferramentas têm nomes parecidos e ele alterna entre elas sem critério, o problema é de desenho. Ou vira uma só, ou os nomes passam a dizer em que caso cada uma serve.

Esses três cortes são gratuitos e levam uma tarde. Recuperação, índice e roteamento vêm depois, se ainda fizer falta.

As recomendações abaixo vêm do guia de engenharia da Anthropic publicado em 11 de setembro de 2025 (Anthropic, acesso em 27/08/2026). Vale registrar de onde elas saíram: segundo o próprio texto, a maior parte do conselho veio de otimizar repetidamente as ferramentas internas da empresa com o Claude Code, com ganho medido em servidores MCP de Slack e Asana.

1. Consolidar em vez de envolver a API inteira

O erro mais comum é gerar uma ferramenta por endpoint. A frase da Anthropic é direta: mais ferramentas nem sempre levam a resultado melhor.

Pense no que a pessoa faria, não no que a API expõe:

antes                          depois
list_users                     users_search
get_user                         (busca, resolve e devolve
get_user_email                    o que a tarefa precisa)
get_user_manager

Quatro chamadas viram uma. O agente gasta menos passos, e cada passo economizado é um passo que não pode dar errado.

2. Nome com prefixo de serviço e de recurso

Ferramenta chamada search obriga o modelo a adivinhar onde ela procura. Com vários serviços conectados, ele erra.

O padrão recomendado agrupa por serviço e por recurso:

search              →  asana_search
                       jira_search
                       asana_projects_search

O prefixo carrega informação. O modelo escolhe pelo nome antes de ler a descrição inteira.

3. Retorno em linguagem que o modelo interpreta

Identificador técnico não significa nada para quem lê. Pior: convida à alucinação, porque o modelo tenta reconstruir sentido a partir de uma string opaca.

// antes
{ "assignee": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": 2 }

// depois
{ "assignee": "Marina Costa",
  "assignee_id": "a1b2c3d4-…",
  "status": "em revisão" }

O identificador continua ali para quando o agente precisar dele. O que mudou é que agora existe também a versão legível. A Anthropic liga essa prática diretamente à redução de alucinação.

4. Teto de resposta, paginação e formato ajustável

Uma ferramenta que devolve tudo entope a janela numa chamada só. O guia sugere limitar a resposta a 25.000 tokens por padrão, com paginação, filtro e truncagem já configurados.

Uma segunda ideia rende mais do que parece: expor um parâmetro response_format que o agente controla.

response_format: "concise" | "detailed"

Assim ele pede o resumo quando está varrendo opções e o detalhe quando já decidiu. Quem escolhe o nível é quem sabe em que ponto da tarefa está.

5. Erro que ensina o caminho de volta

Esta é a decisão de maior retorno por linha escrita, e a mais ignorada.

Uma ferramenta que falha assim entrega ao agente três hipóteses e nenhuma pista:

Error: ENOENT

Ele vai testar as três, gastando passos. A mesma falha, escrita para quem vai ler, resolve na primeira tentativa:

Arquivo não encontrado: lib/posts.ts

O diretório lib/ existe e contém:
  posts-meta.ts, markdown.ts, site.ts, covers.ts

Você quis dizer lib/posts-meta.ts?

Três elementos fazem a diferença: o que falhou, com o valor exato recebido; o estado real do sistema naquele ponto; e o próximo passo sugerido. Um erro com os três transforma uma tentativa perdida em informação.

Vale um cuidado de segurança aqui. Resposta de ferramenta é texto que entra no contexto do agente, e portanto é superfície de injeção — o assunto de por que prompt injection não tem correção definitiva. Mensagem de erro útil não significa devolver conteúdo de terceiros sem tratamento.

6. Descrição de ferramenta é prompt

A frase do guia merece ser citada como está: mesmo refinamentos pequenos nas descrições de ferramentas podem produzir melhorias expressivas.

Duas regras práticas. Torne explícito o contexto que você acha óbvio. E nomeie parâmetro sem ambiguidade — user_id diz o que espera, user não.

antes:  "Busca itens."           parâmetro: query, user
depois: "Busca tarefas do Asana  parâmetro: query, user_id
         por texto no título e
         na descrição. Devolve
         no máximo 50, mais
         recentes primeiro."

As seis juntas, num exemplo só

Fragmento a fragmento é fácil concordar. O efeito aparece quando as seis mudanças caem sobre a mesma ferramenta.

Antes:

nome:      getTickets
descrição: "Retorna tickets."
parâmetros: status (int), u (string)

retorno em caso de sucesso:
[{"id":"8f3c…","s":2,"u":"a1b2…","t":1757308800}]

retorno em caso de falha:
{"error": 422}

Depois:

nome:      support_tickets_search
descrição: "Busca tickets de suporte por status e responsável.
            Devolve no máximo 50, mais recentes primeiro.
            Para o histórico completo de um ticket, use
            support_tickets_get."
parâmetros: status ("aberto" | "em_analise" | "resolvido")
            assignee_id (string)
            response_format ("concise" | "detailed")

retorno em caso de sucesso:
{"total": 128, "mostrando": 50, "proxima_pagina": "p2",
 "tickets": [{"id": "8f3c…",
              "titulo": "Falha no login por SSO",
              "status": "em_analise",
              "responsavel": "Marina Costa",
              "responsavel_id": "a1b2…",
              "aberto_em": "2026-09-08"}]}

retorno em caso de falha:
{"erro": "status inválido: 2",
 "aceitos": ["aberto", "em_analise", "resolvido"],
 "dica": "o parâmetro passou a aceitar texto em vez de número"}

Nada aí exige biblioteca nova. É a mesma consulta ao mesmo banco. O que mudou foi tudo que o agente lê antes e depois de chamar.

Repare no campo dica da resposta de erro. Ele resolve o caso mais chato de todos, que é o agente ter aprendido uma versão antiga da interface. Sem essa linha, ele tentaria 2 de novo.

Resumo das seis

Quando a ferramenta ruim é de outra pessoa

Boa parte do conselho acima pressupõe que você escreve a ferramenta. Na prática, metade do cardápio costuma vir de servidor MCP de terceiro, com nome genérico, retorno cheio de identificador e erro em código numérico.

Três saídas, em ordem de custo:

Filtrar. Se o cliente permite escolher quais ferramentas do servidor ficam ativas, publique só as que você usa. É gratuito e resolve o problema do volume, embora não melhore o desenho das que sobraram.

Embrulhar. Escreva uma ferramenta sua que chama a de terceiro e devolve o resultado tratado: nome no lugar do UUID, teto de tamanho, erro traduzido. Custa uma camada fina de código e recupera o controle do que o agente lê. Foi assim que resolvi o caso em que a saída bruta ocupava metade da janela.

Trocar. Quando o servidor expõe quarenta ferramentas para entregar duas e não deixa filtrar, isso é informação sobre o produto. Existe alternativa, ou dá para chamar a API direta.

O erro a evitar é o quarto caminho, que é aceitar o desenho ruim e compensar com instrução no prompt. Instrução não reduz o que a ferramenta ocupa na janela nem melhora o que ela devolve.

Quando ferramenta é a abstração errada

Antes de escrever a próxima, vale checar se o problema é mesmo de ferramenta. Três casos comuns em que a resposta é outra coisa:

O agente precisa saber, não fazer. Convenção do projeto, decisão de arquitetura e o comando que roda os testes são contexto, e o lugar disso é o arquivo de contexto na raiz. Transformar em ferramenta custa uma chamada e ocupa espaço no cardápio para entregar o que já podia estar lido.

Algo precisa acontecer sempre. Se o lint tem que rodar antes do commit, isso não é uma ferramenta que o agente escolhe usar. É um hook. Ferramenta é opção; o que não pode ser opcional sai da lista de opções.

É de uma vez só. Nem toda tarefa merece interface. Se o agente consegue rodar o comando direto e a operação não se repete, escrever uma ferramenta em volta adiciona um item permanente ao cardápio para resolver um problema temporário.

A pergunta que separa os casos é curta: isto é uma decisão que o agente deve tomar? Se a resposta for não, provavelmente não é ferramenta.

A saída medida é recuperar em vez de listar. Em vez de despejar todas as descrições na janela, um índice busca as poucas relevantes para aquela tarefa e só elas entram no prompt.

O ganho é real e vale a pena: a acurácia sobe de 13,62% para 43,13%, e os tokens de prompt caem mais da metade, com média de 1.084 (arXiv 2505.03275, acesso em 27/08/2026).

E aqui entra a parte que costuma ser omitida: 43% ainda é ruim. Recuperação compra espaço na janela e melhora a escolha, sem chegar perto de resolver. Quem monta uma arquitetura de recuperação achando que destravou cem ferramentas está trocando um problema por outro menor.

A alternativa que escala melhor divide por agente, não por índice. Cada agente recebe um conjunto pequeno de ferramentas e um escopo estreito, e a coordenação acontece um nível acima. É a decisão descrita em quando delegar a um subagente, aqui com um motivo adicional: cada subagente tem a própria janela, e o cardápio de cada um cabe nela.

<!-- [PERSONAL EXPERIENCE] -->

A operação que publica este blog tem um conjunto pequeno de ferramentas, e o desenho delas foi mudando conforme apanhei.

O gerador de schema é o que mais aprendeu com o uso. A primeira versão devolvia só "ok". Hoje devolve 8 entidades | FAQ 5 | wordCount 3194 | órfãos: nenhum | JSON ok: True. A diferença aparece quando algo quebra: com a saída antiga, eu abria o JSON para descobrir o que faltava; com a atual, a resposta já diz.

A decisão desta semana foi a consolidação da seção anterior, aplicada por necessidade. Eu tinha escrito um script de capa por post. Ao publicar o segundo, virou um gerador único que recebe o slug e lê o conteúdo de cada capa num mapa. Antes de apagar o script antigo, gerei de novo a capa do primeiro post e conferi o hash: idêntico. Duas ferramentas viraram uma, e ninguém precisou me explicar o princípio.

Também vale dizer o que continua errado ali. Esse gerador exige editar o próprio arquivo para cada post novo, o que significa que a "ferramenta" carrega os dados dentro dela. Funciona para uma pessoa publicando três vezes por semana. Numa revisão de código séria, reprovaria — e a correção é óbvia, que é receber o conteúdo por parâmetro ou por arquivo de configuração. Ainda não fiz.

A Anthropic descreve um laço de avaliação que funciona sem infraestrutura pesada. Resumido em seis passos:

1. Protótipo. Escreva a primeira versão com documentação amigável ao modelo à mão.
2. Conecte local. Empacote num servidor MCP local e conecte com claude mcp add.
3. Gere tarefas. Peça dezenas de pares de prompt e resposta esperada, baseados em fluxos que você faz de verdade.
4. Meça. Rode as tarefas num laço simples e colete acurácia, tempo, número de chamadas, tokens e erros.
5. Analise com o agente. Concatene as transcrições e peça a análise. Ele encontra padrões que passam despercebido na leitura manual.
6. Itere com conjunto separado. Guarde tarefas que não entraram na otimização, para não ajustar as ferramentas ao próprio teste.

O passo quatro é o que separa opinião de medição. Vale registrar quatro números por rodada e comparar com a rodada anterior:

Número de chamadas por tarefa é o mais barato de todos e o que se move primeiro. Quando ele sobe sem a tarefa ficar maior, alguma coisa no cardápio piorou.

A taxa de erro por ferramenta merece leitura separada, e não agregada. Uma ferramenta com erro alto no meio de nove saudáveis some na média, e é exatamente ela que está custando os passos.

E vale colocar essa verificação no caminho, não na disciplina. Hooks fazem a avaliação rodar sem depender de alguém lembrar, que é a camada de verificação do harness.

Quantas ferramentas um agente aguenta?

Num experimento controlado da Speakeasy com a API do Pet Store, o desempenho foi perfeito com 10 ferramentas, caiu para 19 acertos em 20 com 20 ferramentas, e colapsou por completo com 107, tanto em modelos grandes quanto pequenos. A queda não é gradual: passado um limiar, o modelo despenca em vez de piorar aos poucos. Na prática, vale manter o conjunto visível na casa de uma dezena e revisar sempre que passar disso.

Por que meu agente escolhe a ferramenta errada?

As três causas mais comuns são ferramentas demais na janela, nomes que não distinguem uma da outra e descrições que omitem escopo. Com muitas opções disponíveis, a acurácia de escolha medida no baseline do estudo RAG-MCP foi de 13,62%. Antes de trocar de modelo, reduza o cardápio, coloque prefixo de serviço no nome e escreva na descrição o que a ferramenta faz, o que ela limita e como ordena.

Como escrever a descrição de uma ferramenta?

Trate a descrição como prompt, porque é o que ela é. Diga o escopo exato, o limite de resultados e a ordenação, torne explícito o contexto que parece óbvio e nomeie os parâmetros sem ambiguidade — user_id em vez de user. A Anthropic afirma que mesmo refinamentos pequenos nas descrições podem produzir melhorias expressivas.

Ferramenta MCP consome contexto mesmo sem ser usada?

Sim. Nome, descrição e esquema de parâmetros de toda ferramenta conectada entram na requisição, independentemente de o agente chamá-la ou não. É por isso que conectar mais um servidor tem custo recorrente, cobrado em cada chamada, e não um custo pontual de instalação.

Vale mais desligar servidores MCP ou usar recuperação?

Desligue primeiro. Reduzir o conjunto é gratuito e imediato; montar recuperação custa infraestrutura e, no estudo RAG-MCP, levou a acurácia a 43,13%, o que ainda deixa a maioria das escolhas erradas. Recuperação faz sentido quando o número grande de ferramentas é um requisito real, e não quando ele é resultado de nunca ter desconectado nada.

• 10 ferramentas: acerto total. 107: colapso. E entre os dois pontos não existe ladeira.
• Toda ferramenta conectada custa contexto em toda requisição, usada ou não.
• Com o cardápio grande, a escolha fica em 13,62%. Recuperação leva a 43,13%, que ainda é ruim.
• As seis decisões que rendem são baratas: consolidar, nomear com prefixo, devolver linguagem legível, limitar a resposta, escrever erro que ensina e tratar descrição como prompt.
• Meça número de chamadas por tarefa. É o indicador que se move primeiro.

O próximo post do cluster trata da camada que vem logo depois desta: o agente conferindo o próprio trabalho antes de dizer que terminou. As cinco camadas estão descritas no pilar sobre harness engineering.