Para identificar descrições contraditórias no inventário de ferramentas de um agente, compare o texto apresentado ao modelo, o esquema de parâmetros e o comportamento observado em testes controlados. Registre a divergência por ferramenta e versão. Uma descrição que promete consultar dados enquanto a implementação também os altera exige correção antes de voltar ao catálogo operacional.
O objetivo desse inventário é tornar o contrato de cada ferramenta verificável. A equipe precisa conseguir responder o que a função aceita, o que devolve, quais efeitos produz e quando deve ser escolhida. A revisão proposta abaixo concentra-se nessa consistência semântica. Ela complementa a política de acesso, mas tem uma entrega própria: um catálogo em que nome, documentação, parâmetros e execução contam a mesma história.
Resumo rápido
- Capture o catálogo efetivamente entregue ao agente, incluindo descrições e esquemas.
- Identifique ferramentas pelo servidor de origem e pelo nome, preservando versões.
- Compare promessas de leitura, escrita, filtros, retornos e repetição da chamada.
- Use exemplos sintéticos para confrontar documentação e comportamento sem afetar clientes.
- Bloqueie a promoção de descrições contraditórias até haver correção e evidência.
O que torna uma descrição contraditória
Uma contradição aparece quando duas afirmações sobre a mesma ferramenta não podem ser verdadeiras no mesmo contexto. A descrição diz que o campo de empresa é obrigatório, mas o esquema o aceita ausente. O texto promete somente registros ativos, enquanto a função retorna também os arquivados. O nome sugere uma prévia, mas a chamada confirma a operação. São conflitos que mudam a escolha ou a interpretação do agente.
Nem toda documentação curta contém contradição. “Consulta pedidos” pode ser apenas vaga. Para classificar o problema, registre uma afirmação concreta e a evidência que a desmente. “Não informa se inclui cancelados” é lacuna; “afirma excluir cancelados, mas devolve um cancelado” é divergência comprovada. Essa separação evita que a revisão vire uma lista interminável de preferências de redação.
Também existe diferença legítima entre ambientes. Uma função pode consultar produção e escrever apenas no ambiente de teste. Nesse caso, a descrição precisa explicitar a condição. Não marque o catálogo inteiro como errado antes de conferir configuração, identidade usada, versão do serviço e dados de entrada. O inventário deve explicar a condição de execução junto da evidência.
Adote um vocabulário fixo: lacuna, ambiguidade, contradição e diferença de ambiente. Cada categoria pede uma correção distinta. Uma lacuna pede informação; uma contradição pode pedir alteração do código, da descrição ou de ambos. A decisão deve partir do comportamento pretendido pelo responsável pelo processo.
Capture o contrato que realmente chega ao agente
Comece pelo catálogo exposto na sessão de teste. Salve nome, origem, descrição, esquema de entrada, esquema de saída quando existir e metadados comportamentais. Acrescente a identificação da versão do conector e a data da captura. O documento no repositório pode estar correto enquanto a aplicação ainda distribui uma descrição antiga.
A especificação de ferramentas do MCP descreve campos como nome, descrição e esquema de entrada, além da descoberta por catálogo. Para inventariar uma integração, use esses campos como matéria-prima, sem supor que o protocolo garante a correção do texto. Uma ferramenta válida estruturalmente ainda pode estar mal descrita.
Use uma chave composta, como estoque_principal.consultar_item. Esse é um identificador interno sugerido para o inventário. Dois serviços podem usar o nome consultar_item e ter contratos distintos. Preserve também o nome original, para relacionar o registro ao log de execução sem depender de uma tradução inventada pelo revisor.
Evite copiar credenciais e exemplos de clientes para o catálogo. O registro precisa da estrutura, de exemplos sintéticos e da localização da evidência. Para organizar o histórico das alterações, aproveite o método de governança de prompts com versionamento, mantendo descrições de ferramentas sob revisão equivalente à das instruções do agente.
Monte uma matriz de afirmações e evidências
Divida descrições longas em afirmações testáveis. “Busca pedidos por cliente, sem alterar o cadastro, e retorna apenas pedidos abertos” contém três promessas independentes. Registre uma linha por promessa. Assim, a correção do filtro não encerra indevidamente uma pendência sobre alterações no cadastro.
| Afirmação do catálogo | Evidência a procurar | Possível divergência | Encaminhamento |
|---|---|---|---|
| Somente consulta | Estado antes e depois | Atualiza uma preferência | Separar efeitos ou corrigir contrato |
| Cliente obrigatório | Esquema e chamada sem cliente | Consulta todos os clientes | Definir e aplicar obrigatoriedade |
| Retorna todos os pedidos | Resultado e informação de continuação | Entrega uma página parcial | Explicitar cobertura do retorno |
| Repetição sem efeito adicional | Duas chamadas no mesmo cenário | Cria registros duplicados | Rever promessa de repetição |
| Data em formato brasileiro | Entradas de datas e erros | Aceita apenas formato internacional | Alinhar formato e exemplos |
A referência de objetos em JSON Schema distingue propriedades declaradas, campos obrigatórios e propriedades adicionais. Ao revisar parâmetros, confira cada dimensão separadamente. Declarar uma propriedade não significa torná-la obrigatória. Essa diferença explica por que uma frase aparentemente clara pode conflitar com o validador.
Inclua ainda uma coluna de impacto no processo: escolha errada da ferramenta, interpretação errada do retorno ou efeito inesperado. A prioridade pode seguir esse impacto e a frequência real de uso registrada pela equipe. Não transforme uma estimativa de gravidade em estatística de incidentes; são informações diferentes.
Revise descrições, anotações e exemplos juntos
Leia o texto principal ao lado das descrições de cada parâmetro. Uma ferramenta pode prometer busca exata e descrever o argumento como texto livre para busca aproximada. Esclareça o significado de termos como “ativo”, “recente”, “completo” e “confirmado”. Se dependem de regras do negócio, documente essas regras ou referencie sua definição estável.
A documentação de anotações em JSON Schema explica que palavras como description e default têm função informativa; o valor padrão declarado não preenche automaticamente uma entrada ausente durante a validação. Portanto, compare o padrão anunciado com o que o aplicativo realmente aplica.
Metadados de comportamento também precisam entrar na revisão. O texto oficial do MCP sobre anotações de ferramentas apresenta essas informações como indicações, sem garantia automática de fidelidade. Se o texto anuncia consulta e uma anotação sugere escrita, há uma pendência documental a investigar, mesmo antes de executar a ferramenta.
Use uma descrição revisada com quatro frases objetivas: finalidade, critérios de seleção, resultado e efeitos. Por exemplo: “Consulta pedidos de uma empresa identificada pelo código. Exige o código do cliente. Devolve uma página de pedidos e um marcador de continuação quando houver mais resultados. Não altera pedidos nem cadastra clientes.” Essa redação é uma proposta de contrato para a ferramenta fictícia, sujeita a teste.
Atualize também os exemplos. Um exemplo com parâmetro removido pode ensinar uma chamada inválida mesmo quando o parágrafo principal está correto. Mantenha exemplos pequenos, verificáveis e coerentes com a mesma versão do esquema. Registre explicitamente exemplos que devem falhar.
Teste divergências antes de promover o catálogo
Prepare uma base sintética com registros que diferenciem as interpretações possíveis: pedido aberto, pedido cancelado e cliente sem pedido. Execute diretamente a função com entradas controladas e guarde a resposta estruturada. Essa etapa identifica o contrato real sem depender de o modelo escolher a ferramenta durante uma conversa.
Depois avalie a seleção pelo agente. Dê pedidos curtos que distingam ferramentas parecidas, como “consultar o orçamento existente” e “criar uma nova proposta”. Registre qual ferramenta foi escolhida, os argumentos e a resposta final. Se a execução direta está correta, mas a seleção continua errada, a descrição ou a sobreposição entre funções merece outra revisão.
Combine esse conjunto com testes de regressão de prompts e ferramentas. Guarde casos que já revelaram falhas e repita-os quando mudar o catálogo. A finalidade é verificar se a correção permanece válida, sem prometer que um conjunto finito de testes cobre qualquer conversa futura.
Defina um critério de saída para cada pendência: texto atualizado, esquema coerente, teste direto aprovado e cenário de seleção revisado. O responsável pelo serviço confirma o comportamento; o responsável pelo agente confirma a distribuição da descrição. Não encerre a tarefa apenas porque o arquivo de documentação foi alterado.
Exemplo: distribuidora de peças em Campinas
Considere uma distribuidora fictícia de peças em Campinas, no interior de São Paulo. O assistente comercial dispõe de duas ferramentas: consultar_orcamento e preparar_orcamento. A primeira descreve “consulta sem modificações”, mas registra automaticamente uma reserva de estoque. A segunda diz “prepara uma prévia”, porém salva uma proposta que aparece na fila do vendedor.
No inventário, a equipe separa as duas contradições. Para a consulta, decide remover a reserva automática e oferecer uma função específica quando o processo exigir reserva. Para a preparação, mantém o salvamento e muda a descrição para informar que cria um rascunho persistente. São decisões ilustrativas de desenho, sem alegação de resultado financeiro.
Os testes usam um cliente fictício e uma peça de demonstração. Após consultar, o estoque e as reservas devem permanecer iguais. Após preparar, deve existir um rascunho identificável. A equipe verifica a base diretamente e compara o resultado com a resposta entregue ao agente. Se a descrição promete um identificador, o retorno precisa fornecê-lo.
Por fim, o catálogo atualizado é capturado novamente na sessão. O aceite inclui essa captura, os testes e o nome de quem confirmou o contrato. O gerente consegue entender o que mudou sem interpretar logs técnicos extensos: consultar continua uma consulta; preparar cria um rascunho documentado.
Erros comuns
Corrigir somente o nome: chamar uma função de “consulta segura” não resolve um efeito colateral existente. Mude a implementação ou descreva o efeito com precisão. Depois confirme que a redação nova aparece no catálogo usado pela aplicação.
Tratar esquema válido como contrato correto: validar tipos ajuda a identificar entradas inadequadas, mas não demonstra que os filtros de negócio estão certos. Uma resposta pode respeitar o esquema e trazer o conjunto errado de registros.
Deixar pendências sem responsável: registre quem mantém a função e quem distribui a descrição. Sem essa separação, duas equipes podem supor que a outra corrigiu o problema, enquanto o agente continua recebendo o contrato antigo.
Usar revisão por IA como prova final: um modelo pode sugerir conflitos de linguagem e agrupar descrições semelhantes. Confirme cada achado contra esquema, implementação ou teste. Uma sugestão plausível ainda não é uma divergência demonstrada.
Perguntas frequentes
Preciso inventariar ferramentas que quase nunca são usadas?
Inclua todas as que estão expostas ao agente. Priorize a investigação conforme impacto e uso, mas preserve a lista completa. Uma função pouco usada ainda pode ser selecionada quando sua descrição parece combinar com um pedido incomum.
Posso resolver uma contradição apenas no prompt do sistema?
Uma instrução provisória pode reduzir exposição durante a correção, mas deixa duas fontes conflitantes. O aceite deve exigir alinhamento do catálogo e da execução. Registre a medida temporária e uma condição explícita para removê-la.
Descrições diferentes significam ferramentas duplicadas?
Não necessariamente. Compare entradas, saídas, filtros e efeitos. Duas funções podem atender processos distintos com nomes parecidos. Se a distinção for legítima, descreva quando escolher cada uma e teste pedidos que revelem essa diferença.
Quando devo repetir a revisão?
Associe a revisão a alterações de conector, esquema, implementação e configuração que mudem o contrato. Também reabra a análise quando um incidente mostrar que a resposta observada diverge da promessa registrada, mesmo sem mudança anunciada.
