CCAR-F · Diseño de herramientas y MCP
Errores de herramientas que el agente puede usar
“Operation failed” es el peor mensaje que puede recibir un agente. No dice si conviene esperar y reintentar, corregir la entrada, avisarle al cliente o pedir ayuda. Con esa respuesta el agente reintenta lo que nunca va a funcionar o abandona lo que se podía resolver.
Los tres campos que guían la recuperación
En MCP, una herramienta marca su falla con el indicador de error (isError): isError: true le dice al agente que la llamada falló. Arriba de eso, conviene sumar metadatos estructurados:
- categoría del error (errorCategory): qué tipo de falla es;
- reintentable (isRetryable): si repetir la misma llamada puede funcionar;
- descripción: qué falló y qué hacer, en lenguaje claro.
Las cuatro categorías
| Categoría | Ejemplo | Qué hace el agente |
|---|---|---|
| Transitorio (transient) | El gateway de pagos no respondió en 30 segundos | Reintentar con espera y un límite de intentos |
| Validación (validation) | order-abc en lugar de #12345 |
Corregir la entrada y hacer una llamada nueva |
| Negocio (business) | Reembolso de 750 con un límite automático de 500 | Explicar la política y escalar, sin cambiar lo que pidió el cliente |
| Permisos (permission) | La clave no tiene acceso a ese recurso | Escalar o pedir el acceso |
Ojo con validación: isRetryable es false porque reenviar lo mismo falla siempre, pero no es un callejón sin salida. La descripción tiene que nombrar el campo, el formato esperado y un ejemplo (“Expected YYYY-MM-DD, e.g. 2026-10-20; resolve relative dates”). “Invalid input.” no le da nada con qué corregir.
En los errores de negocio, la descripción además debería traer una explicación apta para el cliente, para que el agente pueda contarle qué pasó.
“No encontré nada” no es “no pude buscar”
Una consulta que funcionó y no tuvo coincidencias es un resultado vacío válido (valid empty result): isError: false y una lista vacía. Una base caída es un error transitorio. Si la herramienta devuelve un array vacío en los dos casos, el agente reintenta un éxito o, peor, le dice al cliente que su cuenta no existe cuando en realidad no pudo buscar. Lo mismo al revés: devolver el texto de la excepción con isError: false hace que el agente lo cite como si fuera un dato.
Fallas parciales en subagentes
Un subagente que busca en cinco fuentes y tiene timeout en dos no debería esconder las fallas ni tirar todo. Aplica recuperación local (local recovery): reintenta lo transitorio por su cuenta y, si no lo resuelve, le devuelve al coordinador los resultados parciales, qué intentó y qué falló. Con eso el coordinador decide si reintenta solo esas fuentes, sigue con lo que hay o anota el hueco.
Las trampas típicas
- Reintentar un error de negocio con backoff: la política no cambia entre intentos.
- “Arreglar” el pedido en silencio: pasar a un reembolso parcial o cancelar con cargo sin el acuerdo del cliente.
- Escalar un formato mal escrito: es desproporcionado si el modelo puede corregirlo con la información correcta.
- Detectar errores buscando la palabra “Error” en el texto: frágil, y no dice si reintentar.
- Reglas de reintento por herramienta en el prompt: no generalizan; los metadatos sí.
En el examen
Leé el error del escenario y clasificalo: ¿pasajero, entrada mal formada, regla de negocio o permisos? La opción correcta es la que trata ese tipo como corresponde y le da al agente los metadatos para decidir.
Pregunta rápida
Una pregunta del simulacro sobre este dominio. Cuenta para tu progreso.
A furniture retailer's support agent has two tools for account questions: get_customer for profile data and lookup_order for orders. During a design review, the team looks at the draft description for lookup_order: "Queries the orders database. Accepts order_id (string). Returns JSON with status, items and total. Rate limit: 100 requests/min." The description was copied from the internal API documentation written by the backend team.
In staging, the agent sometimes calls lookup_order for customer-profile questions such as "what email do you have on file for me?", which belong to get_customer. The staging environment uses the same model and system prompt that will go to production next month.
Which addition to the draft would most improve tool selection?