Esquema de ferramentas para agentes de IA: nomes e tipos que funcionam
Nomes e tipos para esquemas de ferramentas de agentes de IA: verbos no início, argumentos tipados, enums e descrições que orientam a escolha.

Um esquema de ferramentas informa ao modelo como se chama uma função, o que ela faz e quais argumentos aceita. O modelo escolhe a ferramenta certa e preenche os argumentos de forma confiável quando cada ferramenta tem um nome no formato verbo mais objeto, ligado a uma única ação de negócio, uma descrição que diz quando usar e quando não usar, e parâmetros estreitos, tipados, com valores permitidos explícitos. Acerte essas três coisas antes de adicionar mais ferramentas.
Principais pontos
- Nomeie cada ferramenta com uma única ação de negócio, usando verbo e objeto, como list_open_orders ou draft_email_reply, e nunca um nome vago como process ou handle.
- Dê a cada argumento um tipo preciso, uma descrição curta e uma faixa permitida ou um enum, para que o modelo não invente valores que seu sistema vai rejeitar.
- Separe ações de leitura, rascunho e escrita em ferramentas diferentes, para que os limites de permissão fiquem no esquema e não apenas em um prompt.
- Teste os esquemas com pedidos realistas, registre escolhas erradas de ferramenta e argumentos errados, e corrija o esquema antes de reescrever o prompt.
Por que o esquema importa mais que o prompt
Quando um agente decide chamar uma ferramenta, ele lê o nome, a descrição e a definição dos parâmetros, e só então escolhe. A maior parte das falhas vem de ambiguidade: duas ferramentas com nomes parecidos, um campo de texto livre onde era obrigatório um código de registro, uma data sem formato definido, ou um parâmetro que parece opcional, mas é necessário. Um prompt de sistema mais longo raramente resolve esses problemas. Um esquema mais claro normalmente resolve.
Isso pesa mais à medida que o agente ganha ferramentas. Cada nova função acrescenta uma escolha que o modelo precisa fazer corretamente, e cada sobreposição entre duas funções aumenta a chance de uma chamada errada. Por isso, desenhar ferramentas é uma decisão de operações, não apenas um detalhe técnico. Quem é dono do processo de negócio deveria conseguir ler a lista de ferramentas e entender o que o agente pode fazer.
Regras de nomenclatura que ajudam o modelo a escolher
Bons nomes são previsíveis. O modelo deve conseguir adivinhar a ferramenta certa só pelo pedido, e uma pessoa que lê os registros deve entender cada chamada sem abrir o código. Algumas regras cobrem a maioria dos casos:
- Use um verbo mais um objeto: search_invoices, get_customer_by_email, draft_email_reply.
- Dê a cada verbo um único significado. Use get para um registro específico já conhecido, list para uma coleção, create para um registro novo e update para alterar um registro existente.
- Evite quase-duplicatas. update_customer e modify_customer serão confundidas, e o modelo tende a escolher a que viu por último.
- Use as palavras que sua equipe usa para o sistema, não jargão interno. Se a equipe diz “pedido de compra”, a ferramenta deve dizer pedido de compra, e não po_entity.
- Mantenha os nomes estáveis. Renomear uma ferramenta quebra prompts, avaliações salvas e buscas nos registros, então mude nomes apenas com uma nota de versão.
- Deixe as ações arriscadas visíveis no nome. Ferramentas que enviam, publicam, cancelam ou pagam nunca devem compartilhar prefixo com ferramentas de leitura, para que um revisor consiga percorrer a lista e ver a superfície de escrita de relance.
Um teste útil: leia a lista de ferramentas em voz alta, como se fosse um funcionário novo. Se dois nomes parecem ser o mesmo trabalho, renomeie ou una as ferramentas.
Tipar argumentos para que valores errados falhem cedo
O tipo de cada argumento é a primeira linha de defesa. Um campo tipado dá ao modelo um alvo claro e dá ao seu sistema um motivo claro para rejeitar uma entrada ruim antes de qualquer coisa ser executada.
Adote estes hábitos para todo parâmetro:
- Declare o tipo real: inteiro para quantidades, texto para identificadores, booleano apenas para perguntas de sim ou não.
- Use enums para listas fechadas. Um campo de status que aceita rascunho, aprovado, enviado é mais seguro que texto livre, porque o modelo não consegue escrever “quase enviado”.
- Especifique o formato de datas e horários, como ISO 8601, e diga se o valor é uma data local ou um carimbo de tempo com fuso horário.
- Trate identificadores como cadeias opacas vindas do sistema de origem. Dê ao modelo uma ferramenta de busca para encontrar o identificador, em vez de pedir que ele o digite de memória.
- Defina limites para números e listas. Um parâmetro como max_results com um máximo declarado impede que uma única chamada puxe a base inteira.
- Marque um campo como obrigatório apenas quando a ferramenta não pode rodar sem ele. Campos opcionais demais levam o modelo a adivinhar.
- Mantenha um conceito por campo. Não coloque nome, valor e data dentro de uma mesma string, porque seu sistema então precisará interpretar o que o modelo escreveu.
As regras de tipo também ajudam seus registros. Quando todo argumento tem uma forma conhecida, uma chamada que falha mostra qual campo estava errado, o que é muito mais útil do que um erro genérico.
Descrições são instruções para o modelo
O campo de descrição é onde muitas equipes deixam de escrever com cuidado, mas ele faz boa parte do trabalho na escolha da ferramenta. Uma boa descrição informa quatro coisas: o que a ferramenta faz, quando ela deve ser usada, quando não deve ser usada e o que devolve. Também deve dizer se a ferramenta produz efeitos colaterais.
Por exemplo, a descrição de uma ferramenta de leitura pode dizer que ela devolve os pedidos em aberto de um cliente, que deve ser usada antes de responder qualquer pergunta sobre o status de um pedido e que nunca altera dados de pedidos. A descrição de uma ferramenta de escrita deve dizer que ela cria um rascunho, e não uma mensagem enviada, e que uma pessoa precisa aprovar antes de o rascunho ser liberado. Mantenha as descrições simples e específicas. Parágrafos longos de política dentro de uma descrição são mais difíceis de aplicar do que duas frases curtas que nomeiam o limite.
A descrição também não deve ser a única proteção. Uma permissão que importa precisa ser aplicada pelo sistema que recebe a chamada, porque um modelo pode interpretar mal até uma descrição clara. O esquema orienta a escolha, e a camada de permissões limita o dano quando a escolha estiver errada.
Cenário ilustrativo: uma dúvida de reembolso em uma fila de suporte
Cenário ilustrativo, não é um caso de cliente: uma equipe de suporte quer que um agente responda dúvidas sobre reembolso. Na primeira versão, uma única ferramenta chamada handle_refund aceita um pedido em texto livre e um valor opcional. Às vezes o agente emite reembolsos quando deveria apenas explicar a política, e às vezes envia o valor errado, porque o valor chegava como texto com o símbolo da moeda.
Na versão revisada, a equipe separa o trabalho em três ferramentas. get_order_by_number recebe um número de pedido obrigatório que segue um padrão fixo e devolve o status e o valor pago. check_refund_policy recebe um enum com a categoria do produto e devolve o texto da política. create_refund_request recebe um identificador de pedido, um valor inteiro na menor unidade monetária e um motivo de uma lista fixa. Ela cria uma solicitação para uma pessoa aprovar e nunca libera dinheiro. O problema do valor errado desaparece, porque o tipo é inteiro, o motivo não pode ser inventado e a ação de escrita aparece separada das ações de leitura.
Depois, a equipe roda o mesmo conjunto de perguntas realistas nas duas versões e compara as chamadas. A mudança está no que o modelo pode escolher, e não em quão inteligente o modelo é.
Como a Be Human trata esquemas de ferramentas em operações gerenciadas
Em um projeto da Be Human, o primeiro passo é definir o único papel que o agente vai desempenhar e, depois, listar as ferramentas que esse papel realmente precisa. Nomes, tipos de argumento e descrições são escritos junto com as pessoas responsáveis por cada sistema conectado, para que o vocabulário corresponda ao do negócio. Ações de leitura, rascunho e escrita são mantidas como ferramentas separadas desde o início, e cada caminho de escrita leva a uma etapa de aprovação definida nas regras de operação. Depois do lançamento, avaliações recorrentes revisam os registros de chamadas em busca de escolhas erradas e argumentos errados, e mudanças no esquema seguem a mesma revisão das mudanças de permissão. Quando um fornecedor altera uma API, as definições de ferramenta afetadas são atualizadas e testadas antes de voltar à produção.
Teste os esquemas com pedidos realistas antes de confiar neles
Um esquema é uma hipótese até ser testado. Monte um conjunto pequeno de pedidos realistas, tirados de chamados, e-mails ou mensagens reais, e inclua os casos difíceis: pedidos com detalhes faltando, pedidos que parecem duas tarefas ao mesmo tempo e pedidos que não deveriam acionar ferramenta alguma. Registre qual ferramenta o agente escolheu, quais argumentos enviou e se o sistema aceitou. Separe três tipos de falha: ferramenta errada, argumento errado e falta de confirmação antes de uma escrita. Cada tipo aponta para uma correção diferente. Ferramenta errada costuma indicar problemas de nome ou de sobreposição. Argumento errado costuma indicar problemas de tipo ou de descrição. Falta de confirmação significa que a etapa de aprovação está ausente ou não está clara.
Repita o teste após cada mudança no esquema. Para uma equipe de negócio, a versão prática é uma planilha curta com os pedidos, uma coluna para a ferramenta esperada e uma coluna para o que de fato aconteceu. Se quiser uma visão mais ampla de como montar essa planilha, o checklist para aceitar uma integração de agente de IA reúne as perguntas que devem ser resolvidas antes da entrada em operação.
Mantenha a lista de ferramentas pequena, visível e revisada
Mais ferramentas não tornam um agente mais capaz. Elas dificultam a escolha correta e a auditoria por um revisor. Comece com o menor conjunto que completa um papel, registre a finalidade de cada ferramenta em uma lista compartilhada e remova as que deixaram de se justificar. Uma matriz de permissões de ferramentas para agentes de IA que lista cada ferramenta, seu nível de acesso e quem aprova torna a revisão mais rápida, porque a superfície de escrita fica em um único lugar. Quando adicionar uma ferramenta depois, inclua-a na lista, no conjunto de avaliação e nos registros na mesma mudança.
Se você não tem certeza de qual tarefa do seu negócio deve ser a primeira a passar para um agente, o diagnóstico gratuito de IA da Be Human pode ajudar a encontrá-la.
Perguntas frequentes
Quantas ferramentas um agente deve ter? Comece com o menor número de ferramentas que completa um papel definido, normalmente entre três e seis em um primeiro projeto. Cada ferramenta extra acrescenta uma escolha que o modelo precisa fazer corretamente, então adicione uma ferramenta somente quando um pedido real não puder ser concluído sem ela. Revise a lista sempre que o papel mudar.
As regras devem ficar no esquema ou no prompt de sistema? Coloque no esquema as regras que moldam cada chamada, como valores permitidos e campos obrigatórios, porque é ali que o modelo lê as definições dos parâmetros. Coloque a política operacional mais ampla nas instruções, e aplique no sistema que recebe a chamada tudo o que nunca pode ser quebrado. Um prompt pode ser ignorado ou mal interpretado, mas um argumento rejeitado não chega a ser enviado.
Qual é o erro mais comum na nomenclatura de ferramentas? O erro mais comum é dar a duas ferramentas nomes que descrevem quase o mesmo trabalho, como search e find ou update e modify. O modelo então escolhe entre elas de forma inconsistente, e os registros mostram chamadas que parecem quase certas. Una as ferramentas sobrepostas ou renomeie-as, para que cada par verbo e objeto tenha um único significado claro.
Como saber se uma mudança no esquema funcionou? Execute o mesmo conjunto de pedidos realistas antes e depois da mudança e compare qual ferramenta foi escolhida, quais argumentos foram enviados e se o sistema aceitou. Uma mudança que melhora um tipo de pedido, mas quebra outro, deve ser desfeita ou refinada. Guarde o conjunto de testes e os resultados junto com a versão do esquema, para que o histórico continue legível.
Seu próximo passo
Descubra primeiro onde um agente de IA cabe na sua empresa.
Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.
Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.


