Tool Annotations Interest Group — Experimental Extensions

⚠️ Experimental — This repository is an incubation space for the Tool Annotations Interest Group. Contents are exploratory drafts intended to feed future Extensions Track SEPs (SEP-2133). They do not represent official MCP specifications or recommendations.

Charter: modelcontextprotocol.io/community/tool-annotations/charter Discord: #tool-annotations-ig Open work: Pull requests

Why split the work?

SEP-1913 (Trust and Sensitivity Annotations) bundles four concerns that have proven hard to evaluate as a single unit: a client-facing trust taxonomy, action-security metadata for tool I/O, a malicious-activity signal, and propagation rules across session boundaries.

The sponsor, @localden, asked the central question directly in review: the SEP "adds a few schema modifications and a thorny array-or-scalar polymorphism on enum fields. If the taxonomy turns out to be wrong, I worry that we can't remove it or easily modify it. Can we do a potential narrower first cut?" The subsequent design discussion converged on a layered answer: a small, stable annotation surface on the wire, with richer evidence kept out-of-band and referenced by a bounded pointer.

This repo follows that steer. Each concern becomes a separate experimental extension with its own reverse-DNS identifier, its own reference implementation, and its own path to a future Extensions Track SEP. Drafts can graduate independently — directly addressing the "narrower first cut" ask without throwing away the combinatoric value of the full set.

See docs/decisions.md for the decision record and docs/trust-model.md for the shared enforcement model.

Extensions

Identifier	Status	What it specifies	Reference implementation(s)
io.modelcontextprotocol/trust-annotations	Draft skeleton	Headline. A small, scheme-agnostic client-facing data-classification vocabulary (sensitive, untrusted) on result _meta, plus an optional evidenceRef pointer slot that carries richer payloads out-of-band.	Python SDK: kapil8811/mcp-trust-annotations (138-test suite, healthcare demo, LLM usability study).
io.modelcontextprotocol/action-metadata	Draft skeleton	inputMetadata / returnMetadata / outcome classifiers (incl. requires_review) on ToolAnnotations, describing where inputs go, where outputs originate, and what real-world effects a tool can cause.	Carries forward SEP-2061 (Action Security Metadata) by @rreichel3; reference impl per that proposal (read_drafts / list_inbox / send_email).
io.modelcontextprotocol/ifc-fides	Draft skeleton	A profile of the trust-annotations evidenceRef slot: type: "ifc.fides.v1" carrying an integrity + confidentiality label for deterministic information-flow control, following the FIDES paper (arXiv:2505.23643).	Emitter candidate: github-mcp-server (does not emit IFC labels today — closing that gap is the proof point).

Why FIDES is a profile, not the headline

An earlier sketch made information-flow control the top-level extension. That was the wrong cut: it bakes one academic model (an integrity × confidentiality lattice) into the namespace root and silently forecloses the other enforcement models reviewers raised — capability tokens, caller/tool cosigning, and sequence-shape audit records. As one reviewer put it, IFC "fits relatively well if you use annotations" — an endorsement of IFC as a profile, not as the wire root. Demoting it to a type value under trust-annotations's open-ended evidenceRef slot keeps the FIDES work first-class while leaving room for every other model to occupy the same slot.

Relationship to SEP-1913

SEP-1913 remains the canonical place to discuss the overall problem framing. This repo carves the schema-bearing parts of that proposal into independently shippable pieces. When an extension here is ready to graduate, an Extensions Track SEP can reference this repo as the prior art and the working implementation that SEP-2133 requires.

For the full per-SEP plan — what happens to SEP-1913, SEP-2061, SEP-1862 and others, and the SEP-2127 refactor precedent — see docs/sep-disposition.md.

Deliberately not carved here (see docs/open-questions.md):

• maliciousActivityHint — reviewer concerns are structural (it fires at tools/resolve before execution can produce evidence; a boolean is the wrong granularity for client UX; clients won't trust server self-attestation). If it returns, it is per-ContentBlock with spans, on a different clock. Parked on the SEP-1913 umbrella as a known cut item.
• Propagation rules — sensitivity escalation across session boundaries, and the sequence-shape gap (an annotation surface for "this was call N in a flagged sequence") remain open. Likely a future extension once the taxonomy and evidenceRef shape are stable.

Repository layout

This repo mirrors the structure of official extension repositories such as ext-auth:

specification/draft/<extension-name>.mdx   # one spec per extension
docs/                                       # decision log, open questions, related work
MAINTAINERS.md                              # IG facilitators

Contributing

See CONTRIBUTING.md. Substantive design discussion happens on PRs against the relevant specification/draft/*.mdx file, in the IG Discord, and (for cross-extension concerns) on SEP-1913.