Como Criar Esquemas de Ferramentas para Agentes de IA Selecionarem o Endpoint Ideal

Você deu ao agente duas ferramentas: updateUser e deactivateUser. Um ticket de suporte diz “fechar esta conta.” O agente chamou deactivateUser. Na semana passada, um ticket quase idêntico fez com que ele chamasse updateUser com status: "closed", o que sua API aceitou e que significava algo ligeiramente diferente downstream.

Nada estava quebrado. O modelo estava escolhendo entre duas opções plausíveis com descrições que não diziam qual delas se aplicava. A seleção de ferramentas é o modo de falha que as pessoas culpam o modelo e corrigem no esquema, porque o esquema é a única coisa que o modelo tem para se basear.

Este guia aborda o que o modelo realmente lê ao escolher uma ferramenta, como escrever nomes e descrições que discriminam, como o design de parâmetros altera a taxa de erro e como testar a seleção para que uma mudança na redação não a quebre silenciosamente. Uma vez que suas ferramentas são geradas a partir de uma especificação, como em nosso guia sobre transformar uma especificação OpenAPI em ferramentas de agente, isso se torna uma questão do que entra nessa especificação.

Apidog é onde as descrições vivem se suas ferramentas vêm da sua definição de API, então melhorar uma melhora a documentação e as ferramentas juntas.

O que o modelo vê

No momento da escolha, o modelo possui a conversa, o prompt do sistema e uma lista de definições de ferramentas. Cada definição é um nome, uma descrição e um esquema de parâmetros. Ele não possui sua documentação de API, seus comentários de código ou o conhecimento tribal de que updateUser é legado.

Isso significa que cada desambiguação deve ser escrita na própria definição. Tanto o guia de chamada de função da OpenAI quanto a documentação de uso de ferramentas da Anthropic fazem o mesmo ponto: a descrição é o texto que mais importa em toda a definição, e deve ser verbosa em vez de concisa.

Erros de seleção vêm em quatro formas, e cada um tem uma correção diferente.

O modelo escolhe uma ferramenta semelhante quando duas definições se sobrepõem. Corrija as descrições para que cada uma diga quando não a usar. O modelo não escolhe nada e responde da memória quando nenhuma descrição corresponde à linguagem da tarefa. Corrija usando as palavras que seus usuários usam. O modelo escolhe a ferramenta certa com argumentos errados quando os parâmetros são ambíguos. Corrija com tipos, enums e unidades. O modelo encadeia ferramentas mal quando a ordem importa e nada diz isso. Corrija indicando o pré-requisito na descrição.

Nomeie as ferramentas pelo que elas fazem

Nomes carregam mais sinal do que o seu comprimento sugere, porque o modelo os lê primeiro.

Use verboSubstantivo, no mesmo estilo em todo o conjunto de ferramentas: criarPedido, reembolsarPedido, obterStatusPedido. A consistência importa tanto quanto a escolha individual, já que um conjunto que mistura order_create, getOrder e refund torna cada nome ligeiramente mais difícil de ler.

Seja específico sobre o objeto. search é um nome de ferramenta ruim. searchCustomersByEmail é bom, e diz ao modelo tanto o que ele pesquisa quanto como.

Evite jargões internos. Se sua API chama um cliente de "entidade" e uma assinatura de "instrumento", o modelo não conectará isso a um ticket que diz "cliente" e "plano". Nomeie as ferramentas na linguagem da tarefa, não na linguagem do esquema.

Nunca reutilize um nome em diferentes contextos. Duas ferramentas chamadas list em diferentes namespaces colapsam em ambiguidade assim que aparecem em uma lista.

Escreva descrições que discriminam

Uma descrição útil responde a quatro perguntas: o que faz, o que muda, quando usar e quando não usar.

Aqui está um par fraco:

{ "name": "updateUser", "description": "Updates a user." }
{ "name": "deactivateUser", "description": "Deactivates a user." }

