Schema de ferramentas para agentes de IA: nomes, descrições e erros
Nomes, descrições de parâmetros e mensagens de erro decidem qual ferramenta um agente de IA chama. Regras práticas, checklist e testes para cortar escolhas erradas.

Um bom design de schema de ferramentas para agentes de IA significa escrever cada nome de ferramenta, cada descrição e cada parâmetro de forma que o modelo consiga entender, só pela definição, qual ferramenta serve a um pedido e quais valores passar. O schema é a única descrição dos seus sistemas que o modelo lê, então a redação dele decide a maior parte das escolhas de ferramenta. Quando um nome é vago ou um parâmetro não tem explicação, o agente adivinha, e é nesses palpites que começam os registros duplicados, as buscas erradas e as gravações recusadas.
Principais pontos
- Dê a cada ferramenta um verbo e um objeto, e garanta que duas ferramentas não consigam responder plausivelmente ao mesmo pedido.
- Escreva cada descrição como uma regra de decisão: quando usar a ferramenta, quando não usar e o que ela devolve.
- Defina para cada parâmetro um tipo, um formato, os valores permitidos e a origem declarada, para que o modelo não invente valores.
- Escreva mensagens de erro que indiquem o campo que falhou, mostrem um valor válido e digam se uma nova tentativa é segura.
- Teste o schema com um conjunto fixo de pedidos realistas antes e depois de cada mudança, e leia cada falha.
Por que o agente escolhe a ferramenta errada antes de qualquer código rodar
O agente não enxerga o seu software. Ele enxerga uma lista de nomes de ferramentas, descrições e definições de parâmetros, e escolhe entre elas lendo esse texto. A maior parte das escolhas erradas é previsível a partir do próprio schema. Duas ferramentas têm nomes que se sobrepõem, uma descrição explica o que um sistema faz, mas nunca quando usá-lo, ou um parâmetro se chama id sem nenhuma nota sobre qual identificador é esperado.
As notas de engenharia da Anthropic sobre como escrever ferramentas para agentes defendem um raciocínio parecido: as ferramentas devem ser desenhadas em torno das tarefas que o agente precisa concluir, e as descrições merecem o mesmo cuidado que o código por trás delas. Uma ferramenta que empacota cada endpoint de uma API de fornecedor dá ao modelo muitas opções quase idênticas. Uma ferramenta feita para uma tarefa só dá a ele uma escolha óbvia.
Trate o schema como parte do produto. Cada mudança em um nome ou em uma descrição altera o comportamento, mesmo quando o código por baixo continua idêntico.
Nomeie as ferramentas para que nenhuma duas respondam à mesma pergunta
Um bom nome de ferramenta carrega três informações: a ação, o objeto e, quando for relevante, a direção do fluxo de dados. Nomes como processar, tratar, rodar ou atualizar_registro obrigam o modelo a ler a descrição antes de conseguir aceitar ou descartar a ferramenta, e muitos modelos não leem com atenção sob pressão.
Use estas regras ao nomear ferramentas:
- Comece com um verbo que corresponda à ação real, como buscar, obter, rascunhar, criar, cancelar ou aprovar.
- Nomeie o objeto sobre o qual a ferramenta age, como fatura, cliente ou agendamento.
- Mantenha ferramentas de leitura e de escrita visivelmente separadas, para que uma gravação nunca pareça uma consulta.
- Deixe explícita, no nome, a diferença entre duas ferramentas parecidas. Uma ferramenta de obter recebe um identificador conhecido, enquanto uma de buscar recebe texto livre e devolve uma lista.
- Evite nomes que descrevam a parte interna de um fornecedor, já que o modelo precisa da tarefa de negócio, e não do endpoint.
Se um nome precisa de uma descrição longa para ser entendido, provavelmente ele é vago demais. Para aprofundar convenções de nomes, veja a discussão sobre nomes e tipos de ferramentas que funcionam.
Escreva descrições como regras de decisão
A descrição é onde o modelo aprende a fronteira de cada ferramenta. Uma descrição que só diz o que a ferramenta faz deixa o modelo adivinhar quando usá-la. Uma descrição útil responde a quatro perguntas: o que a ferramenta faz, quando usá-la, quando não usá-la e o que muda como resultado da chamada.
Um modelo prático para cada descrição:
- Uma frase que declare a ação e o objeto.
- As situações concretas em que esta ferramenta é a escolha certa.
- A ferramenta vizinha a usar no lugar, citada exatamente, para os casos em que esta não se encaixa.
- O que o resultado contém, e se ele pode vir parcial ou paginado.
- Se a chamada altera algum registro, dito em linguagem simples, como cria um rascunho pendente, nunca envia ou cancela imediatamente.
Cenário ilustrativo: uma empresa dá a um agente duas ferramentas, uma que rascunha um pedido de reembolso e outra que emite o reembolso. A descrição do rascunho diz que ele cria uma solicitação pendente para uma pessoa aprovar e que nunca movimenta dinheiro. A descrição da emissão diz que ela exige uma referência de aprovação e que não deve ser usada para responder se um reembolso já existe. Quando um cliente pergunta se o reembolso foi pago, o agente chama a ferramenta de consulta, e não nenhuma das duas de escrita, porque as duas descrições dizem isso.
A descrição é uma regra que o modelo consegue conferir contra o pedido que tem à frente.
Faça cada parâmetro se explicar
Os parâmetros causam as falhas mais silenciosas. O modelo os preenche com valores plausíveis, e um valor plausível costuma estar errado: um nome de cliente onde se exigia um identificador, dia e mês trocados de ordem ou um código de moeda que o sistema não aceita. Cada parâmetro precisa de definição suficiente para que o modelo o preencha a partir da origem certa ou o deixe vazio de propósito.
Confira cada parâmetro com esta lista:
- Declare o tipo e o formato, incluindo como datas e horas são escritas e qual fuso horário vale.
- Liste os valores permitidos quando o conjunto for fechado, em vez de deixá-los subentendidos.
- Diga de onde o valor vem, como o resultado de uma consulta anterior, uma mensagem do usuário ou um campo que o agente nunca deve adivinhar.
- Nomeie os identificadores com precisão, por exemplo o identificador de cliente devolvido pela ferramenta de busca de clientes, e não apenas cliente.
- Marque os parâmetros opcionais e diga o que o sistema faz quando eles são omitidos.
- Mantenha os nomes dos parâmetros literais. Um campo chamado valor_em_centavos diz mais ao modelo do que um campo chamado valor.
A mesma disciplina vale para as saídas. Se uma ferramenta devolve um campo, descreva-o, porque o modelo vai raciocinar sobre esse campo no passo seguinte. Para mais sobre campos tipados, veja Esquema de ferramentas para agentes de IA: campos tipados e erros claros.
Escreva mensagens de erro em que o agente consiga agir
A mensagem de erro faz parte da interface. Uma mensagem como entrada inválida diz ao modelo que algo falhou e mais nada, então ele costuma repetir a mesma chamada com pequenas variações. Um erro útil diz ao modelo o que mudar, se ele deve pedir algo ao usuário e se a tentativa falha deixou algum rastro no sistema.
Cada erro deveria responder a cinco perguntas:
- Qual campo falhou e qual regra ele quebrou.
- Como é um valor válido, com um exemplo ou com a lista completa de valores permitidos.
- Se o pedido alterou algo, para que o agente saiba se uma nova tentativa poderia duplicar um registro.
- Se o próximo passo é uma consulta, uma pergunta ao usuário ou uma parada.
- Se o formato da resposta é o mesmo do sucesso, para que o agente consiga interpretá-la sem tratamentos especiais.
Cenário ilustrativo: uma ferramenta de agendamento espera uma data escrita como ano, mês e dia. O agente envia dia e mês separados por barra, e o erro informa que a data é ambígua, que o formato esperado é um ano com quatro dígitos seguido de mês e dia com dois dígitos cada, e que nenhum agendamento foi criado. A chamada seguinte usa o formato correto, e nenhuma pessoa chega a ver o erro.
Os erros também merecem atenção do ponto de vista de segurança. Resultados de ferramentas e textos de erro são entrada para o modelo, então um erro nunca deve repetir texto bruto do usuário de um jeito que possa direcionar a próxima ação. A orientação da OWASP sobre prevenção de injeção de prompt cobre essa classe de risco, e ela se aplica a qualquer texto que um agente lê de uma ferramenta.
Teste o schema antes e depois de cada mudança
Editar um schema é mudar comportamento, e essas mudanças são fáceis de fazer sem perceber o efeito. Um conjunto de testes curto e fixo pega a maior parte das regressões antes que elas cheguem a um fluxo de trabalho real. O guia de avaliações da OpenAI descreve a prática geral de definir o comportamento esperado e avaliar as saídas contra ele, e a mesma abordagem funciona para a escolha de ferramentas.
Um processo sólido fica assim:
- Reúna pedidos realistas de operações recentes, com dados pessoais e financeiros removidos.
- Inclua pedidos comuns, pedidos ambíguos e pedidos que não devem executar, como uma gravação que precisa de aprovação.
- Para cada pedido, registre a ferramenta esperada, os argumentos esperados e qualquer recusa ou encaminhamento esperado.
- Rode o conjunto completo após cada edição do schema e compare os resultados com a versão anterior.
- Para cada escolha errada, corrija o nome, a descrição ou o erro que a causou. Mudar só o prompt costuma esconder o problema, e não resolvê-lo.
- Acompanhe as falhas por ferramenta, para que um aumento na taxa de erro aponte para uma definição que precisa de atenção.
Mantenha o conjunto de testes sob controle de versão, ao lado do schema, para que uma mudança em qualquer um dos dois seja revisada junto com o outro.
Como uma operação gerenciada mantém os schemas precisos
A Be Human trata o schema de ferramentas como parte do contexto operacional de cada agente. Em uma primeira implantação, a equipe define um papel útil, lista as ferramentas que esse papel precisa e escreve nomes, descrições, regras de parâmetros e formatos de erro para cada uma. Cada ferramenta é marcada como somente leitura, rascunho ou escrita com aprovação, de modo que a fronteira fique visível no próprio schema. Na operação gerenciada, a mesma equipe revisa o schema quando um sistema conectado muda, roda o conjunto de testes após cada edição e analisa registros que mostram para qual ferramenta cada pedido foi encaminhado. O trabalho é contínuo, porque mudanças dos fornecedores e novos pedidos alteram o desempenho de um schema ao longo do tempo, e um schema que estava correto na primeira semana não tem garantia de continuar correto.
Se ainda não está claro qual tarefa deve ir primeiro para um agente, o diagnóstico gratuito de IA da Be Human pode ajudar a encontrar a primeira tarefa que vale a pena delegar.
Perguntas frequentes
Quantas ferramentas um agente deve receber? Dê a um agente apenas as ferramentas que o papel único dele precisa, e acrescente mais só depois que as atuais tiverem bom desempenho no conjunto de testes. Uma lista grande de ferramentas sobrepostas dá ao modelo mais formas de escolher errado, e cada acréscimo exige sua própria descrição, suas permissões e seu tratamento de erros.
As descrições de ferramentas devem ser longas? As descrições devem ser completas, mas diretas. Cubra a ação, as situações de uso, as situações a evitar, a ferramenta vizinha a usar no lugar e se a chamada altera algo. Se uma frase não ajuda o modelo a decidir, remova-a.
Um schema melhor pode substituir um modelo mais capaz? Um schema claro costuma reduzir mais erros do que a troca de modelo, porque elimina o chute. Ele não corrige uma tarefa que não é adequada para automação, e não substitui os limites de permissão nem as etapas de aprovação para gravações que importam.
O que fazer quando o agente ainda escolhe a ferramenta errada? Leia o pedido registrado e a ferramenta escolhida, depois encontre o nome, a descrição ou o parâmetro que tornou a escolha errada plausível. Corrija essa definição, adicione o pedido ao conjunto de testes e rode o conjunto completo antes de liberar a mudança.
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.


