Tool Annotations Charter

Documentation Index

Fetch the complete documentation index at: https://modelcontextprotocol.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Group Type

Interest Group

​

Mission Statement

The Tool Annotations Interest Group explores the role of tool annotations in enabling safe, usable agentic systems across the MCP ecosystem. Today, six independent SEPs propose annotation changes, each solving real problems but lacking the coherent, cross-cutting perspective that a dedicated group can bring. The IG gathers use cases from server and client authors, evaluates existing and proposed annotations, and considers the long-term future of the annotation model, including whether runtime annotations, tool response annotations, and other extensions belong in the protocol.

​

Scope

​

In Scope

• Evaluation of existing annotations: Assess whether the current set of tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) adequately serves server and client authors
• Discussion of proposed annotations: Review and provide feedback on SEPs proposing new or modified tool annotations (trust/sensitivity, agency, model preferences, and others)
• Future of the annotation model: Explore whether runtime annotations, tool response annotations, or structural changes to the annotation system are worth adding to the protocol
• Use-case gathering: Collect real-world use cases from server authors, client authors, and host applications to ground annotation decisions in practical needs
• Problem statements and recommendations: Produce recommendations for Working Groups or SEP authors on annotation design, coherence, and prioritization

​

Out of Scope

• Binding specification changes: The IG produces recommendations, not binding decisions; specification changes are made through the SEP process
• Implementation work: Building SDK features or reference implementations (may be explored in the experimental repo but is not the IG’s primary purpose)
• Non-annotation tool changes: Changes to tool discovery, invocation, or lifecycle that do not relate to annotations
• Resource annotations: While related, resource-level annotation work is tracked separately unless it directly intersects with tool annotation design

​

Related Groups

• Security IG - Trust and sensitivity annotations (SEP-1913) span both groups’ interests
• Skills Over MCP WG - Skill-level metadata may interact with tool annotations for discovery and filtering

​

Leadership

​

Membership

​

Operations

Discord: #tool-annotations-ig

​

Discussion Topics

The following SEPs and themes form the IG’s initial discussion agenda. This list is not exhaustive and will evolve as the group identifies new areas of interest.

​

Active SEPs Under Discussion

​

Open Questions

• Should runtime annotations (annotations that change between invocations) be added to the protocol?
• Are additional static annotations worth standardizing, and which serve both server and client authors?
• Should tool response annotations be added to the protocol?
• How should annotations interact with trust, security, and human-in-the-loop requirements?
• What is the right level of granularity - a few well-defined hints vs. a richer, extensible vocabulary?

​

Resources

• Tool Annotations as Risk Vocabulary - blog post framing the motivation for this work
• Experimental repo - repository for the Tool Annotations Interest Group

​

Changelog