MCP Tool Annotations: Adding Metadata and Context to Your AI Tools
Introduction
As artificial intelligence (AI) applications become more sophisticated and interact with increasingly complex external systems, better tool metadata becomes crucial. Although the Model Context Protocol (MCP) was introduced only a couple of months ago, it is very much alive and evolving quickly. One of its latest advancements is the introduction of MCP Tool annotations.
Annotations provide a layer of metadata that enhances the interaction between AI models and external tools, making it easier for AI models, clients, and users to understand how these tools behave and what they can do.
In this post, I’ll walk through what Tool annotations are, why they matter, and give a few examples based on the Kubernetes MCP Server.
What are MCP Tool Annotations?
MCP Tool annotations are specialized metadata that you can attach to your MCP tools to communicate their behavior characteristics to the MCP client. Think of them as labels that describe what your tool does and how it behaves, similar to how you might label physical tools in a workshop.
These annotations serve as advisory hints that help client applications make informed decisions about tool usage, display appropriate user interfaces, and implement safety controls.
Note
Annotations are hints provided by the MCP server and are informational only. They do not enforce any behavior or restrictions on the tool itself. Don't blindly trust them, as they are not guaranteed to be accurate or complete.
Why are MCP Tool Annotations Important?
MCP Tool annotations allow servers to express the behavior of their tools in a standardized way. By using annotations, tools become self-descriptive, which brings several benefits:
- Enhanced User Experience: Annotations enable client applications to present tools with user-friendly titles and descriptions, making it easier for users to understand what each tool does.
- Improved Safety and Control: Annotations help implement appropriate safety measures and user confirmations by indicating whether tools are destructive or read-only.
- Better Tool Discovery: Annotations allow clients to filter and discover tools based on their characteristics, making it easier to find the right tool for a specific task.
- Consistency Across Tools: Annotations provide a consistent way to describe tool behavior, making it easier for developers to understand and use different tools across various MCP servers.
Available MCP Tool Annotations
The MCP specification defines several standard annotations that cover the most common tool behavior patterns:
| Annotation | Type | Description |
|---|---|---|
| title | string | A human-readable title for the tool, useful for displaying in user interfaces. This is particularly useful when your tool's function name isn't descriptive enough for end users. |
| readOnlyHint | boolean | Indicates whether the tool only reads data without making any modifications. This is crucial for tools that query information versus those that change system state. |
| destructiveHint | boolean | For non-read-only tools, this signals whether the changes made are destructive or reversible. This helps client applications implement appropriate warnings and confirmations. |
| idempotentHint | boolean | Specifies whether repeated identical calls have the same effect as a single call. This is important for understanding whether a tool can be safely retried. |
| openWorldHint | boolean | Indicates whether the tool interacts with external systems beyond the local environment. This helps in understanding the tool's scope and potential dependencies. |
A Real-World Example: Kubernetes MCP Server
Let's look at how these annotations can be applied in a real-world scenario using the Kubernetes MCP Server as an example.
The Kubernetes MCP Server provides a set of tools to interact with Kubernetes clusters, and it uses MCP Tool annotations to enhance the user experience.
For instance, consider the following tool definition for the helm_list function:
{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},In this example, the tool helm_list is defined with several annotations:
- Title: "Helm: List" provides a clear and concise name for the tool to be presented to end users.
- Read-Only Hint:
trueindicates that this tool only reads data from the Kubernetes cluster without making any changes. - Destructive Hint: Marked as
falsesince this function lists Helm releases without modifying anything. By indicating that this tool does not perform any damaging actions, client applications can avoid unnecessary warnings. - Open World Hint:
trueindicates that this tool interacts with an external system (the Kubernetes cluster), which is important for understanding its scope and potential dependencies.
For more examples, check the Kubernetes MCP Server mcp package which contains many other tools with various annotations.
Best Practices for MCP Tool Annotations
When implementing tool annotations, consider the following guidelines:
- Be Accurate: Ensure that the annotations truthfully reflect the tool's behavior. Misleading annotations can lead to poor user experiences or safety issues.
- Think about Users: Use clear and descriptive titles and descriptions that help users (as opposed to developers) understand the tool's purpose. Avoid technical jargon that may confuse end users.
- Consider Safety Implications: Be conservative with destructive and read-only hints. When in doubt, err on the side of caution.
- Keep Annotations Up to Date: As tools evolve, ensure that their annotations are updated to reflect any changes in behavior or functionality.
- Use Annotations Consistently: Apply annotations uniformly across all tools in your MCP server to maintain a consistent user experience.
Conclusion
MCP Tool annotations provide a powerful way to enhance your AI tools with essential metadata that improves user experience and system safety. By thoughtfully applying these annotations to your tools, you create more robust and user-friendly AI integrations.
In my Kubernetes MCP Server, annotations help users understand the difference between safe query operations and potentially destructive cluster modifications, making the tool more trustworthy and easier to use in production environments.
As you build your own MCP servers, remember that annotations are about communication: they help bridge the gap between what your tool does technically and what users need to know to use it effectively.
You Might Also Like
