Uma tool é o contrato entre o agente e o mundo real: uma função com nome claro, descrição que o modelo entende e schema de entrada e saída tipado. O insight que orienta o desenho: a maioria dos erros de agente nasce na ferramenta mal desenhada, e não no modelo. As regras de ouro: nome verbo + objeto (buscar_pedido, não dados); descrição escrita para um estagiário talentoso que nunca viu o sistema; schema com tipos, campos obrigatórios e exemplos; granularidade média (nem ferramenta única de 20 parâmetros, nem 40 micro-ferramentas); e saída com mensagem de erro acionável, para o agente se corrigir sozinho.
O que é uma ferramenta (tool) de agente?
É a função que o modelo pode chamar para agir ou consultar: buscar pedido, verificar estoque, criar agendamento, enviar mensagem. O fluxo de tool calling: o modelo recebe a lista de ferramentas disponíveis com suas descrições, decide qual chamar diante do objetivo, monta os parâmetros no schema e devolve a chamada; a sua aplicação executa e devolve o resultado, que volta ao modelo como observação do próximo passo. O modelo nunca executa nada direto: ele propõe chamadas, e a sua infraestrutura valida e executa. Essa separação é a fronteira de segurança do agente.
As 4 regras do desenho de ferramenta
- Nome verbo + objeto:
buscar_pedido_por_numerodiz o que faz;dadosouapi_v2obrigam o modelo a adivinhar. O nome é a primeira pista da escolha. - Descrição para um estagiário talentoso: o que faz, quando usar, quando não usar, o que retorna e as pegadinhas ("não use para pedidos cancelados; use consultar_historico"). Descrição vaga é a causa nº 1 de ferramenta errada chamada.
- Schema tipado e enxuto: tipos explícitos, campos obrigatórios marcados, valores padrão sensatos e exemplos no documento. Campo opcional demais gera chamada preguiçosa; obrigatório demais gera falha em cascata.
- Erro acionável na saída: quando falha, retorne uma mensagem que diz o que corrigir ("CPF inválido: 11 dígitos esperados"), e não "erro 500". O agente se corrige na próxima volta do loop quando a mensagem orienta.
Granularidade: o equilíbrio que quase todo mundo erra
Os dois extremos falham por razões opostas. Ferramenta única de 20 parâmetros ("gerenciar_sistema"): o modelo se perde no schema, e qualquer mudança quebra tudo. Quarenta micro-ferramentas: a lista não cabe na atenção do modelo, e escolhas parecidas competem entre si. O ponto de equilíbrio prático: uma ferramenta por intenção do usuário (buscar, criar, atualizar, cancelar), com parâmetros cobrindo as variações. Entre 5 e 15 ferramentas bem nomeadas, a maioria dos casos de uso funciona; acima disso, agrupe por domínio e forneça uma ferramenta de descoberta.
Antes de conectar a ferramenta ao sistema de produção, rode o teste de chamada seca: dê ao modelo os casos de teste com os objetivos em linguagem natural e confira qual ferramenta ele escolhe e com quais parâmetros. Ajuste nomes e descrições com base no que ele errou (o modelo é o melhor revisor do seu desenho de schema). Só depois ligue a execução real, com validação do lado da aplicação e log de todas as chamadas. A avaliação de trajetória do guia de construção de agentes usa exatamente essa base.
Segurança: o que a ferramenta pode fazer
A fronteira de segurança vive no desenho da ferramenta, não no prompt. As práticas: escopo mínimo (a ferramenta só acessa o que precisa), validação no lado da aplicação (o schema do modelo é sugestão; a validação real é sua), confirmação humana para ações irreversíveis (pagamento, cancelamento, exclusão: o padrão WebMCP, que o guia de implementação do WebMCP detalha, adota exatamente esse princípio), log completo de cada chamada (quem pediu, o que o modelo propôs, o que executou) e rate limit por ferramenta para conter loops. Prompt de sistema instrui; o desenho da ferramenta é que impede.
Checklist de entrega da ferramenta
- Nome verbo + objeto, único na lista de ferramentas.
- Descrição com: o que faz, quando usar, quando não usar, o que retorna.
- Schema com tipos, obrigatórios, padrões e exemplo de chamada.
- Erros retornam mensagem acionável em linguagem natural.
- Validação e log no lado da aplicação; confirmação humana nas ações irreversíveis.
- Casos de teste de chamada seca aprovados antes do ligamento real.