El 90% de Tus MCP Tool Schemas Fracasan en Producción Por Diseño Equivocado
Tu schema de MCP pasa la validación JSON Schema. Pasa el linter. Pasa el test de schema.
Pero Claude lo ignora, lo malformatea, o directamente salta la tool.
El problema real no es si tu schema es válido. Es cuántos tokens necesita Claude para descifrar qué parámetro va dónde.
La sabiduría convencional te dice que tus tool schemas deben reflejar tus API contracts. Eso es al revés. Debes diseñar schemas que exploten cómo funciona la inferencia token-a-token de Claude, no cómo de RESTful son tus endpoints.
La diferencia entre un schema que funciona y uno que falla no la ves en los logs de tu API. La ves en la tasa de invocación exitosa.
El Error de Diseñar para Validadores, No para Modelos
La mayoría de tutoriales de MCP te enseñan a escribir JSON Schema técnicamente correcto. Estructuras profundas con $ref y allOf. Enums para todo. Tipos estrictos en cada propiedad.
Esto funciona si tu consumidor es un validador automático. Pero Claude no analiza el documento completo después de recibirlo.
Claude genera tool calls como un proceso autoregresivo token-a-token. Cada token que genera depende del anterior. Cuando encuentra un schema con objetos anidados a profundidad >2 y referencias cruzadas, el modelo debe generar JSON con la estructura de anidamiento correcta al primer intento.
No hay backspace en el stream de tokens.
Cada nivel de anidamiento adicional introduce un riesgo de ramificación token-level donde el modelo se compromete con una estructura que después puede resultar incorrecta.
Un validador JSON analiza el documento completo post-hoc. Claude opera en tiempo real, generando sin visibilidad del destino final.
Por eso un schema que pasa todas las validaciones puede tener un 40% de tasa de fallo en invocación.
El Mito del Enum como Mejora
Aquí viene lo contraintuitivo.
Los enums restringen el espacio de salida. Suena útil. El modelo solo puede elegir entre opciones válidas.
Pero el entrenamiento de Claude contiene ejemplos de schemas con enums donde el modelo inventó valores que no estaban en la lista. Porque intentó ser "útil" con una aproximación cercana.
El modelo estaba generalizando desde el mismo pattern-matching que usa para lenguaje natural. Y falló.
❌ Schema con enum que falla:
✅ Schema con string descriptivo + ejemplos:
Los ejemplos en el campo description primean las predicciones next-token del modelo con más precisión que los enums. Porque activan el mismo mecanismo de pattern-matching que Claude usa para lenguaje natural.
Por Qué el Orden de Parámetros Determina el Éxito
Parameter ordering en el schema importa más de lo que nadie menciona.
Claude genera tool call JSON en orden. Si los parámetros requeridos aparecen al final de la definición del schema, el modelo puede generar primero los campos opcionales no requeridos —consumiendo tokens— y después fallar en incluir los campos requeridos cuando se queda sin contexto.
Los schemas deben listar parámetros requeridos primero, luego los opcionales en orden descendente de importancia. Alineado con el flujo de generación de tokens.
❌ Schema con parámetros requeridos al final:
✅ Schema con parámetros requeridos primero:
El Patrón de Simplificación Estructural (PSE)
Después de analizar cientos de schemas MCP en producción, encontré un patrón repeatable que reduce fallos de invocación drásticamente.
El PSE tiene 5 pasos:
Step 1: Auditoría de Fallos de Invocación
Antes de cambiar nada, necesitas datos. Cada vez que Claude refuse, malformatee, o skip una tool, logged con la propiedad del schema que causó el fallo.
Categoría los fallos por tipo de propiedad: anidamiento, enum, orden, descripción, referencia cruzada.
Sin esta métricas, estás rediseñando ciegas.
Step 2: Eliminar `$ref` y `allOf`
Las referencias cruzadas fuerzan al modelo a mantener múltiples contextos activos simultáneamente. Cada $ref es un punto de ramificación token-level.
Reemplaza $defs y referencias cruzadas con estructuras planas. El modelo genera mejor desde un solo contexto.
❌ Schema con referencias circulares:
✅ Schema plano equivalente:
Step 3: Reemplazar Enums con Descriptive Strings
Cada enum es una oportunidad de hallucination. En su lugar, usa un campo description que incluya 3-5 ejemplos de valores válidos junto con contexto de uso.
El modelo generaliza mejor desde ejemplos que desde listas de tokens.
Step 4: Aplanar Objetos con Profundidad > 2
Los objetos anidados a profundidad mayor de 2 niveles multiplican el coste de inferencia. Cada nivel de anidamiento requiere que el modelo genere la estructura correcta antes de saber qué valores irán dentro.
Reestructura estos objetos como parámetros top-level separados. La pérdida de "pureza arquitectónica" del schema se traduce en ganancia de invocación exitosa.
Step 5: Test con Eval Harness Controlado
Antes y después de cada cambio de schema, ejecuta la misma tool con el mismo prompt en un eval harness controlado.
Mide invocación accuracy, no solo schema validity. El validador puede pasar en verde mientras el modelo falla el 30% de las veces.
El Caso de la Weather Tool
Veamos un ejemplo real que demuestra la diferencia.
❌ Weather tool con schema sobre-diseñado:
Este schema fuerza a Claude a generar {"location": {"coordinates": {"lat": ..., "lon": ...}}} al completo antes de saber qué valores pondrá. Cada nivel es una decisión que el modelo debe tomar sin feedback hasta el final.
✅ Weather tool con schema PSE:
El modelo genera lat y lon directamente, sin navegación por el árbol de coordenadas. La tasa de acierto sube significativamente.
El Argumento Contra "Valid JSON Schema Es el Estándar"
Seguramente estás pensando: "Pero mis herramientas funcionan bien con JSON Schema estándar."
La respuesta: probablemente no tienes tracking sistemático de miss rates por tool. Sin logging de fallos de invocación, no sabes lo que te estás perdiendo.
Los developers que implementan el PSE reportan mejoras de 20-30 puntos porcentuales en invocación accuracy después de aplanar schemas que "funcionaban" con validación estricta.
Sobre la preocupación de validation errors en el servidor: puedes transformar el schema entre lo que Claude ve y lo que tu API valida.
Un pre-processing layer acepta el formato flattened que Claude genera y reconstruye la estructura deep que tu API espera. Claude nunca necesita ver el schema complejo.
La validación de API permanece intacta. El schema que ve Claude está optimizado para inferencia, no para matching 1:1 con tu backend.
Tomaaways Clave
- Validez JSON Schema ≠ invocación exitosa. Son métricas distintas. Un schema puede pasar todas las validaciones y fallar el 40% de las veces.
- Los enums son anti-patrón para Claude. Las descripciones con ejemplos generalizan mejor que listas de tokens restringidas.
- Orden de parámetros = orden de generación. Parámetros requeridos primero, luego opcionales por importancia.
- Profundidad > 2 es deuda de inferencia. Cada nivel de anidamiento multiplica el riesgo de ramificación token-level.
- El PSE no rompe tu API. Un pre-processing layer reconstruye la estructura deep que tu backend necesita.
La próxima vez que escribas un tool schema para MCP, pregúntate: ¿Cuántos tokens necesita Claude para descifrar esta tool? Si la respuesta es "más de los necesarios", estás diseñando para el validador, no para el modelo.
Artículos relacionados
- MCP en Producción: El Pattern de Composición que Nadie Te Explica
- Model Context Protocol Guide: How to Build Claude Integrations That Actually Scale
- Claude Skills: Cómo Construir Custom Agents que Realmente Funcionan en Producción
- Claude Agent SDK: Orquestación Multi-Agente para Producción Real
- Claude Skills Avanzados: Cómo Construir Custom Agents con Herramientas Reales
---
¿Quieres recibir contenido como este cada semana? Suscríbete a mi newsletter
