experimental-ext-tool-annotations
Repository for the Tool Annotations Interest Group
by modelcontextprotocolMDX
Meet the team
See all 1 on GitHub →
Commit activity
Last 12 weeks · 22 commits
Community health
5 of 6 standards met
100
✓README✓License✓Contributing✓Code of Conduct○Issue Template✓PR Template
Recent PRs & issues
Active · 3 in progress · Last activity 3d ago
See all on GitHub →
Summary adapt SEP-1862 from a proposed core method into the negotiated extension add with per-tool opt-in through namespaced , modern per-request capability negotiation, and legacy initialize compatibility return a dedicated metadata-only result with complete argument-specific , while retaining as the authority for identity and schemas define conservative static fallback, validation, errors, trust boundaries, side-effect prohibition, TOCTOU limits, and no-cache semantics add TypeScript types and reference helpers, generated JSON Schema/type docs, examples, conformance tests, and CI Review concern addressed The result deliberately does not return a replacement . This prevents resolution from changing , , identity, descriptions, titles, or icons after the client has already selected arguments—the major concern raised during SEP-1862 review. Fallback Clients that do not negotiate the extension, skip resolution, or encounter a non-argument resolution failure continue using the core tool with its conservative static annotations. Invalid arguments are surfaced and must not be executed unchanged. Validation
Proposes a new experimental extension per CONTRIBUTING's "Proposing a new extension": display strings for tool calls & results, solving the dual-audience problem (compact encodings for the model, one legible line for the human) raised in modelcontextprotocol#930 and discussed in the #tool-annotations-ig thread "proposal for call-side string templates". What's in the draft: call-side under on , with branch-scoped templates inside / subschemas for one-tool-many-actions shapes result-side rendered on content-block (no templating; the server knows the outcome) normative rendering semantics: literal substitution only, for missing/non-scalar, raw fallback, first-matching-branch security implications centered on call-side omission: raw MUST stay reachable, unreferenced args SHOULD be visibly counted (const discriminators exempt), destructive confirmations SHOULD show raw Reference implementation (runs on stock Python SDK 2.x): https://github.com/maxiboch/soundboard Prior discussion: #tool-annotations-ig, with guidance from @SamMorrowDrums to target this repo as an Extensions Track proposal. Seeking a sponsor. Open questions are listed in the draft (branch-key spelling per SEP-2356, result-level vs per-block text, inner key naming).
The use cases (UC-1…UC-5) and cover what data is (HIPAA/PII/financial), where it goes (UC-4), and how it propagates (UC-2). They don't cover how long it lives or whether it can be erased. That's a separate axis. A host can know a result is PHI and still not know whether the tool retains it, for how long, or whether it can honor a deletion request. Under GDPR Art. 17 and the EU AI Act's deletion duties, that posture is its own policy input — it sits next to classification, not inside it. It also maps to two entries already in the Enterprise IG Pain Points catalog (modelcontextprotocol/modelcontextprotocol#2761, 3.3 and 7.1). This fits as a scheme behind the slot, the same place FIDES sits in #4 — not an extension. Candidate would carry: — declared bound, or none — whether persisted data can be erased on request, and the signal for it — none / session / durable A coarse hint can ride the wire next to ; the record stays out of band and recomputes in the #5 style. Lifecycle declarations touch the wire-hint vs host-resolved question open in #2, so the shape should follow whatever that lands on. A scheme is a claim, not proof that the tool honors it — same as the other schemes. Verification is a separate problem. I can write the emitter/consumer fixture for it in the #5 style, and a check in #1, if the direction is wanted.
Recent fixes
Documents the Tool Annotations Interest Group's proposed priorities for the next specification iteration: 1. Mature existing SEP transitions into experimental extensions, backed by SDK implementations and evidence of community demand. 2. Prepare the pre-flight request SEP for substantive review. 3. Separate human-facing content presentation from agent-facing content. 4. Gather, evaluate, and provide consolidated feedback on annotation SEP proposals. This is explicitly framed as non-binding interest-group guidance, not a formal roadmap or assertion of remit.
These are the worked emitter/consumer cases from the #2 thread, now as runnable fixtures so the shape can be checked rather than asserted. Everything reproduces from alone. The first family is the public-repo-with-private-subresource case. A world-public repository still serves things that are not world-readable, like a draft security advisory or the collaborator roster, so the emitter classifies the resource it returns rather than the container. The coarse boolean rides the wire and the four-level class sits out of band on a . A world-readable resource makes no claim, unknown or mixed provenance classifies rather than defaulting to public from a repo-level shortcut, and a content-block annotation may refine a result-level claim but never weaken it. The second exercises re-derivation for the and types: the small annotation stays on the wire while the rich record lives out of band, and a client holding the record recomputes the digest independently. Each is shown under both and , and the same record under the two envelopes produces two distinct, each-recomputable digests, so neither canonicalization reads as the default. recomputes every digest from the committed records, checks the per-resource classification rule, and checks the content-block union semantics. There are no third-party dependencies: the JCS and canonical CBOR encoders are pure-Python and self-test against the RFCs' own published vectors before any digest is trusted. The value profile is restricted to strings, arrays, string-keyed maps, booleans, null and non-negative integers, so the float and number-format edge cases stay out of scope until the spec pins them. I targeted this at the scaffold branch so the fixtures land next to the spec they validate. If you would rather merge #2 first, say the word and I will retarget to main.
Adds the ** experimental extension. / + outcome classifiers (including ) on : a declarative contract describing where a tool's inputs go, where its outputs originate, and what real-world effects it can cause. Origin Carries forward the field semantics from SEP-2061 (Action Security Metadata) by @rreichel3, which @localden closed on 2026-06-13 in favour of this extension. SEP-2061 is preserved as the origin and credit. @connor4312's review of SEP-1913 — "InputMetadata/ReturnMetadata seem okay. I _would_ be able to trust these as a client" — is the clearest external endorsement of this shape. Stacking Part of the three-PR split of SEP-1913 (see the base PR for the full plan): base — shared scaffolding + extension this PR — extension (independent of the FIDES scheme) FIDES scheme — , stacked on the base Targets the base branch; retarget to once the base merges.
Structured data for AI agents
Repository: modelcontextprotocol/experimental-ext-tool-annotations. Description: Repository for the Tool Annotations Interest Group Stars: 2, Forks: 5. Primary language: MDX. Languages: MDX (100%). Open PRs: 3, open issues: 1. Last activity: 3d ago. Community health: 100%. Top contributors: SamMorrowDrums.