Escrever ferramentas e prompts para agentes com limites claros

A descrição de cada ferramenta é o texto que mais pesa na escolha de um agente: a Anthropic a chama de fator de longe mais importante no desempenho com ferramentas. Quem põe um agente nos sistemas da empresa deve reescrever hoje uma descrição em três a quatro frases e escrever no prompt o que exige confirmação humana.

Agente é o modelo que decide sozinho o próximo passo, como um estagiário com acesso ao sistema. Ferramenta é cada ação que ele pode pedir: consultar um pedido, abrir um chamado, emitir um boleto. Quem escolhe entre elas é o modelo, lendo nome, descrição e campos de cada uma.

Quando a escolha sai errada, o agente raramente devolve erro. Ele consulta o pedido de outra pessoa, abre o segundo chamado para o mesmo problema ou tenta três formatos de documento até acertar. O time ajusta o prompt por semanas, e o defeito mora num texto de duas linhas que ninguém revisou.

Chamada de ferramenta (tool use, ou function calling na OpenAI e no Gemini) é um pedido estruturado que o modelo devolve ao aplicativo: o nome da ferramenta e os argumentos em JSON. O modelo nunca executa nada. O aplicativo valida os argumentos, confere a permissão, executa e devolve o resultado, e o modelo decide o passo seguinte com ele. Por isso a autorização mora no código que atende à chamada, e a descrição só orienta a escolha.

A Anthropic descreve a ferramenta como contrato entre um sistema determinístico (que sempre responde igual) e um agente que não é. O guia de 11/09/2025 pede poucas ferramentas, cada uma resolvendo um trabalho inteiro, com prefixo de serviço no nome e retorno enxuto. A OpenAI resume o mesmo critério no teste do estagiário: alguém novo na empresa, lendo só a descrição, saberia usar a função?

Três mudanças separam 2026 de 2024. O modo estrito (strict) só deixa sair a chamada que obedece ao esquema dos campos, como formulário que recusa campo fora do padrão. A busca de ferramentas carrega a definição só quando o agente precisa dela. E nos modelos Claude mais recentes, forçar uma ferramenta específica passou a devolver erro.

Uma descrição de ferramenta boa responde a quatro perguntas: o que faz, quando usar, o que ela não faz e o que significa cada retorno, inclusive o vazio. A documentação da Anthropic pede no mínimo três a quatro frases por ferramenta e aceita o campo input_examples (exemplos de argumentos válidos, como um formulário já preenchido) para campos difíceis. A OpenAI faz uma ressalva: em modelos de raciocínio, exemplos podem piorar a escolha, então teste com e sem eles.

O erro mais caro é a descrição que só repete o nome da função. O agente escolhe por semelhança, chuta o formato do campo e trata resposta vazia como falha, repetindo a chamada. Cada tentativa é cobrada e nenhuma aparece como erro no relatório.

Quantidade de ferramentas também pesa. A OpenAI recomenda menos de 20 funções disponíveis no início do turno. Acima disso, a saída é a busca de ferramentas (tool search): as definições ficam marcadas com defer_loading e só entram no contexto quando o agente as procura, como um catálogo consultado sob demanda. O MCP (Model Context Protocol, padrão aberto que liga agentes a sistemas, como uma tomada universal) entrega essas ferramentas prontas, e cada uma chega com a descrição que o autor do servidor escreveu.

Chamadas paralelas (parallel tool use, várias consultas disparadas de uma vez, como pedir três orçamentos no mesmo e-mail) são o padrão no Claude e no Grok. O aplicativo executa todas e, no Claude, devolve os resultados juntos numa única mensagem. Quando a ordem importa, como consultar antes de alterar, escreva no prompt que a alteração espera o resultado da consulta; na OpenAI e no Grok, parallel_tool_calls: false limita o turno a uma chamada.

As regras mudam por fornecedor no que quebra produção: forçar ferramenta, limite de ferramentas estritas e o que reenviar entre chamadas.

Permissão é a parte que o prompt declara e o código confirma. Simon Willison chamou de tríade letal (16/06/2025) o agente que reúne acesso a dados privados, leitura de conteúdo de terceiros e um canal para enviar dados para fora: basta uma instrução escondida num e-mail para vazar o cadastro. Remover uma das três peças desfaz o ataque, e a confirmação humana antes de ações sensíveis é a defesa operacional que sobra quando as três precisam existir.

A decisão de pedir confirmação segue duas perguntas: a ação se desfaz com um clique e o impacto cabe num limite escrito? Consultas rodam sozinhas e em paralelo. Mudança de endereço, reembolso e cancelamento esperam o sim, e o prompt diz isso com todas as letras, porque o GPT-6, segundo a própria OpenAI, prefere seguir até o fim e só pede aprovação com o resultado pronto.

Faça hoje

Abra a lista de ferramentas do agente que sua equipe já usa e escolha a que mais aparece em chamadas repetidas. Reescreva a descrição em três a quatro frases, ligue strict, feche o esquema e acrescente ao prompt a lista do que executa sozinho e do que espera confirmação. Em 30 minutos, rode as três perguntas do guia; deu certo quando a consulta sai em uma chamada e a alteração aparece como proposta antes de qualquer execução.