En nuestro primer post de esta serie, Todo es una prueba, presentamos Arcade.dev Evals: un framework para probar si los LLMs pueden seleccionar la herramienta MCP correcta y llenar los argumentos correctamente, sin ejecutar ninguna herramienta. Este post se enfoca en lo práctico: qué separa una buena definición de una mala, y cómo medir la diferencia.
Las definiciones de herramientas no son firmas de funciones
Construir herramientas MCP de alta calidad requiere pensar bien, no solo en cómo funcionan internamente, sino también en cómo se presentan a los LLMs para que entiendan su uso correcto en cada escenario. Un conjunto de definiciones bien descritas puede impactar directamente el rendimiento de tu agente, lo que se traduce en una mejor experiencia para quienes lo usan.
Como constructores de herramientas sin experiencia, es fácil tratar las herramientas MCP como funciones de código normales. No pensamos mucho en cómo las presentamos a los modelos: tomamos los nombres exactos del spec de OpenAPI (parecen suficientemente descriptivos) y nos saltamos las descripciones. ¿Quién lee la documentación, verdad? Para simplificar, también aceptamos enums como strings. Luego hacemos el cableado necesario para que las herramientas usen nuestra API REST y listo.
El problema aparece al probar en el mundo real. La herramienta puede no fallar de forma escandalosa: dependiendo de los requisitos de formato, los modelos más capaces (y costosos) suelen inferir qué hacer con un toolkit mal definido, pero los modelos más baratos van a sufrir más. El problema principal surge cuando necesitas parámetros que requieren formatos específicos, como fechas y enums. Sin la guía adecuada, incluso los modelos competentes pueden equivocarse con el formato correcto, sobre todo si usamos strings para enums y fechas, lo que introduce una complejidad cardinal enorme.
Además, dependiendo de tu conjunto de herramientas, el modelo puede caer en una trampa de ambigüedad y elegir una herramienta que cree que hace exactamente lo que quieres, por falta de una buena descripción. Dependiendo de lo que haga esa herramienta, puede ser desastroso. Por si fuera poco, las herramientas mal definidas también generan un mayor consumo de tokens por los reintentos repetidos.
La analogía del menú de restaurante
Nuestro primer error fue tratar las definiciones de herramientas MCP como firmas de funciones. No lo son. Se parecen más a los platillos de un menú de restaurante: le das a un LLM las opciones y, según el contexto, elige la más atractiva y la parametriza. Luego el mesero lleva el pedido a la cocina y te lo trae de vuelta.
Si el menú solo tiene nombres genéricos sin más detalles, quién sabe qué te van a traer cuando quieras probar algo nuevo. Cuando llega, si no te gusta, puedes intentar pedir de nuevo, pero el mismo problema puede repetirse indefinidamente hasta que te rindes. En el peor de los casos, podrías recibir algo con ingredientes a los que eres alérgico, con efectos secundarios irreparables para tu salud.
Cómo se ve cuando está bien hecho
El primer cambio lógico es actualizar los nombres de las herramientas para que la intención quede clara incluso cuando solo está disponible el nombre. Esto ayuda tanto a los LLMs como a las personas que administran sus propios conjuntos de herramientas. También agregamos una descripción que captura el propósito y las restricciones críticas de la herramienta, sin ser verbosa.
El siguiente cambio aplica a cada parámetro. Hay que describir los formatos requeridos, los valores por defecto y los valores aceptados (incluidas las opciones de enum). Esto es sumamente importante y aumentará considerablemente la tasa de éxito de las llamadas a herramientas.
# BEFORE: Vague tool definition
{
"name": "schedule", # Generic name
# No description!
"inputSchema": {
"properties": {
"when": {"type": "string"}, # What format?
"type": {"type": "string"}, # What are the options?
"location": {"type": "string"}, # Zoom? Address? URL?
}
}
}
# AFTER: Descriptive tool definition
{
"name": "create_meeting",
"description": "Schedule a video meeting with ISO formats and one attendee.",
"inputSchema": {
"properties": {
"datetime": {
"type": "string",
"description": "ISO 8601 datetime (YYYY-MM-DDTHH:MM)"
},
"meeting_type": {
"type": "string",
"description": "Meeting type: demo | review | planning | 1:1"
},
"platform": {
"type": "string",
"description": "Video platform",
"enum": ["Zoom", "Google Meet", "Teams"]
}
}
}
}Midiendo la diferencia
Corrimos ambas versiones en Arcade Evals con los mismos casos de prueba en múltiples modelos. Los resultados fueron consistentes: el toolkit vago no alcanzó el umbral del 90% en los casos de programación de reuniones en ninguno de los modelos probados. El toolkit descriptivo pasó consistentemente.
¿La causa principal de los fallos? La falta de guía de formato (datetime y duración ISO) y el mapeo de enums/listas. Cuando no le dices al modelo que “when” debe ser “2026-02-04T14:00”, lo adivina. Y a veces adivina mal.
Sabiendo esto, construimos un framework de evals enfocado en la puntuación de coincidencia de herramientas que te permite probar si un LLM puede seleccionar la herramienta correcta y llenar los argumentos correctamente, usando solo definiciones de herramientas y prompts. Sin necesidad de ejecutar las herramientas.
Una checklist rápida para schemas de herramientas MCP de alta calidad
Cosas que debes tener en mente al construir herramientas MCP:
- Los nombres de herramientas comunican intención: prefiere verbos + objetos (
create_meeting,send_email): prefiere estos sobre verbos genéricos (schedule,notify). - Las descripciones indican restricciones: una oración que explique qué hace la herramienta y qué no hace.
- Los parámetros son amigables para el modelo: los nombres coinciden con el lenguaje del usuario; las descripciones incluyen formatos y ejemplos.
- Los conjuntos cerrados son enums: si el valor debe ser una de N opciones, lístalas.
- Los formatos son explícitos: datetime/duración ISO, IDs, expectativas de parsing de URLs, reglas de ordenamiento.
- Evita los “requisitos ocultos”: si una herramienta necesita identidad, selección o contexto, conviértelo en un input o proporciona ese contexto.
Empieza con Arcade Evals
¿Listo para probar tus herramientas MCP antes de que lleguen a producción? Arcade Evals viene integrado en el Arcade CLI.
pip install 'arcade-mcp[evals]'
arcade evals .Para la documentación completa, consulta la guía de Arcade Evals.
¿Quieres profundizar más? Corrimos estos evals en 14 modelos con 3 ejecuciones cada uno, incluyendo una evaluación completa del Figma MCP Server. Lee el reporte o córrelo tú mismo.
