Tool annotations contain only MCP hints

Tool annotations are a closed set of behavior hints. Resource annotation fields such as audience and priority do not belong here, and custom keys are not allowed. Remove those properties; author-reviewed server metadata can instead use the Tool’s _meta where the protocol version defines it.

Requirement

A Tool annotations object contains only title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.

Details

Rule ID: mcp.tool-annotations.members
Owner: mcp
Surface: ToolAnnotations
Kind: structural
Requirement level: must
Document schema locations: #/$defs/toolAnnotations
Status: internal · Enforcement: internal

Protocol version applicability

2024-11-05	2025-03-26	2025-06-18	2025-11-25	2026-07-28
not-applicable	applies	applies	applies	applies

Required by

• MCP Description 0.9.0, Section 9.6
  • 9. Tools: req-tool-annotations-closed
  • 9. Tools: req-tool-annotations-fields

Based on

• Tier 1 — MCP schema.ts and normative specification text: MCP 2025-03-26 to 2026-07-28 schema.ts, interface ToolAnnotations (no index signature)
  • validation/mcp-schemas/2025-03-26/schema.ts#L727-L779
  • validation/mcp-schemas/2025-06-18/schema.ts#L869-L923
  • validation/mcp-schemas/2025-11-25/schema.ts#L1168-L1222
  • validation/mcp-schemas/2026-07-28/schema.ts#L1900-L1954

Notes

Tool annotations are not available in MCP 2024-11-05; that boundary is checked separately.

Examples

Valid example

Source: expected-valid/distinct-tool-and-resource-annotations.json · Selected: /tools/0/annotations

{
  "title": "Inspect",
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false
}

Invalid example

Source: expected-invalid/tool-annotations-unknown-property.json · Selected: /tools/0/annotations

{
  "readOnlyHint": true,
  "audience": [
    "user"
  ]
}

Rule Source Code

annotations.yaml at immutable tag v0.9.0-rc.3.