Metadatos reintentables y resultados parciales

Cuando falla una herramienta o un servidor MCP, el modelo debe decidir qué hacer a continuación. Un estado genérico como "Operation failed" no le proporciona nada sobre lo que razonar, por lo que la única opción segura es abortar o adivinar.

Un error estructurado convierte un callejón sin salida en una decisión: ¿debemos reintentar, esquivar el fallo o escalarlo a una persona? En esta lección aprenderá los cuatro campos de metadatos que lo hacen posible: errorCategory, isRetryable, attempted_query y partial_results.

Todo error estructurado de MCP comienza con un booleano: isError: true. Esta es la señal inequívoca de que el resultado de la herramienta es un fallo, no un dato.

Sin ella, el modelo podría tratar un mensaje de error como una respuesta legítima y resumir tranquilamente el fallo como si fuera un resultado. La marca es la puerta que activa toda la lógica de recuperación posterior.

errorCategory clasifica por qué falló la llamada para que el modelo pueda enrutarla de forma inteligente. Las cuatro categorías estándar son:

• transient — un fallo temporal (tiempo de espera agotado, límite de solicitudes). Probablemente convenga reintentarlo.
• validation — la entrada tenía un formato incorrecto. Corrija la solicitud; no reintente a ciegas.
• business — una regla del dominio lo impidió (por ejemplo, el pedido ya se ha enviado).
• permission — el autor de la llamada no está autorizado. Reintentar no ayudará; escale el caso o vuelva a autenticarse.

La categoría orienta la estrategia; no toma la decisión por sí sola.

isRetryable indica explícitamente, con un sí o un no, si reintentar podría llegar a funcionar. Funciona junto con la categoría, pero codifica una señal más precisa.

Un tiempo de espera agotado transient suele tener isRetryable: true. Un error de validation tiene isRetryable: false: reintentar con la misma entrada incorrecta solo volverá a fallar. Y lo que es crucial: esto permite que el subagente recupere localmente los fallos transitorios en lugar de propagar cada contratiempo al coordinador.

Una distinción sutil, pero fundamental para el examen: un FALLO de acceso no es lo mismo que un resultado VACÍO válido.

• isError: true + transient → la consulta no pudo ejecutarse. Considere reintentarlo.
• isError: false + lista vacía → la consulta se ejecutó correctamente y realmente no hay coincidencias. Reintentar no sirve de nada y desperdicia recursos.

Los errores genéricos difuminan esta diferencia. Los metadatos estructurados mantienen claramente separado "no pude consultar" de "consulté y no hay nada".

attempted_query registra exactamente lo que la herramienta intentó hacer: la instrucción SQL, la llamada a la API o la cadena de búsqueda. Esto cumple dos funciones:

• Permite al modelo reintentar con información de retorno: enviar la intención original junto con el error para poder formar una consulta corregida.
• Aporta proveniencia: conserva una trazabilidad entre cada afirmación y su fuente, con constancia de lo que se solicitó realmente.

Recuerde: reintentar con información de retorno corrige errores de formato o estructurales. Si la información simplemente no está en la fuente, ninguna cantidad de nuevas consultas será útil.

Cuando una operación de varios pasos o fuentes falla a mitad de camino, el trabajo realizado antes del fallo sigue teniendo valor. partial_results permite conservarlo.

Imagine un subagente de investigación que consultó cinco fuentes y la quinta agotó el tiempo de espera. Devolver los cuatro resultados correctos junto con el error permite al coordinador continuar, en lugar de descartar todo porque falló una parte. Nunca aborte todo el flujo de trabajo por un solo fallo.

Los metadatos permiten aplicar una estrategia clara de dos niveles en los sistemas de tipo concentrador y satélites:

• Recupere localmente los fallos transitorios dentro del subagente: reintente discretamente los casos con isRetryable.
• Escale los fallos no recuperables al coordinador, incluyendo todo el contexto estructurado: tipo de fallo, consulta intentada y cualquier resultado parcial.

El coordinador gestiona los errores y el enrutamiento. Pero solo puede enrutar bien si el subagente le entrega una señal estructurada en lugar de una excepción sin información o silencio.

Si define el error como una salida estructurada, aplique cuidadosamente las reglas del esquema. Marque un campo como obligatorio solo si siempre está presente. partial_results suele estar vacío o ausente cuando se produce un fallo grave; no lo marque como obligatorio, o el modelo podría inventar entradas para satisfacer el esquema.

Para errorCategory, use un enum con un valor "other" y un campo de texto libre para los detalles. Así mantiene limpia la clasificación actual y permite ampliarla para modos de fallo que aún no haya encontrado.

Los metadatos guían probabilísticamente al modelo (~90 %). Cuando un fallo tiene consecuencias financieras, legales o de seguridad, eso no es suficiente.

Use un hook de PostToolUse para interceptar el resultado de la herramienta antes de que el modelo lo vea y aplicar la política de forma determinista (100 %). Por ejemplo: si errorCategory es permission en una herramienta de reembolsos, bloquee cualquier reintento y fuerce el escalamiento; no deje que el prompt determine si se comporta correctamente.

Lo peor que puede hacer con un fallo es ocultarlo. Hay que evitar dos modos de fallo:

• Supresión silenciosa: ocultar el error y devolver un resultado vacío o inventado. Ahora el modelo no puede distinguir entre un "no hay coincidencias" real y una consulta averiada.
• Abortar todo el flujo de trabajo por un solo componente fallido: se descartan todos los resultados parciales.

Los errores estructurados solucionan ambos problemas: hacen visible el fallo y conservan lo que funcionó.

Los errores estructurados convierten los fallos en decisiones que se pueden enrutar:

• isError — la puerta que activa la lógica de recuperación.
• errorCategory — transient / validation / business / permission (+ "other") establece la estrategia.
• isRetryable — la indicación explícita de reintento; permite recuperar localmente los fallos transitorios.
• attempted_query — permite reintentar con información de retorno y mantener la proveniencia (no ayuda si la información realmente no existe).
• partial_results — conserva los datos útiles; nunca aborte todo el flujo de trabajo por un solo fallo.

Marque como obligatorios solo los campos que siempre estén presentes, proteja los fallos financieros, legales o de seguridad con hooks deterministas y nunca suprima los errores silenciosamente. Eso es gestión de errores al nivel de un arquitecto.