E um par que realmente separa:

{
  "name": "updateUser",
  "description": "Atualiza campos de perfil de um usuário ativo, como nome, e-mail ou fuso horário. Use para correções e edições de perfil solicitadas pelo usuário. NÃO altera o status da conta. Para desativar uma conta, use deactivateUser em vez disso. Não use para fechar ou cancelar uma conta."
}
{
  "name": "deactivateUser",
  "description": "Desativa uma conta de usuário, revogando todas as sessões e bloqueando o login. Reversível com reactivateUser. Use quando um cliente solicita fechar, cancelar, pausar ou suspender sua conta. NÃO exclui dados. Para exclusão permanente, use deleteUser, que não pode ser desfeito."
}

Quatro técnicas estão funcionando ali.

Nomeie o irmão. “Use deactivateUser em vez disso” resolve a ambiguidade diretamente, no exato momento em que o modelo os compara.

Inclua o vocabulário do usuário. As palavras “fechar”, “cancelar”, “pausar” e “suspender” aparecem porque são as palavras que surgem nos tickets. Esta é a única edição de maior retorno que você pode fazer, e é quase gratuita.

Diga o que não faz. Declarações negativas são mais discriminatórias do que as positivas, porque as afirmações positivas de duas ferramentas vizinhas tendem a se parecer.

Sinalize a reversibilidade. O modelo raciocina sobre o risco quando você lhe diz que há risco. Isso se alinha com os padrões de aplicação em nossa postagem sobre guardrails de agentes de IA, que é onde a proteção real reside.

O comprimento está bom. Uma descrição de cem palavras que previne uma chamada errada a um endpoint destrutivo é barata.

Projete parâmetros para que argumentos errados sejam difíceis

Uma vez que a ferramenta certa é escolhida, os argumentos são o próximo ponto onde as coisas dão errado.

JSON Schema oferece a maioria das restrições de que você precisa aqui, e o vocabulário de validação do JSON Schema vale a pena ser consultado para os termos-chave que sua API de chamada de ferramenta suporta.

Use enums sempre que o conjunto for fechado. Um parâmetro status tipado como string convida à invenção. Tipado como enum, ele restringe o modelo aos valores que sua API aceita.

"status": {
  "type": "string",
  "enum": ["pending", "paid", "refunded", "cancelled"],
  "description": "Status do pedido. 'cancelled' significa nunca atendido; 'refunded' significa atendido e depois revertido."
}

Coloque unidades no nome. amount é ambíguo e os modelos adivinharão dólares ou centavos de forma inconsistente. amount_cents nunca é. O mesmo vale para timeout_seconds, distance_meters e duration_ms.

Dê um exemplo de formatos de data. "description": "Data de início no formato ISO 8601, por exemplo 2026-08-26" produz datas formatadas corretamente com muito mais frequência do que apenas “data de início”.

Mantenha as listas obrigatórias honestas. Marcar tudo como opcional empurra as falhas para o tempo de execução; marcar coisas como obrigatórias que a API define sensatamente faz o modelo inventar valores. Ambos são comuns, e ambos aparecem como erros de validação abordados em nossa postagem sobre design de erros de API para agentes.

Prefira o formato plano ao aninhado. Um modelo preenchendo {"customer": {"address": {"postal_code": "..."}}} comete erros estruturais que não cometeria em customer_postal_code. Achate na fronteira da ferramenta e remonte em seu executor.

Divida ferramentas sobrecarregadas. Uma ferramenta com um parâmetro mode que muda o significado de todos os outros campos é, na verdade, duas ferramentas. Dividi-la melhora a seleção e simplifica ambos os esquemas.

Declare pré-requisitos e ordem

O trabalho multi-etapas falha quando o modelo não conhece a sequência. Diga isso na descrição da ferramenta dependente:

{
  "name": "captureCharge",
  "description": "Captura uma cobrança previamente autorizada. Requer um authorization_id de authorizeCharge. Chame authorizeCharge primeiro se você ainda não tiver um. Não pode capturar mais do que o valor autorizado."
}

