Errores de herramientas visibles para el modelo
Devuelva errores que la IA pueda leer y solucionar.
Errores de herramientas visibles para el modelo es una lección gratuita de MCP Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de MCP Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de MCP Academy incluye 4 lecciones en total.
Los errores son simplemente más contexto
Cuando una herramienta falla, la IA no se bloquea. Simplemente lee su error como contexto y decide qué hacer a continuación, igual que con cualquier resultado.
Un buen error permite actuar
Escriba el error pensando en un lector que pueda actuar en consecuencia. «Ciudad no encontrada» es mejor que «Exception», porque el modelo puede pedir al usuario que corrija la ciudad.
Devuelva una cadena de error
El patrón más sencillo consiste en devolver una cadena de mensaje clara cuando algo va mal, para que el modelo lea exactamente qué ha fallado.
@mcp.tool()
def get_user(uid: int) -> str:
if uid < 1:
return "Error: uid must be positive."Genere una excepción para indicar un error de la herramienta
También puede raise una excepción normal de Python. FastMCP la captura e informa de un error de herramienta al modelo, no de un fallo del servidor.
@mcp.tool()
def divide(a: float, b: float) -> float:
if b == 0:
raise ValueError("b cannot be zero")
return a / bisError marca el resultado
Internamente, una llamada fallida a una herramienta devuelve contenido con isError establecido en true. Ese indicador informa al cliente de que el resultado describe un fallo.
El modelo puede recuperarse
Un error legible permite a la IA reintentar con una entrada mejor o explicar el problema al usuario, convirtiendo un fallo en un siguiente paso útil. 🔁
Indique qué ocurrió y por qué
Los buenos errores indican qué falló y por qué. «Falta el archivo: report.csv» es mucho más útil para el modelo que un simple «No encontrado».
Sugiera una solución
Cuando sea posible, incluya la solución dentro del error. «La fecha debe tener el formato YYYY-MM-DD» permite que el modelo se corrija en la siguiente llamada.
if not iso_date:
raise ValueError("Date must be in YYYY-MM-DD format")No revele detalles internos
Los errores llegan al modelo y, a menudo, también al usuario, así que mantenga fuera del mensaje los secretos, las trazas de pila sin procesar y las cadenas de conexión.
Valide y genere el error pronto
Compruebe primero los argumentos y devuelva el error antes de realizar el trabajo real. Fallar pronto mantiene su herramienta predecible y fácil de comprender.
Los errores forman parte del contrato
Trate los fallos como una salida diseñada. Una herramienta que indica sus posibles errores es tan útil para el modelo como una que documenta sus resultados correctos.
Comprobación rápida
¿Por qué debe escribir los errores de las herramientas como mensajes claros y legibles?
Resumen
Los errores de las herramientas son contexto que el modelo lee: hágalos claros, indique qué ocurrió y por qué, sugiera una solución y nunca revele detalles internos. ✅
Aprende Python con un tutor de IA — gratis
Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.
- Cursos
- 30
- Lecciones
- 120
Preguntas frecuentes
¿La lección «Errores de herramientas visibles para el modelo» es gratis?
Sí — el texto completo de «Errores de herramientas visibles para el modelo» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de MCP Academy, actualiza a CoddyKit PRO. El curso de MCP Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Errores de herramientas visibles para el modelo»?
Devuelva errores que la IA pueda leer y solucionar. Practicas MCP Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar MCP Academy?
No se requiere experiencia previa. MCP Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.
¿Cuánto tiempo toma la lección «Errores de herramientas visibles para el modelo»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de MCP Academy?
Sí. Cada lección de MCP Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Errores de herramientas visibles para el modelo
- Errores del protocolo frente a fallos de herramientas
- Validar las entradas antes de actuar
- Fallar de forma segura, sin bloqueos