Abertura

Um agente interno de operações começou com cinco ferramentas. A cada sprint, algum time pedia mais uma. Um ano depois, a lista enviada em toda chamada estava assim.

Get user. Fetch user. Get user profile. Look up customer. Search users. Cinco ferramentas, todas dizendo, mais ou menos, busca um usuário.

Depois, get account, e get account versão dois, descrita como: busca uma conta, nova. E mais trinta e três.

O trace mostra o efeito. Chega um pedido: qual é o plano do cliente com este CPF?

O modelo chama get user, com o CPF no campo de id. Erro de tipo.

Tenta search users, com o CPF como texto livre. Nada útil.

E só na terceira tentativa encontra look up customer. Três turnos, para uma consulta. Nesta aula, você vai aprender a reconhecer esse smell, quanto ele custa de verdade e a ordem de trabalho para enxugar a lista.

O diagnóstico

O formato é este. Chega um pedido simples.

O modelo precisa escolher entre dezenas de opções descritas de forma vaga.

Ele escolhe a que tem o nome mais parecido com o pedido.

O resultado é um erro, ou um dado que não ajuda.

E depois de turnos extras, ele acerta. Ou desiste.

Como identificar? Mais de quinze ou vinte ferramentas disponíveis na mesma chamada.

Nomes parecidos, como get alguma coisa, fetch alguma coisa e alguma coisa versão dois, com descrições quase iguais.

Descrições de uma linha que dizem o que a ferramenta faz, mas nunca quando usar.

Traces em que a ferramenta errada é chamada primeiro e corrigida depois. E definições de ferramenta somando milhares de tokens em toda chamada.

E ninguém sabe dizer quais ferramentas ainda são usadas.

Por que acontece

Cada time acrescenta a sua. Uma ferramenta nova é o jeito mais fácil de dar ao agente uma capacidade nova, e ninguém é dono da lista inteira.

Remover parece arriscado. Sem dado de uso, tirar uma ferramenta pode quebrar um fluxo que alguém usa uma vez por mês.

As APIs internas viram ferramentas uma a uma. Cada endpoint vira uma ferramenta, com o nome do endpoint. O agente herda o formato do seu backend, não o formato da tarefa.

Versões novas convivem com as antigas. A versão dois entrou para a um não quebrar, e as duas ficaram.

E conectar um servidor de ferramentas via MCP, o model context protocol, muitas vezes expõe dezenas de ferramentas de uma vez. O time liga o servidor e esquece de filtrar o que o agente precisa de verdade.

A armadilha de quem está começando é tratar mais ferramentas como mais capacidade. Muitas vezes é o contrário. Poucas ferramentas, bem distintas, vencem uma caixa de ferramentas que o modelo não consegue ler inteira.

Quanto custa

Agora, o custo. Primeiro, acerto. A escolha de ferramenta piora quando as opções são muitas, e parecidas. Cada erro custa um turno a mais, ou uma resposta errada.

Depois, dinheiro, com números ilustrativos. Digamos que cada definição de ferramenta tem uns cento e cinquenta tokens, e o agente faz dez mil chamadas por dia. Com quarenta ferramentas, são uns seis mil tokens por chamada, e uns sessenta milhões de tokens por dia. Só do catálogo.

Com oito ferramentas, uns doze milhões. E cada escolha errada ainda paga um turno a mais, com o histórico inteiro de novo.

E segurança. Mais ferramentas, mais superfície. Imagine o agente de um marketplace com três ferramentas de pagamento. Pagar boleto, enviar Pix e transferir por TED. As três descritas como: paga o cliente. Um pedido de estorno pode disparar a errada. Aí o erro deixa de ser custo. O dinheiro vai pelo trilho errado. E uma ferramenta de escrita esquecida na lista é uma porta aberta. Em segurança, isso tem nome. Agência excessiva. O modelo tem mais poder do que a tarefa precisa.

Um desafio

Uma pergunta para você. Você conectou o servidor de ferramentas de um produto interno, e o agente agora vê oitenta ferramentas, a maioria de administração. Em produção, um usuário pediu o status de um pedido, e o modelo chamou delete workspace. O que esse caso mostra, primeiro?

Que a lista enviada ao modelo é larga demais para a tarefa, com ferramentas destrutivas no mesmo conjunto de leituras simples. Status de pedido não precisa de delete workspace.

Não é que o protocolo seja ruim. Ele é um jeito de expor ferramentas, não a causa. E culpar o usuário com um filtro de entrada vem depois. O desenho já entregou uma ferramenta destrutiva para uma tarefa de leitura. Filtre o que o servidor expõe, consolide, e mantenha efeito colateral separado de leitura.

O tratamento

São três refatorações. Consolidar ferramentas, quando há duplicadas, quase gêmeas, ou ferramentas que ninguém chama. É quase sempre o primeiro passo.

Introduzir um roteador, quando mesmo depois de consolidar ainda sobram muitas ferramentas, porque o agente cobre vários assuntos. Cada rota recebe só as suas. O agente de pedidos não precisa ver as ferramentas de RH.

E mover as instruções para a descrição da ferramenta, quando as regras de quando usar cada uma moram no prompt de sistema, longe de onde o modelo realmente escolhe.

Na prática, a ordem é esta. Meça o uso nos traces dos últimos noventa dias. Uma ferramenta que nunca aparece é candidata a sair.

Junte as ferramentas que fazem a mesma coisa com chaves diferentes. Uma ferramenta, vários parâmetros.

Reescreva cada descrição para o momento da escolha. O que faz, quando usar, quando não usar e o que devolve.

E se a lista ainda passa de uma dúzia, e os assuntos são distintos, roteie.

De volta ao pedido do CPF. Antes, quarenta ferramentas visíveis, cinco delas de usuário, e três turnos. Depois, oito ferramentas, e uma delas é find customer, com uma chave e um valor. A primeira chamada já usa o CPF como chave. Um turno.

E digamos que você consolidou, e ainda sobraram vinte e oito ferramentas, porque o mesmo agente atende RH, pedidos e financeiro. A escolha continua ruim em pedidos. Não coloque um bloco no prompt dizendo, se o assunto for pedidos, use só estas. O modelo continua vendo as vinte e oito. A restrição tem que estar na lista que você manda, não na prosa. É isso que o roteador faz.

Quando ignorar

Quando dá para ignorar? Vinte ferramentas de domínios diferentes, com nomes e descrições claros, podem funcionar bem. O smell é confusão, não quantidade. E o contrário também vale. Oito ferramentas, em que três fazem a mesma busca de cliente com chaves diferentes, é esse smell.

Se o seu provedor deixa o modelo ver só um índice e carregar as definições sob demanda, o custo de tokens some. A confusão entre ferramentas parecidas continua.

E num protótipo, começar largo para descobrir o que o agente precisa, e podar depois, tudo bem.

Fechamento

Então, a ideia para levar. O modelo escolhe a partir do que você entrega, no momento da escolha. Entregue menos portas, uma por trabalho, cada uma com uma placa dizendo quando entrar. Você ganha menos turnos, menos tokens e menos jeitos de causar estrago.

Na próxima aula, a gente faz o primeiro corte passo a passo: consolidate tools. Até lá.