Um agente recebe duas tools com nomes parecidos e escolhe a errada. Outra chamada usa um identificador que não existe porque o parâmetro dizia apenas "ID". A aplicação rejeita o pedido, mas o modelo não sabe se deve corrigir o argumento, escolher outra ferramenta ou responder sem chamar nada.
Para escrever uma boa descrição de tool, explique quatro decisões: o que a ferramenta faz, quando o agente deve escolhê-la, quais dados os parâmetros representam e que resultado ele receberá. O schema limita a forma da chamada. A descrição orienta a escolha. Um não substitui o outro.
Esse trabalho acontece antes do runtime. O servidor MCP em TypeScript para agentes de código mostra como expor uma superfície estreita. Aqui, o foco é escrever a interface que o modelo lê antes de enviar o primeiro argumento.
Resumo prático
- Nomeie a intenção que o agente precisa cumprir, não a classe ou o endpoint interno.
- Diga quando usar a tool e quando escolher outra opção.
- Descreva parâmetros ambíguos com unidade, formato, origem e exemplos curtos.
- Mantenha ferramentas parecidas separadas por escopo e teste a seleção com casos reais.
O que uma descrição de tool precisa responder?
Uma descrição útil responde à pergunta "esta é a ferramenta certa para este pedido?". O guia de function calling do Google Cloud separa a declaração da função, os parâmetros e a execução que devolve o resultado ao modelo. Esses campos não são decoração: formam a superfície que o agente usa para propor uma chamada.
Comece pela intenção, não pela implementação. O agente não precisa saber que a função chama um endpoint REST ou que o handler consulta uma tabela. Ele precisa saber que a tool busca pedidos existentes por número ou cliente, por exemplo. A camada de execução pode mudar sem obrigar o modelo a reaprender uma decisão de negócio.
Uma descrição deve deixar quatro coisas legíveis:
- Ação: qual pergunta ou tarefa a tool resolve.
- Momento: que sinais indicam que ela deve ser chamada.
- Limite: quais pedidos pertencem a outra tool ou exigem confirmação.
- Resultado: que tipo de evidência volta e o que ainda não foi confirmado.
Isso não significa transformar a descrição em um manual. Detalhes de autenticação, retries internos e nomes de tabelas pertencem ao código e aos logs. O texto entregue ao modelo deve conter a informação necessária para decidir, não todo o histórico da implementação.
Cápsula citável: A descrição de uma tool é uma parte da interface do agente. Ela deve explicar a ação, o momento de uso, os limites e o resultado esperado. O schema valida a forma dos argumentos, mas não ensina sozinho quando uma ferramenta é mais adequada que outra.
Como escolher nomes que diferenciam as tools?
O nome deve representar a operação que o agente reconhece, com um vocabulário estável e específico. buscar_dados não distingue clientes, pedidos ou faturas. consultar_pedido_por_numero já reduz a ambiguidade porque informa o objeto e o critério principal.
Evite nomes baseados em detalhes que só existem no código, como executeQueryV2, customerLookupService ou runWorkflow. Eles podem fazer sentido para quem abriu o repositório, mas não respondem à tarefa que aparece na conversa.
Este é um exemplo ilustrativo de duas tools de leitura. O código não depende de um provedor específico:
const tools = [
{
name: "consultar_pedido_por_numero",
description:
"Busca um pedido existente pelo número exato e devolve status, itens e datas observadas.",
},
{
name: "buscar_pedidos_do_cliente",
description:
"Lista pedidos associados a um cliente quando o usuário não tem um número de pedido.",
},
];As duas tools ainda precisam de schemas de entrada e saída. A diferença é que cada descrição responde a uma intenção distinta. Se uma delas atende tanto busca por número como busca por nome, o agente precisa adivinhar qual regra vale e a ferramenta vira uma caixa maior do que deveria.
Quando a ferramenta muta dados, o nome também deve deixar a ação visível. preparar_reembolso e confirmar_reembolso não têm o mesmo risco nem a mesma condição de uso. A descrição deve reforçar essa diferença, mas a autorização continua sendo uma decisão do runtime, não uma promessa escrita no texto.
Como descrever parâmetros sem esconder a ambiguidade?
Um parâmetro não está explicado só porque tem um nome. id, date, status e amount podem representar várias coisas. O guia do Google Cloud recomenda nomes claros e descrições detalhadas para funções e parâmetros. A aplicação precisa transformar essa recomendação em perguntas concretas sobre cada campo.
Para cada parâmetro, informe o que ele identifica, qual formato aceita, de onde o usuário pode obtê-lo e que unidade ou fuso horário se aplica. Se o valor deve vir de uma resposta anterior, diga isso. Se o agente não deve inventá-lo, escreva a regra.
const consultarPedido = {
name: "consultar_pedido_por_numero",
description:
"Busca um pedido existente pelo número exato. Use quando o usuário informar o número; não use para descobrir pedidos de um cliente.",
parameters: {
type: "object",
properties: {
numero: {
type: "string",
description:
"Número visível no comprovante do pedido, como PED-1042. Não use o telefone ou o ID interno do cliente.",
},
},
required: ["numero"],
},
};O exemplo também mostra o que não deve acontecer: trocar um identificador por outro só porque ambos são strings. O schema pode exigir string, mas não consegue explicar sozinho a diferença entre PED-1042, um telefone e um UUID interno.
Inclua exemplos apenas quando eles eliminam uma dúvida real. Um exemplo de formato ajuda com datas, códigos compostos e unidades. Muitos exemplos decorativos aumentam o texto disponível sem melhorar a decisão. Se a regra for longa o bastante para virar um parágrafo de exceções, talvez a tool esteja abrangendo duas operações.
Cápsula citável: Parâmetros bem descritos carregam semântica que um tipo JSON não expressa. Diga o que o campo identifica, qual formato aceita, qual unidade usa e de onde o valor deve vir. Um schema pode rejeitar um tipo inválido, mas não distingue sozinho um número de pedido de outro identificador textual.
Como dizer quando o agente não deve chamar a tool?
Uma boa descrição contém limites positivos e negativos. Dizer apenas "busca pedidos" não explica se a tool deve ser usada para criar um pedido, localizar um cliente ou consultar uma entrega. O agente precisa reconhecer a fronteira com as ferramentas vizinhas.
Escreva a regra em linguagem operacional:
- Use esta tool quando o pedido trouxer um número de pedido completo.
- Use a busca por cliente quando o usuário não souber esse número.
- Não use esta tool para alterar, cancelar ou reembolsar um pedido.
- Não preencha o número por inferência; peça o dado que falta.
Essas frases não concedem permissão. Elas reduzem a chance de o modelo tratar uma tool de leitura como uma ação ou escolher uma operação de mutação porque o nome parece parecido. A validação de autorização e argumentos continua no código, como explica o artigo sobre validar tool calls em TypeScript.
Também vale separar tools por escopo. A documentação de estratégia de tools MCP da AWS alerta que poucas ferramentas podem deixar o modelo sem contexto, enquanto muitas podem confundir a escolha e a sequência. A mesma orientação recomenda pensar na granularidade e no escopo de cada tool.
Na documentação atual de function calling do Google Cloud, a recomendação é fornecer apenas as tools relevantes para a tarefa e usar um conjunto ativo de 10 a 20 como referência operacional. Isso não é uma lei para todo agente. É um sinal de que uma descrição perfeita não conserta um catálogo indiscriminado. Filtre a superfície antes de revisar o texto.
Como revisar uma descrição sem prometer que ela funciona?
Não trate a descrição como texto que só precisa parecer claro. Revise-a com casos que representem decisões concorrentes. O objetivo não é provar que um modelo sempre escolherá a tool certa. É descobrir se a interface deixa uma escolha importante sem resposta.
Uma matriz pequena pode conter:
| Caso | Tool que deveria aparecer | O que a descrição precisa deixar claro |
|---|---|---|
| Usuário informa PED-1042 | consulta por número | número exato e leitura somente |
| Usuário informa apenas o cliente | busca por cliente | ausência do número e critério de busca |
| Usuário pede cancelamento | nenhuma leitura | ação de mutação pertence a outra superfície |
| Usuário não informa o identificador | pergunta de esclarecimento | não inventar o valor ausente |
Para cada caso, registre a tool escolhida, os argumentos produzidos e a razão esperada. Se a saída precisar de confirmação, registre também essa condição. O teste pode usar um modelo real, um mock ou uma fixture de chamada, mas a escolha deve ser explícita antes da execução.
Depois compare versões da definição como código. Uma mudança em description, name, inputSchema ou outputSchema pode alterar a forma como o agente entende a superfície. O teste de contrato para servidores MCP em TypeScript cobre a fronteira do protocolo; a matriz acima cobre a decisão que acontece antes da chamada.
Uma descrição falha quando o revisor consegue explicar como a tool funciona, mas não consegue explicar por que o agente deveria escolhê-la em vez da vizinha. O teste de leitura é simples: remova o nome interno da função e pergunte qual tarefa concreta continua visível.
O que deve ficar fora da descrição?
Não use a descrição para esconder uma política que deveria ser verificável. Frases como "sempre seguro", "não falha" ou "pode executar qualquer operação" são promessas vagas. O runtime precisa impor limites, validar argumentos, controlar autorização e verificar efeitos externos.
Também não coloque segredos, tokens, stack traces, nomes de tabelas sensíveis ou detalhes de infraestrutura. A descrição é enviada para a camada que ajuda o modelo a escolher. Logs de execução e diagnósticos de operador têm outra finalidade e outra política de retenção.
Evite ainda repetir o schema em prosa. Se status aceita três valores, declare o enum e explique somente a diferença que afeta a decisão. Se o campo é obrigatório, marque-o no schema e use o texto para dizer por que ele é necessário ou de onde vem.
No MCP, a definição de uma tool inclui nome, descrição e schemas de entrada e saída. A especificação de tools do MCP descreve essa superfície e lembra que tools são controladas pelo modelo, embora a aplicação deva manter controles de confiança e interação humana para ações sensíveis.
Cápsula citável: Descrições de tools devem orientar escolha, não substituir controles de segurança. Não coloque segredos nem prometa que uma operação é sempre segura. Autorização, validação, limites e confirmação precisam ser aplicados pelo runtime, enquanto o texto explica a intenção e os limites que o agente deve considerar.
Checklist antes de publicar uma tool
Antes de expor uma nova ferramenta ao agente, revise:
- O nome descreve a intenção e diferencia as tools vizinhas.
- A descrição diz quando usar e quando não usar.
- Cada parâmetro informa significado, formato, unidade e origem quando isso importa.
- A tool deixa claro se lê, propõe ou altera estado.
- O schema marca campos obrigatórios, enumera valores e limita formas inválidas.
- O resultado explica o que foi observado, não apenas que a chamada terminou.
- A autorização e os limites existem no runtime.
- Há pelo menos um caso de teste para cada escolha concorrente.
- A superfície ativa contém somente as tools necessárias para a tarefa.
Uma descrição não torna o comportamento determinístico. Ela melhora o contrato que o modelo recebe e torna a decisão revisável. Se os casos continuam ambíguos depois de você escrever a regra de uso e a regra de não uso, o próximo ajuste provavelmente é dividir a tool ou reduzir o catálogo, não acrescentar mais adjetivos.
Como este artigo foi produzido
Este texto foi escrito por Samuel Fajreldines a partir de uma auditoria dos posts relacionados no repositório, da inspeção de resultados atuais e da leitura da documentação do Google Cloud, AWS e Model Context Protocol em 09/10/2026. Os exemplos TypeScript e JSON são ilustrativos. Não há benchmark próprio nem teste de seleção executado sendo apresentado como prova.