Duas linhas, e o problema de ordenação é resolvido onde o modelo já está lendo. Isso vale para toda a classe: criar antes de atualizar, carregar antes de processar, autorizar antes de capturar. Se a descrição de uma etapa dependente não nomear a etapa anterior, espere que o modelo a pule. Onde a sequência abrange múltiplos agentes em vez de múltiplas chamadas, as regras de entrega em nossa postagem sobre passagem de contexto entre sub-agentes se aplicam.

Teste a seleção como qualquer outro comportamento

Descrições são código, e elas regridem. Alguém encurta uma para se adequar a um guia de estilo e o agente começa a escolher o endpoint errado na próxima terça-feira.

Construa um pequeno conjunto de testes de seleção. De vinte a cinquenta prompts, cada um com a ferramenta que você espera. Execute-os, registre qual ferramenta o modelo escolhe e valide apenas o nome. Argumentos variam de execução para execução; a escolha não deve variar. Esta é a forma prática da abordagem em nosso guia para testar agentes de IA não determinísticos.

Alimente-o com os casos mais prováveis de falhar:

• As duas ferramentas mais semelhantes em seu conjunto, com prompts que deveriam direcionar para cada uma.
• Prompts usando o vocabulário do cliente em vez do vocabulário da API.
• Um prompt que não deveria corresponder a nada, onde o comportamento correto é perguntar em vez de forçar uma chamada.
• Uma ferramenta destrutiva, onde uma escolha errada tem um custo real.

Execute cada prompt várias vezes. Uma ferramenta que vence quatro em cada cinco é um "cara ou coroa" em produção e a descrição precisa de trabalho.

Direcione as execuções para mocks para que um teste de seleção nunca toque em dados reais. Nossa postagem sobre executar agentes contra mocks em vez de produção aborda a configuração, e Apidog pode servir esses mocks a partir da mesma definição de onde suas ferramentas foram geradas, o que mantém o esquema e o comportamento alinhados.

Três conjuntos que dão errado da mesma forma

O conjunto CRUD. Uma API expõe getUser, listUsers, searchUsers e queryUsers, todos gerados a partir de endpoints que cresceram ao longo dos anos. Para um modelo, esses são quatro nomes para uma mesma ideia. A correção não é ter descrições melhores para todos os quatro; é expor apenas um deles ao agente e deixar o restante fora da lista de ferramentas. Um conjunto curado sempre supera um conjunto completo.

O conjunto de administração. Ferramentas de leitura e ferramentas destrutivas ficam lado a lado com o mesmo tom: getInvoice, voidInvoice, deleteInvoice. Nada no texto sinaliza que duas delas "acabam com carreiras". Adicione a consequência à descrição, marque-as para aprovação e mantenha a execução no executor, em vez de confiar na redação. A abordagem em camadas está em nossa postagem sobre impedir que agentes destruam sua API.

O conjunto legado. Dois endpoints fazem o mesmo trabalho, um depreciado. A especificação ainda lista ambos, então o gerador emite ambos, e o agente escolhe o antigo cerca de metade do tempo. Ou remova a operação depreciada das ferramentas geradas, ou comece sua descrição com as palavras “Depreciado. Use createOrderV2 em vez disso.” Os modelos honram essa linha quando ela está no início e a ignoram quando está enterrada no final.

Descrições são configurações compartilhadas

Uma vez que você aceita que as descrições das ferramentas impulsionam o comportamento, a próxima pergunta é quem as possui. Na maioria das equipes, a resposta é acidental: quem configurou o agente primeiro, em um arquivo em sua máquina.

