Você configura uma ferramenta para o agente, testa uma vez, parece funcionar, e aí coloca em produção. Na segunda semana o agente começa a chamar a ferramenta com parâmetros que não existem. Ou pior: fica em loop, chamando a mesma ferramenta três vezes seguidas sem conseguir avançar. Você abre o log e não entende o que aconteceu.
Isso não é bug do modelo. Na maioria dos casos, é problema de design da ferramenta.
Tool use em agentes de IA tem uma taxa de falha que a maioria dos tutoriais ignora. O exemplo bonito funciona porque foi construído para funcionar naquela condição específica. Em produção, com dados reais e fluxos imprevisíveis, as coisas quebram de jeitos que você não testou.
Trabalho com agentes há tempo suficiente para ter visto esse ciclo várias vezes: a ferramenta parece simples, o modelo parece inteligente, a expectativa é que a combinação vai funcionar naturalmente. Não funciona. O que funciona é projetar a ferramenta pensando em como o modelo vai interpretá-la, não em como você, humano, interpretaria.
Aqui você vai entender o que diferencia uma ferramenta que funciona de uma que quebra no primeiro caso não previsto, onde o design costuma falhar e o que validar antes de colocar qualquer coisa em produção.
O que é tool use em agentes de IA e por que a parte difícil fica escondida
Tool use é a capacidade do modelo de chamar funções externas durante a geração de uma resposta. Em vez de só responder em texto, o modelo decide que precisa de informação ou precisa executar algo, emite uma chamada estruturada, recebe o resultado e continua a partir daí.
O que os tutoriais mostram é sempre o caso feliz: o modelo chama a ferramenta certa, com os parâmetros certos, recebe um resultado limpo e segue. O problema é que esse cenário depende de decisões de design que o tutorial não menciona porque, no exemplo simples, elas não importam. Em produção, importam muito.
A documentação oficial da Anthropic sobre tool use cobre a mecânica bem. O que não cobre é o que fazer quando o modelo começa a usar suas ferramentas de formas que você não esperava.
Quando o tool use quebra (sinais de que algo está errado no design)
O modelo não chama a ferramenta quando deveria
O modelo lê a descrição da ferramenta e decide se ela se aplica ao contexto atual. Se a descrição for vaga ou genérica demais, o modelo frequentemente opta por responder sem chamar a ferramenta, achando que consegue resolver por conta própria. O resultado é uma resposta que parece razoável mas é inventada.
O modelo chama a ferramenta com parâmetros errados ou inventados
Se os parâmetros aceitam formatos ambíguos (datas, identificadores, categorias) sem instrução explícita, o modelo vai inferir. Às vezes infere certo. Às vezes inventa um valor que parece razoável mas não existe no sistema real, e aí o erro aparece na camada errada.
O modelo entra em loop após uma falha
Quando a ferramenta retorna erro e o modelo não sabe o que fazer com aquele erro, ele pode tentar chamar a ferramenta novamente com parâmetros levemente diferentes, esperando um resultado diferente. Sem limite de tentativas e sem tratamento explícito de erro, o agente fica preso e consome tokens sem entregar nada.
O modelo usa a ferramenta certa na ordem errada
Em fluxos com múltiplas ferramentas, o modelo precisa entender dependências. Se a descrição não deixa claro que a ferramenta B precisa do resultado da ferramenta A, ele pode tentar chamar B primeiro e receber um resultado inválido que parece válido.
Como projetar uma ferramenta que o agente consegue usar
Nome e descrição são instruções, não rótulos
O modelo usa o nome e a descrição da ferramenta para decidir quando e como chamá-la. Uma descrição genérica não diz nada útil. Uma descrição que responde quando usar, o que a ferramenta retorna e o que ela não cobre diz muito.
Se a ferramenta busca pedidos mas não histórico de pagamentos, escreva isso explicitamente. O modelo vai tentar usar a ferramenta para tudo que parece relacionado a pedidos, incluindo pagamentos, se você não delimitar.
Parâmetros simples e formatos sem ambiguidade
Quanto menos o modelo precisar inferir sobre o formato esperado, melhor. Parâmetro de data com exemplo do formato aceito, lista de opções válidas quando o campo é categórico, instrução sobre o que colocar quando o valor for desconhecido. Cada campo sem instrução é uma chance de o modelo errar de um jeito difícil de rastrear.
O retorno precisa ser interpretável, não apenas correto
Uma ferramenta que retorna um objeto grande com dezenas de campos está passando a responsabilidade de filtrar para o modelo. Na prática, o modelo às vezes usa o campo errado. Retorne o mínimo necessário para o passo seguinte. Metadados internos que o modelo não precisa para continuar o fluxo não deveriam estar no retorno.
Defina o que acontece quando a ferramenta falha
Erro genérico é inútil para o modelo. A mensagem de erro é, na prática, uma instrução para o próximo passo. Se a ferramenta não encontrar o recurso solicitado, a mensagem precisa sugerir o que tentar em seguida, não apenas informar que falhou.
Uma ferramenta vs muitas ferramentas: quando dividir e quando não dividir
Pra mim, esse é o ponto onde a maioria das implementações erra por um dos dois extremos.
Ferramenta única que faz tudo: o modelo recebe uma ferramenta com quinze parâmetros, metade opcionais, e precisa entender quando usar cada combinação. A probabilidade de erro escala com a complexidade.
Muitas ferramentas pequenas demais: o modelo fica com um catálogo de vinte funções para um fluxo simples e começa a chamar coisas desnecessárias ou na ordem errada.
A divisão certa é por intenção, não por operação técnica. Se duas operações sempre acontecem juntas, talvez sejam uma ferramenta só. Se uma operação faz sentido sozinha, sem depender de outra, ela merece ser separada. Quando o número de ferramentas passa de oito ou dez em um único agente, vale considerar dividir em agentes especializados, não por princípio arquitetural, mas porque a taxa de acerto do roteamento cai na prática.
Esse raciocínio se conecta diretamente a como você define o que o agente precisa manter em memória entre chamadas, porque memória e tool use compartilham o mesmo orçamento de contexto.
O que esperar de um agente com tool use bem projetado
Quando o design está correto, o comportamento é previsível, mas não mágico:
- O modelo chama a ferramenta certa na primeira tentativa na maioria dos casos
- Erros retornam com contexto suficiente para o modelo tentar uma alternativa
- O agente completa o fluxo sem loop em situações que não foram explicitamente testadas
- Logs de execução mostram chamadas com parâmetros que fazem sentido, não valores inventados
- O comportamento em produção é parecido com o comportamento nos testes
Nenhum desses pontos garante zero erro. Garantem que os erros são raros e rastreáveis, não aleatórios e inexplicáveis. A diferença importa muito na hora de depurar.
O impacto de colocar ferramentas em produção sem validar o design
O problema não é a primeira semana. É a segunda e a terceira, quando os casos de uso reais começam a aparecer.
Um agente que entra em loop consome tokens sem entregar resultado. Em volume, isso aparece na fatura antes de aparecer nos logs. Um agente que chama ferramentas com parâmetros errados vai fazer operações que você não esperava: buscar o registro errado, acionar o fluxo errado, retornar dado de um contexto diferente sem sinalizar que algo deu errado.
O custo operacional de corrigir um design ruim depois que está em produção é alto porque envolve rastrear histórico de execuções, identificar padrões de falha e refazer testes. Fazer isso antes é uma tarde de trabalho. Fazer depois de incidente é uma semana, dependendo do volume.
Se você quer ir além do design das ferramentas e controlar também o que o agente pode ou não pode fazer com elas, vale ler sobre guardrails para IA em produção.
Dúvidas comuns sobre tool use em agentes de IA
Quantas ferramentas um agente pode ter?
Não existe número fixo, mas acima de oito a dez ferramentas a qualidade de roteamento começa a cair na prática. O limite real depende de quão distintas são as ferramentas e de quão bem as descrições as diferenciam. Ferramentas com propósito parecido descritas de forma parecida são receita de ambiguidade.
O modelo sempre vai usar a ferramenta mais relevante?
Não. O modelo escolhe com base nas descrições. Se duas ferramentas têm descrições parecidas, o modelo vai escolher de forma inconsistente entre execuções. Diferenciação clara nas descrições resolve na maioria dos casos, mas não em todos.
Preciso testar tool use diferente de outros testes?
Sim. Testes de tool use precisam incluir casos onde a ferramenta falha, casos onde o parâmetro é ambíguo e casos onde o modelo poderia responder sem usar a ferramenta. O caso feliz não é representativo do comportamento em produção.
Quando faz sentido usar MCP em vez de tool use direto?
MCP faz sentido quando você quer reutilizar servidores de ferramentas entre diferentes agentes ou modelos, ou quando a ferramenta precisa ser acessível fora do contexto do agente. Para um agente único com ferramentas específicas do domínio, tool use direto é mais simples e mais fácil de depurar. Se o assunto é novo para você, tem um guia sobre MCP na prática que cobre essa distinção em mais detalhe.
Próximo passo
Tool use em agentes de IA não falha por limitação do modelo. Falha por descrição vaga, parâmetro ambíguo, retorno de erro inútil e divisão de responsabilidade mal pensada. São problemas de design, e design tem solução antes mesmo de escrever uma linha de código.
Se você já tem um agente em produção com tool use instável, o primeiro lugar para olhar é a descrição de cada ferramenta. Não o modelo, não a infraestrutura. A descrição.
- Revise as descrições das suas ferramentas com foco em quando usar, o que retorna e o que não cobre
- Teste explicitamente os casos de falha, não só o caminho feliz
- Defina mensagens de erro que orientam o próximo passo do modelo
Se quiser entender como orquestrar múltiplos agentes com ferramentas especializadas, o artigo sobre LangGraph na prática mostra como esse fluxo funciona em escala.