Seu Servidor MCP Tem um Problema Secreto de Scoring

Seu servidor MCP funciona perfeitamente em demos. Você sabe que funciona porque foi você quem construiu a demo. Você escolheu o prompt a dedo, a ferramenta disparou, o resultado voltou limpo. Todo mundo assentiu. Bora publicar.

Então chega a produção.

Em produção, o LLM escolhe a ferramenta errada 30% das vezes. Usuários reportam resultados estranhos. O agente chama search quando deveria chamar fetch. Passa uma string de data onde precisa de um timestamp epoch. Ignora completamente sua ferramenta mais poderosa porque não consegue descobrir quando usá-la.

O que mudou? Nada no seu código. Os handlers estão bem. A lógica está bem. O problema sempre esteve lá — você só nunca percebeu porque demos são roteirizadas e produção não é. Na demo, você controla a entrada. Em produção, o LLM tem que descobrir qual das suas quinze ferramentas combina com o pedido ambíguo de um usuário. E ele falha nessa etapa muito mais do que você imagina.

Este é o problema secreto de scoring. Seu servidor não tem um bug. Ele tem uma lacuna de qualidade que só aparece quando um modelo de linguagem precisa tomar decisões reais sobre suas ferramentas.

Algo que a maioria dos desenvolvedores MCP não internaliza: o LLM nunca lê seu código. Ele nunca vê a lógica dos seus handlers, suas regras de validação, seu tratamento de erros cuidadoso. Tudo que ele vê é um nome, uma descrição e um schema.

Só isso. Essa é a interface completa entre sua ferramenta e a inteligência que decide se vai usá-la.

Se duas ferramentas têm descrições parecidas, o LLM chuta. Ele não pede esclarecimento. Não sinaliza ambiguidade. Escolhe uma e segue em frente. Se sua descrição diz "buscar documentos" e outra ferramenta diz "encontrar documentos", o LLM está essencialmente tirando cara ou coroa.

Se uma descrição é vaga, o LLM alucina a intenção. Preenche as lacunas com suposições. "Gerenciar configurações do usuário" pode significar ler, gravar, deletar ou exportar configurações. O LLM vai assumir um significado e se comprometer com ele sem avisar ninguém.

Seleção de ferramentas é um problema de linguagem, não de código. O instinto de engenheiro é debugar o handler. A correção real quase sempre está no texto — as vinte palavras que descrevem o que sua ferramenta faz e quando usá-la. A maioria dos times nunca olha para lá porque está ocupada demais lendo stack traces.

Um score de qualidade não é um número único. Se fosse, seria inútil — como dar a um restaurante uma nota só sem distinguir comida de serviço de ambiente.

Um score de qualidade real tem seis dimensões, cada uma mensurável independentemente, cada uma capaz de arruinar a confiabilidade da sua ferramenta sozinha.

Clareza da descrição: A descrição explica o que a ferramenta faz, quando usá-la e quando não usar? Especifica o formato de resposta? Um score de 40 aqui significa "o LLM vai usar mal esta ferramenta regularmente." Um score de 90 significa "o LLM quase sempre escolhe esta ferramenta corretamente."

Completude do schema: Os parâmetros são tipados com precisão? Os campos obrigatórios são realmente obrigatórios? Enums são usados onde valores são restritos?

Consistência de nomes: Suas ferramentas seguem um padrão previsível? Se você tem create_user e delete_user mas depois fetch_all_documents, a inconsistência cria sobrecarga cognitiva para o modelo.

Detecção de sobreposição: Quantas das suas ferramentas poderiam plausivelmente corresponder ao mesmo pedido? Alta sobreposição é o maior preditor de seleção errada.

Documentação de erros: A ferramenta descreve o que acontece quando as coisas dão errado?

Cobertura de exemplos: Há exemplos de uso na descrição? Exemplos valem mais que parágrafos de explicação porque ancoram o entendimento do LLM em padrões concretos.

Vamos tornar isso concreto. Assim é um score de 40 versus 90 em cada dimensão.

Clareza da descrição a 40: "Pesquisa no banco de dados." A 90: "Busca full-text em todos os documentos indexados. Retorna os 10 melhores resultados por relevância. Use quando o usuário quer encontrar documentos por conteúdo. Não use para busca por ID exato — use get_document. Retorna título, trecho e score de relevância."

Completude do schema a 40: Um único parâmetro "query" tipado como string, sem restrições. A 90: "query" como string não vazia com comprimento máximo 500, mais "limit" opcional como integer min 1 max 100 default 10, mais "date_range" opcional com datas ISO 8601.

Nomes a 40: search, getDoc, user_remove, ListAllItems. A 90: search_documents, get_document, remove_user, list_items. O padrão é verbo_substantivo, consistentemente.

Sobreposição a 40: search_documents, find_documents e query_documents existem e fazem coisas ligeiramente diferentes. A 90: cada ferramenta tem um propósito claro e não sobreposto.

A diferença é sempre especificidade. Ferramentas vagas falham. Ferramentas precisas funcionam. E a distância entre 40 e 90 geralmente não é uma reescrita — é uma tarde de edição cuidadosa.

A maioria dos times debuga a camada errada. Veem falhas de seleção de ferramentas e correm pro código. Reescrevem handlers para ser mais tolerantes. Adicionam lógica de retry. Trocam para um modelo mais caro. Constroem camadas de roteamento elaboradas em cima do MCP para compensar a ambiguidade embaixo.

Tudo isso é caro, demorado, e trata o sintoma em vez da causa.

A correção real geralmente é uma edição de 20 palavras numa descrição. Mudar "gerencia documentos" para "cria um novo documento a partir do título e corpo fornecidos. Retorna o ID do documento. Use apenas para criar novos documentos — para atualizar documentos existentes, use update_document."

Essa edição levou trinta segundos. Ela elimina uma categoria inteira de erros de seleção. Nenhum código mudou. Nenhum upgrade de modelo necessário.

Quality scoring te diz exatamente quais 20 palavras mudar. Aponta a dimensão específica que está falhando, na ferramenta específica que causa problemas, com uma sugestão concreta do que escrever. Transforma um vago "a IA fica confusa" num preciso "a descrição do seu search_documents não menciona o formato de resposta, e 34% das falhas se rastreiam ao LLM interpretando mal os resultados."

Por isso a medição importa. Não porque o score em si é valioso, mas porque ele converte um problema invisível em um visível e corrigível. Os times que entendem isso param de reescrever handlers e começam a reescrever descrições. Entregam correções em minutos em vez de dias. E suas ferramentas simplesmente funcionam — não porque o código é melhor, mas porque a linguagem é.