Linter de esquemas MCP

Por que um agente chama a ferramenta errada

A descrição de uma ferramenta Model Context Protocol não é documentação para pessoas. Ela é enviada ao modelo em toda requisição e é a única coisa que o modelo usa para decidir se chama aquela ferramenta. Quando um agente escolhe delete_branch em vez de list_branches, quase nunca é um bug do agente: são duas descrições que o modelo não conseguiu diferenciar.

Cole acima a URL do seu servidor MCP e este linter lerá cada definição de ferramenta que o servidor anuncia, exatamente como um agente a recebe, e relatará o que torna a escolha pouco confiável.

O que é verificado

• Descrições ausentes ou curtas demais — uma ferramenta descrita em três palavras não dá ao modelo nada em que se basear.
• Descrições que repetem o nome — o modelo já tem o nome. «Listar issues: lista issues» não acrescenta sinal nenhum.
• Parâmetros sem documentação — as descrições de parâmetros são como o modelo sabe o que colocar em cada campo. Sem elas, ele deduz pelo nome e erra.
• Esquemas sem propriedades declaradas — uma ferramenta que não declara entradas aceitará o que o modelo inventar.
• Sem array required — aí todo parâmetro parece opcional, o modelo omite um necessário e recebe um erro de volta.
• Descrições longas o bastante para custar contexto real — enviadas a cada turno, então prolixidade é uma cobrança recorrente, não pontual.

Mais longo não é melhor

Vale dizer com clareza, porque o instinto costuma errar aqui: o linter sinaliza descrições longas demais tanto quanto curtas demais. Definições de ferramentas são reenviadas em toda requisição, então um parágrafo a mais é pago a cada turno de cada conversa, para sempre, sem melhorar a precisão da escolha. Busque uma ou duas frases específicas: o que a ferramenta faz e quando escolhê-la em vez da vizinha. Dá para ver exatamente quanto custa a sua lista atual com a calculadora de tokens MCP.

O que o relatório inclui

Uma pontuação de qualidade, cada achado com a ferramenta afetada e — onde uma reescrita mudaria de fato o comportamento de um modelo — uma descrição substituta sugerida. As verificações em si não usam modelo nenhum e rodam sempre. As reescritas sugeridas usam, e há um orçamento mensal para elas de modo que a ferramenta continue gratuita; se ele acabar, o relatório diz isso claramente e todos os achados acima continuam valendo.

Ferramentas e guias relacionados

• MCP Inspector — leia os esquemas completos em que a revisão se baseia.
• Calculadora de tokens MCP — quanto essas descrições custam por requisição.
• Scanner de segurança MCP — as mesmas descrições, verificadas quanto a instruções plantadas em vez de clareza.
• Criar um servidor MCP em Python

Uma descrição não consegue servir a dois leitores

Ajustar uma descrição para a seleção de ferramentas a deixa curta, específica e voltada à máquina — e inútil para um cliente tentando entender o que o seu servidor faz. Essa tensão é real e não se resolve escrevendo melhor. O MCP Showcase a resolve gerando as duas coisas a partir do mesmo servidor: os seus esquemas enxutos continuam indo ao modelo, enquanto clientes em potencial recebem um playground ao vivo com documentação legível por ferramenta que podem realmente experimentar no navegador.