Pare de escrever descrições de ferramentas MCP como se um humano estivesse lendo

Eu passei os últimos anos observando desenvolvedores construírem servidores MCP incríveis, apenas para vê-los desmoronar em produção por algo fundamentalmente estúpido: instruções ruins.

Você constrói uma integração sofisticada—talvez ela se conecte a um CRM legado ou a uma API de faturamento complexa. Você lida com a autenticação, gerencia o sandboxing via V8, tem seus tipos TypeScript perfeitamente mapeados. Então, na linha de chegada, você escreve uma descrição da ferramenta que soa 'legal.' Algo como: "Esta ferramenta permite que você busque informações do usuário em nosso banco de dados e retornará os detalhes como uma string."

E então, quando você a insere no Claude Desktop ou Cursor, o agente começa a alucinar. Ele tenta passar user_id quando você nomeou o parâmetro como userId. Ele esquece que a saída é uma string porque você não declarou explicitamente o tipo de retorno de uma maneira acionável. Ele se perde no 'fluff.'

O problema não é seu LLM. O problema é que você está escrevendo para humanos, mas essas ferramentas estão sendo consumidas por agentes. Agentes não precisam de polidez; eles precisam de densidade semântica.

O Problema da Densidade Semântica

Quando falamos sobre chamadas de função no ecossistema MCP, não estamos apenas falando sobre APIs. Estamos falando sobre um novo tipo de Arquitetura de Conjunto de Instruções (ISA) onde as 'instruções' são escritas em linguagem natural, mas executadas por lógica de alta precisão.

Nesse contexto, cada palavra extra na descrição da sua ferramenta é essencialmente ruído que aumenta a probabilidade de um erro de análise ou uma falha de raciocínio. Se um agente tem que navegar por três frases de 'contexto' antes de encontrar um verbo imperativo, você está desperdiçando sua janela de contexto e aumentando sua carga cognitiva. É aqui que a densidade semântica entra.

Densidade semântica é a razão entre informações acionáveis e o comprimento total do texto. Uma descrição de alta densidade usa verbos imperativos e fornece tipos de retorno claros, minimizando o ruído linguístico que pode distrair um LLM durante a chamada de função.

Recentemente, comecei a usar uma ferramenta específica para auditar minhas próprias definições de servidor: o Tool Description Semantic Density Scorer. Não é apenas uma questão de 'sentir' que suas descrições são boas; ela realmente mede sua integridade estrutural.

Analisando a Densidade de Verbos e Comandos Acionáveis

A primeira coisa que o avaliador observa é calculate_verb_encensity. Isso soa acadêmico, mas na prática, trata-se de identificar se a descrição da sua ferramenta é realmente uma instrução ou apenas um parágrafo de prosa.

Uma ferramenta MCP eficaz deve ser ancorada por verbos imperativos e orientados para a ação: retrieve, update, delete, fetch, calculate. Se eu vejo descrições que usam voz passiva ou 'fluff' descritivo como "é projetada para ajudá-lo...", a razão de densidade cai. Uma string de alta densidade, como "Recupere o registro e depois atualize-o," tem uma concentração muito maior de comandos acionáveis em relação ao seu comprimento (aproximadamente 0.28 em nossos testes). Isso diz ao agente exatamente o que a operação envolve sem a necessidade de raciocínio secundário.

O Assassino Silencioso: Uniformidade de Nomenclatura

Há outra maneira pela qual as chamadas de ferramentas MCP falham que é quase impossível de detectar durante um teste unitário padrão: inconsistência de nomenclatura nas listas de parâmetros.

Você pode ter um parâmetro como user_id (snake_case) e outro como userAge (camelCase). Para um humano, é trivial. Para um LLM tentando construir um objeto JSON válido para uma chamada de função, é um enorme sinal vermelho que leva a falhas de análise a montante na camada de integração.

O Avaliador usa analyze_naming_uniformity para auditar essas listas de parâmetros. Ele verifica a consistência de caixa (por exemplo, camelCase vs. snake_case) e retorna uma pontuação de uniformidade. Se sua definição de ferramenta tiver até mesmo um parâmetro desviado, ele sinaliza. Isso é crítico quando você está construindo ferramentas complexas que dependem de padrões consistentes em várias chamadas de função.

O Agregador: Avaliando a Clareza Total

O verdadeiro cerne desse processo é a ferramenta evaluate_description_clarity. Ela atua como um agregador primário. Não olha apenas para verbos ou nomes isoladamente; calcula uma pontuação de clareza ponderada integrando:

1. Densidade de verbos (Há ação suficiente?).
2. Uniformidade de nomenclatura (A sintaxe é previsível?).
3. Definições explícitas de tipo de retorno (Diz 'retorna uma string' ou 'retorna um objeto'?).

Você pode literalmente passar seu texto por isso e obter uma nota definitiva sobre quão confiável essa ferramenta será em um ambiente automatizado como Windsurf ou Claude Desktop.

Por Que Isso Importa para a Produção

Se você está apenas brincando com MCP em um sandbox local, talvez não importe. Mas se você está construindo ferramentas de nível de produção—o tipo que construímos na Vinkius que lida com lógica de negócios real e dados sensíveis—você não pode se dar ao luxo de ambiguidade.

Quando um agente tem acesso às suas ferramentas, sua capacidade de desempenho está diretamente limitada pela precisão de suas definições. Se suas descrições são 'fluffy,' você está essencialmente entregando um manual quebrado a um trabalhador altamente qualificado e se perguntando por que ele não consegue seguir as instruções.

Você deve estar verificando suas definições de ferramentas com o mesmo rigor que você verifica seu código TypeScript. Verifique a caixa, verifique a densidade de verbos e assegure-se de que os tipos de retorno sejam explícitos. Se você não fizer isso, não está construindo uma ferramenta agente; você está apenas torcendo para que tudo dê certo.

Os MCPs são a música dos Agentes de IA. Nós construímos o catálogo. Descubra Vinkius MCP Catalog.