Conoce a tu estudiante y dale las herramientas adecuadas
Idiomas 101
Quienes tomaron clases de idiomas recuerdan bien esto: los profesores te ponían en situaciones diseñadas para simular la vida real, en un restaurante, en una reunión formal, en una cita. Te daban contexto y medían qué tan bien te desempeñabas. Pero no estabas realmente ahí; solo hacías un juego de roles. El objetivo era claro: practicar en un entorno seguro, recibir retroalimentación y ganar confianza antes de enfrentar esas situaciones de verdad. A partir de eso, el profesor podía estimar cómo te iría en la vida real. Si no salía bien, recibías comentarios y sugerencias para mejorar. Tal vez no era tu culpa, sino el método de enseñanza; quizá otro enfoque habría funcionado mejor.
Esto es un gran paralelo de cómo funciona Arcade.dev Evals. Así como los estudiantes de idiomas necesitan practicar antes de conversaciones reales, nosotros necesitábamos una forma de probar y aumentar la confianza en la calidad de las definiciones de herramientas antes de llevarlas a producción. Con Arcade Evals podemos construir un escenario de juego de roles donde el LLM es el estudiante: le agregamos un contexto de conversación simulada, le damos acceso a las definiciones de herramientas y le enviamos un mensaje de usuario con el resultado esperado que queremos validar. Lo clave es que esto prueba la selección de herramientas sin necesidad de ejecutarlas de verdad. Sin llamadas a API, sin efectos secundarios, sin infraestructura. El modelo es nuestra constante y las herramientas son lo que evaluamos. Las rúbricas califican si las definiciones eran lo suficientemente claras para que el modelo eligiera la herramienta correcta y llenara los argumentos bien.
En esta analogía, somos los profesores que les dan a los estudiantes herramientas que, si se usan bien, los ayudan a destacar en situaciones reales. Si el estudiante no se desempeña bien, también consideramos que el problema puede estar en las herramientas que les dimos. Todo el proceso es pedagógico: buscamos mejorar las herramientas para que sean intuitivas según las habilidades del estudiante. Podemos construir herramientas increíbles que hagan cosas sorprendentes, pero si solo funcionan con los modelos más avanzados y estamos desplegando en un entorno con capacidades mixtas, pueden ser prácticamente inútiles.
Vocabulario rápido
Antes de profundizar en Arcade Evals, conviene familiarizarse con algunos términos clave:
- Definición de herramienta / schema: el JSON schema y las descripciones que el modelo ve para una herramienta (nombres, parámetros, formatos, enums).
- Caso de eval: una solicitud de usuario + contexto opcional + las llamadas de herramienta esperadas.
- Critics: calificadores para los argumentos de herramienta (coincidencia exacta vs. similitud).
- Rubric: umbrales de pass/warn/fail entre los critics.
- Tracks: conjuntos de herramientas paralelos (por ejemplo, “vago” vs. “descriptivo”) evaluados con los mismos casos.
Afilando nuestras habilidades pedagógicas con Arcade Evals
La calidad de las herramientas afecta directamente la confiabilidad del agente. Una herramienta bien diseñada tiene descripciones claras, nombres de parámetros intuitivos y schemas sin ambigüedades que permiten al LLM seleccionarla en el momento correcto y llenar los argumentos bien. Cuando las herramientas están mal diseñadas, los agentes fallan de forma silenciosa o impredecible en producción: eligen herramientas incorrectas, pasan argumentos malformados o se pierden la acción correcta por completo. Por eso la evaluación sistemática es indispensable: hay que medir si las herramientas son comprensibles para el modelo antes de que los usuarios encuentren fallas.
La idea central es simple: crea un conjunto de situaciones realistas, pídele al modelo que las resuelva con las herramientas que le das y califica si usó la herramienta y los argumentos correctos. Arcade Evals empaqueta esto en suites de casos, donde cada caso tiene un mensaje de usuario, contexto opcional, llamadas de herramienta esperadas y critics que califican los argumentos. Las rúbricas convierten esas puntuaciones en un resultado claro de pass, warn o fail, para que puedas ver si una herramienta está lista para uso real.
Mira el fragmento de código abajo. Representa un caso de eval completamente ejecutable:
"""Minimal Arcade Evals example – a complete, runnable evaluation suite."""
from arcade_evals import (
BinaryCritic, # Exact match validator
SimilarityCritic, # Fuzzy text matching (cosine similarity)
EvalRubric, # Pass/warn/fail thresholds
EvalSuite, # Container for test cases
ExpectedMCPToolCall, # What we expect the LLM to call
FuzzyWeight, # Enum for qualitative weight assignment
MCPToolDefinition, # Tool schema definition
tool_eval, # Decorator to register eval functions
)
# ---------------------------------------------------------------------------
# 1. Define your MCP tools (the interface the LLM sees)
# ---------------------------------------------------------------------------
TOOLS: list[MCPToolDefinition] = [
{
"name": "schedule_meeting",
"description": "Book a calendar meeting with one attendee.",
"inputSchema": {
"type": "object",
"properties": {
"title": {"type": "string", "description": "Meeting title"},
"attendee": {"type": "string", "description": "Email of attendee"},
"datetime": {
"type": "string",
"description": "ISO 8601 datetime (e.g., 2026-02-04T14:00)",
},
"location": {
"type": "string",
"description": "Meeting platform",
"enum": ["Zoom", "Google Meet", "Teams"],
},
},
"required": ["title", "attendee", "datetime", "location"],
},
},
]
# ---------------------------------------------------------------------------
# 2. Create an evaluation suite with test cases
# ---------------------------------------------------------------------------
@tool_eval() # Registers this function with the eval runner
async def eval_scheduling_tools() -> EvalSuite:
suite = EvalSuite(
name="Scheduling Tools Evaluation",
system_message="You are a scheduling assistant. Use the provided tools.",
rubric=EvalRubric(fail_threshold=0.8, warn_threshold=0.9),
tools=TOOLS,
)
suite.add_case(
name="Book team sync",
user_message="Schedule a team sync with alice@acme.com tomorrow at 3pm on Zoom",
expected_tool_calls=[
ExpectedMCPToolCall(
name="schedule_meeting",
arguments={
"title": "Team sync",
"attendee": "alice@acme.com",
"datetime": "2026-01-23T15:00",
"location": "Zoom",
},
)
],
critics=[
SimilarityCritic(
critic_field="title",
weight=FuzzyWeight.HIGH,
similarity_threshold=0.8,
),
BinaryCritic(
critic_field="attendee",
weight=FuzzyWeight.CRITICAL,
),
BinaryCritic(
critic_field="datetime",
weight=FuzzyWeight.CRITICAL,
),
BinaryCritic(
critic_field="location",
weight=FuzzyWeight.MEDIUM,
),
],
)
return suiteEsto te da un ciclo de retroalimentación que puedes usar como cualquier otro oficio: captura cómo se comporta el modelo, establece expectativas y sigue iterando en descripciones y schemas hasta que el modelo haga lo correcto de forma consistente.
Qué información puede darte Arcade Evals
Arcade Evals fue diseñado para ayudar a quienes construyen herramientas MCP y agentes a obtener resultados objetivos que simulan cómo actúan los LLMs cuando se les pide resolver una solicitud de acción. Las definiciones de herramientas se pueden cargar desde código fuente de herramientas Python de Arcade, Arcade MCP Gateways, servidores MCP remotos o locales, o definiciones de herramientas basadas en diccionarios. Algunos ejemplos de cómo ayuda:
- Evalúa cómo se comporta un conjunto de herramientas en diferentes modelos y proveedores.
- Valida si el propósito de una herramienta se comunica con claridad; ajusta nombres de herramientas, nombres de parámetros y descripciones cuando no es así.
- Prueba definiciones de herramientas de forma iterativa con dicts sin comprometerte a código de producción.
- Compara diferentes servidores MCP o versiones usando el mismo contexto y las mismas expectativas.
- Valida la calidad de servidores MCP de terceros con interacciones de usuario simuladas y realistas.
- Verifica la consistencia de Arcade MCP Gateway a medida que agregas toolkits de distintos proveedores.
- Usa las evals como pruebas de regresión cuando cambies schemas o agregues herramientas.
Qué no evalúa Arcade Evals (y por qué está bien)
Arcade Evals está diseñado intencionalmente para la selección de herramientas y la calidad de los argumentossin ejecutar la herramienta. Eso significa que no valida:
- Si la llamada a la API downstream tiene éxito
- Si la salida de la herramienta es correcta o útil
- Planificación en múltiples pasos y reintentos (a menos que elijas evaluar esos patrones explícitamente)
- Latencia, límites de tasa, auth o efectos secundarios
Esto es una característica, no un error: te permite iterar en los schemas de herramientas de forma temprana, barata y segura.
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 evalsPara una lista práctica de lo que hace que las definiciones de herramientas funcionen (con ejemplos antes/después), lee Building High-Quality MCP Tools with Arcade Evals.
Para los datos completos del benchmark detrás de este enfoque, consulta el reporte técnico.
