MCP Tool Annotations: Añadiendo Metadatos y Contexto a Tus Herramientas de IA

2025-05-27 en Inteligencia Artificial etiquetado LLM / AI Agent / Model Context Protocol (MCP) / Kubernetes por Marc Nuri | Última actualización: 2025-05-27

English version

Introducción

A medida que las aplicaciones de inteligencia artificial (IA) se vuelven más sofisticadas e interactúan con sistemas externos cada vez más complejos, mejorar los metadatos de las herramientas se vuelve crucial. Aunque el Model Context Protocol (MCP) fue introducido hace solo unos meses, está muy vivo y evolucionando rápidamente. Uno de sus últimos avances es la introducción de anotaciones de herramientas MCP.

Las anotaciones proporcionan una capa de metadatos que mejora la interacción entre los modelos de IA y las herramientas externas, facilitando a los modelos de IA, clientes y usuarios entender cómo se comportan estas herramientas y qué pueden hacer.

En este artículo, mostraré qué son las anotaciones de herramientas MCP, por qué son importantes y daré algunos ejemplos basados en el Kubernetes MCP Server.

¿Qué son las Anotaciones de Herramientas MCP?

Las anotaciones de herramientas MCP son metadatos especializados que puedes adjuntar a tus herramientas MCP para comunicar sus características y comportamiento al cliente MCP y sus usuarios. Piensa en ellas como etiquetas que describen lo que hace tu herramienta y cómo se comporta, similar a cómo podrías etiquetar herramientas físicas en un taller.

Estas anotaciones sirven como pistas informativas que ayudan a las aplicaciones cliente a tomar decisiones informadas sobre el uso de herramientas, mostrar interfaces de usuario apropiadas e implementar controles de seguridad.

Nota

Las anotaciones son pistas proporcionadas por el servidor MCP y son informativas únicamente. No imponen ningún comportamiento o restricción en la herramienta misma. No confíes ciegamente en ellas, ya que no se garantiza que sean precisas o completas.

¿Por qué son Importantes las Anotaciones de Herramientas MCP?

Las anotaciones de herramientas MCP permiten a los servidores expresar el comportamiento de sus herramientas de manera estandarizada. Al usar anotaciones, las herramientas se vuelven autodescriptivas, lo que aporta varias ventajas:

Mejora de la Experiencia del Usuario: Las anotaciones permiten a las aplicaciones cliente presentar herramientas con títulos y descripciones amigables para el usuario, facilitando la comprensión de lo que hace cada herramienta.
Mejora de la Seguridad y el Control: Las anotaciones ayudan a implementar medidas de seguridad apropiadas y confirmaciones de usuario al indicar si las herramientas son destructivas o de solo lectura.
Mejor Descubrimiento de Herramientas: Las anotaciones permiten a los clientes filtrar y descubrir herramientas según sus características, facilitando la búsqueda de la herramienta más adecuada para una tarea específica.
Consistencia entre Herramientas: Las anotaciones proporcionan una forma consistente de describir el comportamiento de las herramientas, facilitando a los desarrolladores entender y usar diferentes herramientas en varios servidores MCP.

Anotaciones Disponibles

La especificación MCP define varias anotaciones estándar que cubren los patrones de comportamiento más comunes de las herramientas:

Anotación	Tipo	Descripción
title	`string`	Un título comprensible para humanos, útil para mostrar en interfaces de usuario. Esto es particularmente útil cuando el nombre de la función de tu herramienta no es lo suficientemente descriptivo para los usuarios finales.
readOnlyHint	`boolean`	Indica si la herramienta solo lee datos sin realizar modificaciones. Esto es crucial para herramientas que consultan información frente a aquellas que cambian el estado del sistema.
destructiveHint	`boolean`	Para herramientas que no son de solo lectura, esto señala si los cambios realizados son destructivos o reversibles. Esto ayuda a las aplicaciones cliente a implementar advertencias y confirmaciones apropiadas.
idempotentHint	`boolean`	Especifica si multiples llamadas idénticas tienen el mismo efecto que una sola llamada. Esto es importante para entender si una herramienta puede ser reintentada de manera segura.
openWorldHint	`boolean`	Indica si la herramienta interactúa con sistemas externos más allá del entorno local. Esto ayuda a entender el alcance de la herramienta y sus posibles dependencias.