Trate o conjunto de ferramentas como um artefato compartilhado, revisado como qualquer outra interface. Plataformas construídas em torno do trabalho de agentes muitas vezes modelam isso diretamente. Um Agente Sharkly é uma configuração salva que abrange instruções, Runtime, Habilidades e repositórios, e compartilhá-lo em um Espaço torna a configuração de trabalho de uma pessoa reutilizável pela equipe. O valor não é o armazenamento. É que uma mudança na descrição se torna uma edição revisável que afeta a todos, em vez de um ajuste local silencioso que faz o agente de um desenvolvedor se comportar de forma diferente dos demais.

Observe as palavras que os usuários trazem

A lacuna mais comum é o vocabulário. Sua API diz subscription, seus clientes dizem plan, membership e billing. Sua API diz deactivate, eles dizem cancel, close e turn off.

Colete a linguagem real. Extraia as principais frases de tickets de suporte, logs de pesquisa ou transcrições de execuções de agentes falhas, e então incorpore-as nas descrições das ferramentas que deveriam ter correspondido. Isso custa uma hora e geralmente melhora a precisão da seleção mais do que qualquer ajuste de esquema.

Fique de olho nas falhas também. Quando um agente não escolhe nada e responde com seu próprio conhecimento, isso é uma falha de vocabulário, não uma falha de raciocínio. A linguagem da tarefa nunca se sobrepôs ao texto da ferramenta, então a ferramenta estava invisível.

Uma lista de verificação para um conjunto de ferramentas

• Nomes seguem uma convenção verboSubstantivo e nomeiam um objeto específico.
• Cada descrição diz o que muda, quando usar e quando não usar.
• Ferramentas sobrepostas nomeiam-se explicitamente.
• As descrições incluem as palavras que os usuários realmente usam, não apenas termos internos.
• Ações destrutivas e irreversíveis são indicadas na descrição.
• Enums são declarados para cada conjunto fechado.
• Unidades e formatos residem em nomes de parâmetros ou descrições, com exemplos.
• Listas de requisitos correspondem ao que a API realmente impõe.
• Ferramentas dependentes nomeiam seu pré-requisito.
• Um conjunto de testes de seleção é executado em CI contra mocks.

O modelo está fazendo correspondência de padrões com o texto que você escreveu. Quando ele escolhe errado, o texto é o primeiro lugar a procurar, e geralmente o único lugar que você precisa mudar. Baixe o Apidog se você quiser as descrições, os mocks e os testes em um único projeto.

Perguntas frequentes

Qual deve ser o comprimento de uma descrição de ferramenta? Longo o suficiente para desambiguar, o que geralmente são de duas a cinco frases. As descrições ocupam contexto, então encurte as de ferramentas inequívocas e use o espaço para ferramentas que são vizinhas.

Devo incluir exemplos na descrição? Sim, para formatos e unidades, onde um exemplo elimina uma classe inteira de erros. Evite exemplos de uso longos, pois eles custam contexto e raramente alteram a seleção.

É melhor ter muitas ferramentas específicas ou algumas flexíveis? Ferramentas específicas, até certo ponto. Cada uma seleciona de forma mais confiável porque faz uma única coisa. Após algumas dezenas, a própria lista se torna o problema e você filtra ou recupera, conforme abordado em nossa postagem sobre gerar ferramentas de agente a partir de OpenAPI.

Posso corrigir a seleção no prompt do sistema? Parcialmente, e é uma solução provisória razoável para uma ou duas confusões conhecidas. Não escala, porque o prompt é compartilhado entre todas as ferramentas, enquanto a descrição viaja com a ferramenta que precisa dela.

E se o modelo continuar inventando valores de parâmetros? Restrinja o tipo, adicione um enum e diga na descrição que o valor deve vir de uma chamada anterior, em vez de ser construído. Se ainda assim acontecer, valide no wrapper e retorne um erro nomeando os valores permitidos.

Essas regras também se aplicam a servidores MCP? Sim. Um servidor MCP expõe nomes, descrições e esquemas na mesma forma, então as mesmas regras de redação se aplicam. Nosso explicador sobre o que é MCP aborda o próprio protocolo.