Tool Annotations — MCP Research Results

Current Spec (Authoritative)

ToolAnnotations is part of the MCP spec since revision 2025-03-26 and has evolved through subsequent revisions. The current interface (as of 2025-11-25 / draft): ¹

interface ToolAnnotations {
  title?: string;
  readOnlyHint?: boolean;      // default: false
  destructiveHint?: boolean;   // default: true
  idempotentHint?: boolean;    // default: false
  openWorldHint?: boolean;     // default: true
}

All properties are hints — not guaranteed to faithfully describe tool behavior. Clients MUST consider tool annotations untrusted unless they come from trusted servers. ¹

Pull Requests

#185 - ToolAnnotations (Merged 2025-03-26) The foundational PR that introduced ToolAnnotations into the spec. Added readOnlyHint, destructiveHint, idempotentHint, openWorldHint, and trust/safety language. ²
#316 - Add documentation for ToolAnnotations (Merged 2025-04-11) Added documentation for the annotations introduced in #185. ³
#663 - Encourage title properties/usage (Merged 2025-06-13) Added title as a display annotation on tools and other primitives.
#1854 - Move taskHint to top-level Tool.execution.task (Merged 2025-11-20) Moved the taskHint annotation out of ToolAnnotations to a dedicated Tool.execution field.
#489 - Add stateless, streaming and async tool annotations (Closed 2025-09-24) Proposed adding stateless, streaming, and async annotations. Closed without merge.
#176 - [proposal] Add sensitive flag for the Tool (Closed 2025-03-14) Early proposal for a sensitive flag. Predated and was superseded by #185.
#616 - feat: Add comprehensive tool annotations for enhanced governance and UX (Closed 2025-12-15) Proposed adding aiProcessingHint, slowExecutionHint, resourceIntensiveHint, sensitiveDataHint, privilegedAccessHint, and reversibleHint. Closed — moved to SEP-1984. ⁴ ⁵
#1984 - SEP-1984: Comprehensive Tool Annotations for Enhanced Governance and UX (Open) SEP version of #616 proposing extended governance/UX annotations.
#1938 - SEP-1938: agencyHint tool annotation (Open) Proposes an agencyHint annotation to indicate whether a tool possesses agentic capabilities (reasoning, planning, or autonomous decision-making). Migrated from #1792.
#1913 - SEP-1913: Trust and Sensitivity Annotations (Open) Proposes trust and sensitivity-related annotations.

Issues

#1792 - [SEP-1792] Proposal: Add agencyHint tool annotation (Open) Original SEP proposal for agencyHint, later migrated to PR #1938.
#1561 - SEP-1561: Addition of unsafeOutputHint Tool Annotation (Open) Proposes unsafeOutputHint to flag tools whose output may contain unsafe content.
#1560 - SEP-1560: Addition of secretHint Tool Annotation (Open) Proposes secretHint for tools that handle secret/credential data.
#1487 - SEP-1487: Addition of trustedHint Tool Annotation (Open) Proposes trustedHint to indicate whether a tool's output can be trusted.
#848 - Flexible tool annotations (Closed) Discussion about making annotations more extensible.
#1075 - SEP-1075: Security Annotations for MCP Tool Definitions (Closed)
#711 - [SPEC] Annotations for MCP Requests and Responses (security/privacy) (Open) Broader proposal for annotations on requests/responses, not just tool definitions.

Discussions

Primitive Groups for Tools, Resources, Prompts — discusses grouping and annotation of tools at a higher level.

Notable Maintainer Quotes

"Sorry, I have some worries here, particularly around the trust model. I do think adding more expressivity here will be a good thing, but we need to be careful not to promise something that will actually be broken in practice." ⁶ — @jspahrsummers

"I think the information itself, if it could be trusted, would be very useful, but I wonder how a client makes use of this flag knowing that it's not trustable. I guess that maybe degrades to, 'Clients should apply a high scrutiny bar to all untrusted servers and ignore most of these annotations, until the user tells them not to.'" ⁷ — @jspahrsummers

"100%, actually I think 'Clients should ignore annotations from untrusted servers' applies to all annotations, even title - but especially the ones that describe operational properties." ⁸ — @bhosmer-ant

"These would require a SEP. I think the general question here is about the taxonomy of hints." ⁴ — @dsp-ant

"This change would now require an SEP. Your summary says 'These annotations enable better governance policies, security controls, resource management, and user experience enhancements', but it's not clear to me exactly how a client would behave differently when presented with these annotations, so you may want to discuss that in your Rationale. Also, depending on how specialized a client must be to benefit from these annotations, there is an argument for implementing them as (unofficial) fields in Tool._meta instead." ⁵ — @jonathanhefner

Key Insights

ToolAnnotations are established spec — introduced in 2025-03-26 with readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The title property was added later.
Trust is the central design tension — the core debate in #185 was about what value annotations provide when they can't be trusted from untrusted servers. The resolution: explicitly label everything as "hints" and require clients to treat them as untrusted by default.
Booleans won over variant types — the original PR experimented with variant/enum types for destructive/idempotent but settled on simple booleans for extensibility and simplicity.
Active expansion proposals — several open SEPs propose new annotations (agencyHint, secretHint, unsafeOutputHint, trustedHint, comprehensive governance annotations), but none have been merged yet. The bar for adding new annotations is high — each requires a formal SEP.
taskHint was moved out — the taskHint annotation was relocated from ToolAnnotations to Tool.execution.task (#1854), showing a pattern of separating execution concerns from metadata hints.
Extensibility has formalized since the original design — In March 2025, @jspahrsummers noted that "all objects in the MCP spec are intentionally open-ended" ⁹, but the spec has since introduced structured extensibility mechanisms. Tool._meta with namespaced keys (e.g., com.example/my-field) is the preferred way to attach custom metadata ⁵ ¹⁰, and the Extensions framework (SEP-2133) provides a formal governance path for protocol-level additions ¹¹. Issue #1898 argues that types like ToolAnnotations should explicitly set additionalProperties: false, with _meta as the designated extension point rather than arbitrary top-level properties ¹².

olaservo/tool-annotations-research.md

Select an option

No results found