Tu Servidor MCP Tiene un Problema Secreto de Puntuación

Tu servidor MCP funciona perfecto en demos. Lo sabes porque tú construiste la demo. Elegiste el prompt a mano, la herramienta se disparó, el resultado volvió limpio. Todos asintieron. A producción.

Entonces llega producción.

En producción, el LLM elige la herramienta equivocada el 30% del tiempo. Los usuarios reportan resultados raros. El agente llama a search cuando debería llamar a fetch. Pasa un string de fecha donde necesita un timestamp epoch. Ignora tu herramienta más potente porque no sabe cuándo usarla.

¿Qué cambió? Nada en tu código. Los handlers están bien. La lógica está bien. El problema siempre estuvo ahí — solo que nunca lo notaste porque las demos son guionadas y producción no. En una demo, controlas la entrada. En producción, el LLM tiene que descifrar cuál de tus quince herramientas coincide con la solicitud ambigua de un usuario. Y falla en ese paso mucho más de lo que crees.

Este es el problema secreto de puntuación. Tu servidor no tiene un bug. Tiene una brecha de calidad que solo aparece cuando un modelo de lenguaje tiene que tomar decisiones reales sobre tus herramientas.

Algo que la mayoría de los desarrolladores MCP no internalizan: el LLM nunca lee tu código. Nunca ve la lógica de tus handlers, tus reglas de validación, tu cuidadoso manejo de errores. Solo ve un nombre, una descripción y un esquema.

Eso es todo. Esa es la interfaz completa entre tu herramienta y la inteligencia que decide si usarla.

Si dos herramientas tienen descripciones similares, el LLM adivina. No pide aclaración. No señala ambigüedad. Elige una y sigue adelante. Si tu descripción dice "buscar documentos" y otra herramienta dice "encontrar documentos", el LLM esencialmente está tirando una moneda.

Si una descripción es vaga, el LLM alucina la intención. Llena los vacíos con suposiciones. "Gestionar configuración de usuario" podría significar leer, escribir, eliminar o exportar configuración. El LLM asumirá un significado y se comprometerá con él sin decirle a nadie.

La selección de herramientas es un problema de lenguaje, no de código. El instinto ingenieril es depurar el handler. La corrección real casi siempre está en el texto — las veinte palabras que describen qué hace tu herramienta y cuándo usarla. La mayoría de los equipos nunca miran ahí porque están demasiado ocupados mirando stack traces.

Una puntuación de calidad no es un solo número. Si lo fuera, sería inútil — como darle a un restaurante una sola calificación sin distinguir comida de servicio de ambiente.

Una puntuación real tiene seis dimensiones, cada una independientemente medible, cada una capaz de hundir la fiabilidad de tu herramienta por sí sola.

Claridad de descripción: ¿La descripción explica qué hace la herramienta, cuándo usarla y cuándo no? ¿Especifica el formato de respuesta? Un 40 aquí significa "el LLM usará mal esta herramienta regularmente." Un 90 significa "el LLM casi siempre elige esta herramienta correctamente."

Completitud de esquema: ¿Los parámetros están tipados con precisión? ¿Los campos obligatorios son realmente obligatorios? ¿Se usan enums donde los valores están restringidos?

Consistencia de nombres: ¿Tus herramientas siguen un patrón predecible? Si tienes create_user y delete_user pero luego fetch_all_documents, la inconsistencia crea sobrecarga cognitiva para el modelo.

Detección de superposición: ¿Cuántas de tus herramientas podrían coincidir plausiblemente con la misma solicitud? Alta superposición es el mayor predictor de selección incorrecta.

Documentación de errores: ¿La herramienta describe qué pasa cuando las cosas salen mal?

Cobertura de ejemplos: ¿Hay ejemplos de uso en la descripción? Los ejemplos valen más que párrafos de explicación porque anclan la comprensión del LLM en patrones concretos.

Hagámoslo concreto. Así se ve una puntuación de 40 versus 90 en cada dimensión.

Claridad de descripción a 40: "Busca en la base de datos." A 90: "Búsqueda de texto completo en todos los documentos indexados. Devuelve los 10 mejores resultados por relevancia. Usar cuando el usuario quiere encontrar documentos por contenido. No usar para búsqueda por ID exacto — usa get_document en su lugar."

Completitud de esquema a 40: Un solo parámetro "query" tipado como string, sin restricciones. A 90: "query" como string no vacío con longitud máxima 500, más "limit" opcional como entero con mín 1 máx 100, más "date_range" opcional con fechas ISO 8601.

Nombres a 40: search, getDoc, user_remove, ListAllItems. A 90: search_documents, get_document, remove_user, list_items. El patrón es verbo_sustantivo, consistentemente.

Superposición a 40: search_documents, find_documents y query_documents existen y hacen cosas ligeramente diferentes. A 90: cada herramienta tiene un propósito claro y no superpuesto.

La diferencia es siempre especificidad. Las herramientas vagas fallan. Las herramientas precisas funcionan. Y la brecha entre 40 y 90 generalmente no es una reescritura — es una tarde de edición cuidadosa.

La mayoría de los equipos depuran la capa equivocada. Ven fallos de selección de herramientas e inmediatamente van al código. Reescriben handlers para ser más tolerantes. Añaden lógica de reintentos. Cambian a un modelo más caro. Construyen capas de enrutamiento elaboradas encima de MCP para compensar la ambigüedad debajo.

Todo eso es caro, lento, y aborda el síntoma en lugar de la causa.

La corrección real suele ser una edición de 20 palabras en una descripción. Cambiar "gestiona documentos" por "crea un nuevo documento a partir del título y cuerpo proporcionados. Devuelve el ID del documento. Usar solo para crear nuevos documentos — para actualizar existentes, usa update_document."

Esa edición tomó treinta segundos. Elimina toda una categoría de errores de selección. Ningún código cambió. Ninguna actualización de modelo necesaria.

La puntuación de calidad te dice exactamente qué 20 palabras cambiar. Señala la dimensión específica que falla, en la herramienta específica que causa problemas, con una sugerencia concreta de qué escribir. Convierte un vago "la IA se sigue confundiendo" en un preciso "la descripción de tu search_documents no menciona el formato de respuesta, y el 34% de los fallos se remontan a que el LLM malinterpreta los resultados."

Por eso la medición importa. No porque el puntaje sea valioso, sino porque convierte un problema invisible en uno visible y arreglable. Los equipos que entienden esto dejan de reescribir handlers y empiezan a reescribir descripciones. Envían correcciones en minutos en vez de días. Y sus herramientas simplemente funcionan — no porque el código sea mejor, sino porque el lenguaje lo es.