Caso de uso: Kubernetes MCP Server

Veamos cómo se pueden aplicar estas anotaciones en un escenario del mundo real utilizando el Kubernetes MCP Server como ejemplo.

Kubernetes MCP Server es un servidor MCP que proporciona un conjunto de herramientas para interactuar con clústeres de Kubernetes, y utiliza anotaciones de herramientas MCP para mejorar la experiencia de usuario.

Por ejemplo, considera la siguiente definición de herramienta para la función helm_list:

{mcp.NewTool("helm_list",
	mcp.WithDescription("List all the Helm releases in the current or provided namespace (or in all namespaces if specified)"),
	mcp.WithString("namespace", mcp.Description("Namespace to list Helm releases from (Optional, all namespaces if not provided)")),
	mcp.WithBoolean("all_namespaces", mcp.Description("If true, lists all Helm releases in all namespaces ignoring the namespace argument (Optional)")),
	// Tool annotations
	mcp.WithTitleAnnotation("Helm: List"),
	mcp.WithReadOnlyHintAnnotation(true),
	mcp.WithDestructiveHintAnnotation(false),
	mcp.WithOpenWorldHintAnnotation(true),
), s.helmList},

En este ejemplo, la herramienta helm_list se define con varias anotaciones:

Título: "Helm: List" proporciona un nombre claro y conciso para la herramienta que se presentará a los usuarios finales.
Read-Only Hint: true indica que esta herramienta solo lee datos del clúster de Kubernetes sin realizar ningún cambio.
Destructive Hint: Marcada como false ya que esta función lista las Releases de Helm sin modificar nada. Al indicar que esta herramienta no realiza acciones destructivas, las aplicaciones cliente pueden evitar advertencias innecesarias.
Open World Hint: true indica que esta herramienta interactúa con un sistema externo (el clúster de Kubernetes), lo cual es importante para entender su alcance y posibles dependencias.

Para más ejemplos, consulta el paquete mcp del Kubernetes MCP Server que contiene muchas otras herramientas con diversas anotaciones.

Buenas Prácticas para las Anotaciones de Herramientas MCP

Cuando implementes anotaciones de herramientas, considera las siguientes pautas:

Sé Preciso: Asegúrate de que las anotaciones reflejen con precisión el comportamiento de la herramienta. Las anotaciones engañosas pueden llevar a malas experiencias de usuario o problemas de seguridad.
Piensa en los Usuarios: Utiliza títulos y descripciones claras y descriptivas que ayuden a los usuarios (en lugar de a los desarrolladores) a entender el propósito de la herramienta. Evita la jerga técnica que pueda confundir a los usuarios finales.
Considera las Implicaciones de Seguridad: Sé conservador con las anotaciones destructivas y de solo lectura. Cuando tengas dudas, opta por la precaución.
Mantén las Anotaciones Actualizadas: A medida que las herramientas evolucionan, asegúrate de que sus anotaciones se actualicen para reflejar cualquier cambio en el comportamiento o la funcionalidad.
Usa Anotaciones de Manera Consistente: Aplica anotaciones de manera uniforme en todas las herramientas de tu servidor MCP para mantener una experiencia de usuario coherente.

Conclusión

Las anotaciones de herramientas MCP proporcionan una forma potente de mejorar tus herramientas de IA con metadatos esenciales que mejoran la experiencia del usuario y la seguridad del sistema. Al aplicar estas anotaciones de manera reflexiva a tus herramientas, creas integraciones de IA más robustas y fáciles de usar.

En mi servidor Kubernetes MCP, las anotaciones ayudan a los usuarios a entender la diferencia entre operaciones de consulta seguras y modificaciones potencialmente destructivas del clúster, haciendo que la herramienta sea más confiable y fácil de usar en entornos de producción.

A medida que construyes tus propios servidores MCP, recuerda que el propósito de las anotaciones es la comunicación: ayudan a cerrar la brecha entre lo que hace tu herramienta técnicamente y lo que los usuarios necesitan saber para usarla de manera efectiva.

Entradas Recientes

Categorías

Archivos