Agentes que usam ferramentas (tool use)

Meu primeiro agente com ferramentas tinha uma função chamada "buscar" com a descrição "busca dados". O modelo a chamava para tudo, inclusive para o que não era busca, e errava metade das vezes. Renomeei para "buscar_campanhas_por_periodo", escrevi três frases de descrição e defini os parâmetros com exemplos. Os erros praticamente sumiram. A lição: a ferramenta é escrita para o modelo ler, não para o programador.

Este guia explica como o modelo chama funções, como definir ferramentas que ele use bem, a diferença entre leitura e escrita e o que padronizar quando você tem várias.

Como funciona a chamada de ferramenta

Você descreve as ferramentas disponíveis (nome, o que faz, parâmetros). O modelo, ao decidir que precisa de uma, devolve uma chamada estruturada: qual ferramenta e com quais argumentos. Seu código executa, devolve o resultado, e o modelo continua o raciocínio com ele. O modelo não executa nada; ele pede, o seu sistema faz.

Isso é o que permite que um agente leia uma planilha, consulte uma API ou crie uma tarefa sem que essas capacidades estejam "dentro" do modelo.

Descrevendo uma ferramenta bem

Nome específico em verbo e objeto. Descrição que diz o que faz, quando usar e quando não usar. Parâmetros com tipo, descrição e exemplo de valor. "periodo: string no formato AAAA-MM-DD/AAAA-MM-DD, por exemplo 2026-09-01/2026-09-15". Erros de argumento caem quando o exemplo existe.

Diga também o que a ferramenta devolve, para o modelo saber o que esperar e não reinterpretar o resultado.

Leitura e escrita não são iguais

Ferramentas de leitura (consultar, buscar, listar) podem ser chamadas livremente: o pior caso é uma consulta inútil. Ferramentas de escrita (criar, enviar, apagar, pagar, publicar) mudam o mundo, e o pior caso é um e-mail errado para um cliente ou um registro apagado.

Regra que uso: toda escrita passa por confirmação humana ou roda primeiro em modo de simulação que mostra o que faria. Só depois de semanas de simulação limpa eu libero execução direta, e mesmo assim com registro e possibilidade de desfazer.

Idempotência

Se o agente chamar a mesma ferramenta de escrita duas vezes por engano, o efeito deve ser um só. Criar tarefa duplicada é chato; cobrar duas vezes é grave. Projete a ferramenta para tolerar repetição.

Quantas ferramentas um agente aguenta

Dezenas em teoria; na prática, o desempenho cai quando há muitas parecidas. O modelo hesita entre "buscar_campanhas" e "listar_campanhas" se as descrições não deixarem claro. Agrupe, diferencie nas descrições e remova as que quase nunca são chamadas. Registre qual ferramenta foi chamada em cada passo: isso mostra rapidamente as confusas.

MCP: ferramentas padronizadas

O Model Context Protocol é um padrão para expor ferramentas de um serviço (e-mail, Drive, CRM, banco de dados) de forma que qualquer assistente compatível as use. Em vez de escrever integração por integração, você conecta um servidor MCP e as ferramentas aparecem descritas. Serve tanto para usar serviços prontos quanto para expor os do seu próprio sistema.

Erros de ferramenta e como tratá-los

Ferramentas falham: API fora do ar, arquivo não encontrado, período sem dados. O resultado da chamada deve voltar para o modelo como erro legível ("nenhuma campanha no período informado"), não como exceção crua. Com uma mensagem clara, o modelo ajusta o argumento ou informa que não há dado; com uma exceção, ele tenta de novo com os mesmos argumentos ou inventa.

Coloque também um limite de tentativas por ferramenta. Três chamadas iguais seguidas com erro é sinal de loop, e o agente deve parar e reportar, não insistir. Esse limite simples é o que mais me poupou crédito.

Testando ferramentas

Monte um conjunto de pedidos que deveriam chamar cada ferramenta e um conjunto que não deveria. Rode e confira. Ferramenta que é chamada quando não deveria tem descrição ampla demais; ferramenta que não é chamada quando deveria tem descrição vaga ou nome ruim. Ajuste a descrição, não o modelo.

Perguntas frequentes

Fontes e método

• Documentação de tool use e de MCP da Anthropic
• Ferramentas próprias em agentes de operação de mídia, 2025 e 2026