What Tool Annotations Are

Tool annotations shipped in the 2025-03-26 spec revision. The current ToolAnnotations interface looks like this:

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

Every property is a hint. The spec is explicit about this: annotations are not guaranteed to faithfully describe tool behavior, and clients must treat them as untrusted unless they come from a trusted server.

These four boolean hints give clients a basic risk vocabulary:

• readOnlyHint: Does the tool modify its environment?
• destructiveHint: If it does modify things, is the change destructive (as opposed to additive)?
• idempotentHint: Can you safely call it again with the same arguments?
• openWorldHint: Does the tool interact with an open world of external entities, or is its domain closed?

The first three hints mostly answer a preflight question: should the client ask for confirmation before calling this tool? openWorldHint is different. It’s about where the tool reaches and what its output might carry back, which matters after the call as much as before. It’s also the hint most sensitive to deployment context. “External” might mean anything outside a corporate network or anything beyond the local machine, depending on where the server runs. The safest posture is to treat anything a tool considers external as a potential source of untrusted content.

The defaults are deliberately cautious: a tool with no annotations is assumed to be non-read-only, potentially destructive, non-idempotent, and open-world. The spec assumes the worst until told otherwise. Making annotations optional kept the barrier to entry low for server authors, but it also means coverage is uneven. Many servers ship without them, and clients vary in how strictly they honor the pessimistic defaults. Closing that gap is part of what the current wave of SEPs is trying to do.

How We Got Here

The original proposal discussion surfaced a question that still shapes every annotation proposal today: what value do hints provide when they can’t be trusted? MCP co-creator Justin Spahr-Summers raised it directly during review:

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.

Basil Hosmer pushed the point further, arguing that clients should ignore annotations from untrusted servers entirely:

“Clients should ignore annotations from untrusted servers” applies to all annotations, even title — but especially the ones that describe operational properties.

The spec landed on a compromise: call everything a hint, require clients to treat hints as untrusted by default, and leave it to each client to decide how much weight to give them based on what it knows about the server.

The interface has stayed small since then, and that’s been intentional. title went in because it’s just a display name with no trust implications. taskHint was proposed as an annotation but landed as Tool.execution instead, on the grounds that execution metadata isn’t really a behavioral hint. Earlier takes on stateless, streaming, and async annotations and security annotations are worth knowing about too, since the same concerns show up again in the SEPs open today.

What’s Open Now

Five SEPs currently propose new annotations or closely related capabilities:

The trust and sensitivity work is co-authored by GitHub and OpenAI based on gaps they hit running MCP in production. A Tool Annotations Interest Group is forming to work through these alongside related proposals like tool resolution and preflight checks. Reviewing each one in isolation makes it easy to miss how a given annotation interacts with others, and it’s those interactions that determine how risky a tool actually is in a given session.

The Lethal Trifecta: Why Combinations Matter

Simon Willison’s lethal trifecta names three capabilities that, when combined, create the conditions for data theft: access to private data, exposure to untrusted content, and the ability to externally communicate. The attack is simple: LLMs follow instructions in content, and they can’t reliably tell a user’s instructions apart from ones an attacker embedded in a web page, email, or calendar event. If the agent has all three capabilities, an attacker who controls one piece of untrusted content can trick the model into reading private data and sending it out.

Researchers have demonstrated this using a malicious Google Calendar event description, an MCP calendar server, and a local code execution tool. The code execution tool is the linchpin in that chain — any agent with unrestrained shell access sits one injected instruction away from exfiltration, and that’s true whether the tool arrived via MCP or was built into the host. What MCP adds is the ease of assembling the chain: users routinely combine tools from several servers in one session, so the risk profile is a property of the session, not of any single server.

One commenter on Willison’s newsletter connected this directly to tool annotations:

If the current state is tainted, block (or require explicit human approval for) any action with exfiltration potential… This also makes MCP’s mix-and-match story extra risky unless tools carry metadata like: reads_private_data / sees_untrusted_content / can_exfiltrate — and the runtime enforces ’never allow all three in a single tainted execution path.'

Several of the open SEPs are trying to define that kind of metadata so a client can spot when a session has all three legs of the trifecta available.

What Annotations Can Do

Drive confirmation prompts. A tool marked readOnlyHint: true from a trusted server might be auto-approved, while destructiveHint: true gets a confirmation step. A user asks their agent to clean up old files, the agent reaches for delete_file, and the client shows a dialog listing what’s about to be deleted before anything happens. This is the most common use of annotations today.

Enable graduated trust. An enterprise running its own internal MCP servers behind auth has a very different trust relationship than someone installing a random server off the internet. Annotations from the first can drive policy; from the second they’re informational at best. In practice most clients still treat installation itself as the trust signal and don’t distinguish further, so this is more of a design opportunity than a widely shipped feature.

Improve UX. title is just a display name. Annotations that help users understand what tools do without running them are useful regardless of trust. This is largely unexploited today: no MCP client lets users filter tools by annotation values, and none surface annotations as context in approval prompts. GitHub’s read-only mode is the closest production analog, enabled by about 17% of users.

Feed policy engines. Annotations can be one input among several into a policy engine enforcing rules like “no destructive tools without approval” or “open-world tools are blocked in sessions that have accessed private data.” The hints don’t need to be perfectly trustworthy if the engine cross-references other signals.

Adoption across all of these is uneven, partly because MCP users split into two camps. Developers building autonomous agents treat confirmations as friction and lean on sandboxing instead. Enterprise adopters want more annotations than currently exist. One camp barely notices annotations, the other wants a much richer vocabulary.

What Annotations Can’t Do

They don’t make the model resist prompt injection. Annotations are static metadata on a tool definition; nothing in them tells the model to ignore malicious instructions it reads from a calendar event. What an annotation like seesUntrustedData could do is let the client treat the session as tainted once that tool runs and tighten approvals from then on — a defense at the host layer, not inside the model.

An untrusted server can lie. A server can claim readOnlyHint: true and delete your files anyway. This is why the spec says clients must treat annotations from untrusted servers as untrusted.

They aren’t enforcement. If you need a guarantee that a tool can’t exfiltrate data, that’s a job for network controls or sandboxing, not a boolean hint. We made the same point about server instructions: don’t rely on soft signals for things that need to be hard guarantees.

A tool’s risk depends on what else is in the session. search_emails isn’t safe or dangerous on its own; it depends on what other tools the agent has. Annotations on one tool can’t tell you that.

Questions for Evaluating New Annotations

As a starting point for the Interest Group, we’re putting forward a tentative set of questions to ask of each annotation proposal. These will likely change as the group works through the open SEPs.

1. What client behavior does it enable?

Maintainer Jonathan Hefner put this directly on an early draft of what became the governance/UX annotations proposal:

It’s not clear to me exactly how a client would behave differently when presented with these annotations.

If there’s no concrete client action that changes based on the annotation, it probably doesn’t belong in the protocol. Each of the existing hints maps to at least one decision a client can make:

2. Does it need trust to be useful?

title is useful even from an untrusted server; worst case you show a bad display name. readOnlyHint from an untrusted server isn’t actionable, because the decision it informs — whether to skip a confirmation — only makes sense if you believe the hint. Proposals should say where they fall on that spectrum, since it determines which clients can actually use them.

3. Could _meta handle it instead?

Tools already have _meta, which accepts namespaced keys like com.example/my-field for exactly this kind of metadata. If an annotation only matters to one deployment style where the same organization runs both the server and the client, _meta is a reasonable home for it. It’s also a good way to prove out an idea before writing a SEP: ship a namespaced field, see how it holds up in production, and come back with a proposal backed by actual usage instead of a design doc. What _meta can’t do is drive behavior in off-the-shelf clients — those won’t read a key they’ve never heard of, so anything aimed at ecosystem-wide UX still needs a real annotation.

4. Does it help reason about combinations?

Annotations that help a client understand what happens when tools are used together are worth more than ones that only describe a tool in isolation. openWorldHint already hints at this: a client could use it to notice that a session mixes closed-world data access tools with open-world communication tools.

5. Is it a hint or a contract?

Hints inform decisions; contracts enforce them. If a proposal’s value depends on the annotation being true, it’s asking for a contract, and the right place for that is the authorization layer, the transport, or the runtime rather than ToolAnnotations. Hints work best when they’re still useful even if some servers get them wrong.

Where This Is Heading

The Tool Annotations Interest Group includes participants from Microsoft, OpenAI, AWS, Cloudflare, and Anthropic, among others. These are companies that build both MCP hosts and MCP servers at scale, so they sit on both sides of the annotation contract: they need annotations expressive enough to surface risk to their users, and they need to author annotations that other clients will actually honor. Among the questions on the group’s agenda are whether annotations belong on tool responses as well as tool definitions, and whether any annotations should be evaluated at runtime rather than declared statically.

In the meantime, the existing annotations are worth using. If you’re writing a server, set readOnlyHint: true on read-only tools, destructiveHint: false on additive operations, and openWorldHint: false on closed-domain tools. If you’re writing a client, treat annotations from untrusted servers as informational and lean on them for UX, but keep your actual safety guarantees in deterministic controls. And if you’re thinking of proposing a new annotation, the questions above are a good place to start shaping it.

Get Involved

The Tool Annotations Interest Group is forming now. If you’re interested in contributing:

• Review the open SEPs linked above and leave feedback
• Join the conversation in #tool-annotations-ig on the MCP Contributors Discord

Acknowledgements

This post draws on discussions with the MCP community, particularly the contributors involved in the Tool Annotations Interest Group proposal, including Sam Morrow (GitHub), Robert Reichel (OpenAI), Den Delimarsky (Anthropic), Nick Cooper (OpenAI), Connor Peet (Microsoft), and Luca Chang (AWS).

This is especially important in a world where clients and servers don’t have a pre-existing relationship - we can’t assume that we will always know which MCP clients will connect to which MCP servers. This design highlights two challenges that need to be addressed:

• Operational issues with managing client IDs via Dynamic Client Registration (DCR)
• Preventing client impersonation

If you’re already familiar with OAuth and the current state of client registration in MCP, skip to Two Distinct Challenges in MCP Client Registration.

Background on OAuth

A protected MCP server that implements OAuth 2.1 should allow a user to grant a client access to itself and prevent attempts to trick the user into granting access to a client they didn’t intend to use via phishing.

The authorization flow can be best described by looking at this sequence diagram:

  sequenceDiagram
   participant Client
   participant User
   participant AuthServer as Authorization Server
   participant Resource as Resource Server

   Client->>User: 1. Redirect to authorization server
   User->>AuthServer: Navigate to auth URL
   AuthServer->>User: 2. Display consent screen
   User->>AuthServer: Approve access
   AuthServer->>Client: 3. Redirect with authorization code
   Client->>AuthServer: 4. Exchange code for access token
   AuthServer-->>Client: Access token (saved)
   Client->>Resource: 5. Request with access token
   Resource-->>Client: Protected resource

This flow requires a few steps to be performed to acquire an access token:

1. The client directs the user to an authorization UI provided by the authorization server
2. The authorization server displays a consent screen to the user
3. User approves client access and the authorization server redirects the user back to the client with an access code
4. Client exchanges the access code for a set of tokens, which are cached locally
5. Client uses the access token to access the MCP server

To be able to initiate this flow, however, the authorization server first needs some basic information about the client that is kicking off the authorization process:

1. Client name: Human readable text to display in the consent screen to help the user decide whether they want to grant access.
2. Redirect URL: The destination to send the authorization code back to if the user consents.

In order to prevent a malicious client from tricking a user into granting access they didn’t intend to grant, the authorization server must be able to trust the client information it has.

For example, a malicious client could claim to be Claude Desktop on the consent screen while actually being owned by someone not affiliated with Claude Desktop developers. Seeing the client information on the consent screen, users might grant access thinking they’re authorizing the legitimate Claude Desktop, not realizing that some malicious client now has access to their account.

Improving Client Registration in MCP

For MCP users, a common pattern is to connect to an MCP server by using its URL directly in an MCP client.

This goes against the typical OAuth authorization pattern because the user is selecting the resource server to connect to rather than the client developer. This problem is compounded by the fact that there is an unbounded number of authorization servers that an MCP server may use, meaning that clients need to be able to complete the authorization flow regardless of the provider used.

Some client developers have implemented pre-registration with a select few authorization servers. In this scenario, the client doesn’t need to rely on DCR when it detects an authorization server it knows. However, this is a solution that doesn’t scale given the breadth of the MCP ecosystem - it’s impossible to have every client be registered with every authorization server there is. To mitigate this challenge, we set out to outline some of the goals that we wanted to achieve with improving the client registration experience:

1. Clients: Client developers don’t need to implement pre-registration and distribute a client ID for each authorization server MCP servers might be using.
2. Users: Users don’t need to go through a pre-registration process themselves and manually specify a client ID for every MCP server they connect to.
3. Authorization servers:

• Trust in Metadata: Authorization servers have a way to trust the metadata they associate with a client, such as name and redirect URL.
• Single Client ID per App: Authorization servers can have a single client ID per client for governance and management purposes
• Selective Allow/Deny: Authorization servers can selectively allow or deny clients based on their policies.
• Database Management: Authorization servers do not need to handle an unbounded database or expiration flows for every new client registration.

Currently, none of our existing client registration approaches satisfy all of these requirements. Pre-registration requires too much effort in a highly variable setting (unbounded number of clients connecting to unbounded number of servers), while DCR reduces effort but creates operational issues that a lot of the authorization servers are not ready to tackle yet.

Two Distinct Challenges in MCP Client Registration

After extensive discussion with MCP server implementers, we’ve identified that a few competing solutions to the registration problem were addressing two distinct issues:

1. Operational limitations of Dynamic Client Registration in open environments
2. Client identity and impersonation risks across different deployment scenarios

Challenge 1: Operational Limitations of Dynamic Client Registration

The DCR Model Mismatch

The DCR design takes the pre-registration pattern available in modern OAuth-based authorization servers and makes it available via an API. In fully open environments like MCP, DCR really puts the spotlight on a few operational challenges that an open registration endpoint introduces:

For authorization servers:

• Unbounded database growth: Every time a user connects a client to an MCP server, a new registration is created with the authorization server unless the client already has one. Registrations are also not portable, so using Claude Desktop on your Windows machine, and then jumping to Claude Desktop on macOS will create two distinct client registrations.
• Client expiry “black hole”: There’s no way to tell a client that its ID is invalid without creating an open redirect vulnerability. Clients have to implement their own heuristics for client ID management.
• Per-instance confusion: Each client instance typically gets its own client ID even when using the same application, but on different machines or across different users. From an auditing perspective, an authorization server administrator may see hundreds (if not thousands) of records for the same application without any rhyme or reason.
• Denial-of-Service vulnerability: An unauthenticated /register endpoint writes to a database within the authorization server, meaning that tenant admins now need to worry about rate limiting or policy controls (e.g., hosts allowed to register clients).

For clients:

• Extra overhead: Managing registration state and another secret beyond access/refresh tokens
• No validity checking: Can’t verify if a client ID is still valid
• Unclear lifecycle: No guidance on when to re-register or update credentials

Solution: Client ID Metadata Documents (CIMD)

Client ID Metadata Documents (CIMD), described in OAuth Client ID Metadata Document and implemented by Bluesky, elegantly sidestep these operational issues.

Instead of a registration step, clients use an HTTPS metadata URL as their client ID directly. The server fetches the metadata from the URL at authorization time:

  sequenceDiagram
   participant Client
   participant AuthServer
   participant MetadataURL

   Client->>AuthServer: Authorization request (client_id=https://app.com/oauth.json)
   AuthServer->>MetadataURL: GET https://app.com/oauth.json
   MetadataURL-->>AuthServer: {name: "App", redirect_uris: [...]}
   AuthServer->>Client: Show consent screen & continue flow

This addresses all the operational issues:

• No unbounded database growth: Servers fetch metadata on-demand (can cache for performance)
• No expiry management: The URL is the ID - it doesn’t expire
• Natural per-app model: One URL per application, not per user
• No registration endpoint: No unauthenticated write operations

The cost? Clients need to host a metadata document at an HTTPS URL. For web applications, this is trivial. For desktop applications, this typically means hosting on their backend infrastructure.

Challenge 2: Client Identity and Impersonation

The second challenge is orthogonal to the DCR vs. CIMD debate - it’s about trusting that a client is who it claims to be. This problem will exist regardless of how the registration process is implemented.

For web-based clients, trust is more straightforward, as we have an HTTPS domain that’s tied to a certificate authority. For desktop clients, if the client can’t offload its authorization to existing backend infrastructure, there is difficulty trusting the client is legitimate and unmodified.

The Trust Spectrum

We can map impersonation scenarios on two axes: attacker cost and mitigation complexity.

Low attacker cost/Low mitigation complexity: Domain-based attacks

• Attack: Register malicious callback URI and claim to be Claude Desktop
• Cost: Trick user into clicking a link and consenting
• Mitigation:
  • Restrict trusted domains/URLs
  • Show warnings for unknown domains
  • Works with both DCR and CIMD

Medium attacker cost/Medium mitigation complexity: localhost impersonation

• Attack: Run malicious app on localhost:8080, impersonate legitimate client
• Cost: Trick user into running a malicious application (plus consenting for that app to have data access)
• Problem: Desktop apps can’t hold secrets, hard to prove identity

High attacker cost/High mitigation complexity: Platform-attested applications

• Attack: Get malicious client signed by a trusted authority
• Cost: Extremely high - requires compromising certification vendor processes
• Mitigation: platform system-level attestation (future work)

Solution: Software Statements for Desktop Applications

To broadly solve the client impersonation for the middle tier as well as to prevent localhost impersonation we need signed software statements. Implementing this would require:

1. Client hosts a JSON Web Key Set (JWKS) on their backend
2. Client authenticates the user through their own flow
3. The client-owned backend service issues a short-lived, signed JWT attesting to the client’s identity
4. Client includes this JWT in the OAuth flow
5. Authorization server verifies the JWT against the trusted JWKS

This dramatically raises the bar for client impersonation, as an attacker would need to:

• Compromise the client’s backend infrastructure, or
• Successfully impersonate the client’s authentication flow

Crucially, software statements work with both DCR and CIMD. They’re not a competing solution - they’re a complementary security layer.

Future: Platform-Level Attestation

The strongest protection would be platform-level attestation, e.g. having macOS, Windows, or Android attest that a piece of software is legitimate.

Having OS-level attestation would make client impersonation unreasonably expensive. While the exact way this ties into a software statement is yet to be prototyped, the general direction is threading platform-level application identity validation through to the OAuth flow.

The Complementary Path Forward

While we’re looking at all available options, it’s important to note that we’re not choosing between solutions. We’re exploring complementary approaches for distinct problems:

For operational issues: We are looking at adding CIMD support in favor of DCR

• Keep DCR for backward compatibility
• Recommend CIMD for new implementations
• Both achieve the same authorization goal

For trust issues: Layering software statements on top

• Optional enhancement for both DCR and CIMD
• Required only when localhost impersonation is a concern
• Authorization servers choose their required trust level

Security Considerations

Both CIMD and software statements require authorization servers to make outbound HTTPS requests, potentially to untrusted domains. Implementations must:

• Prevent SSRF attacks by blocking internal network access
• Implement timeouts and size limits
• Consider caching strategies for performance
• Validate response formats strictly

If we adopt these approaches, we’ll need good best practices and SDK support to help avoid vulnerabilities and provide a easy path for implementors.

Next Steps

Discussions for these approaches are happening in the Specification Enhancement Proposals (SEP):

• SEP-991: Client ID Metadata Documents
• SEP-1032: Software Statements with DCR

Get involved: Join the conversation in Discord (the #auth-wg-client-registration channel) or comment on the SEPs directly.

A big thank to the following folks for help with this blog post: Den Delimarsky, Aaron Parecki, Geoff Goodman, Andrew Block, Pieter Kasselman, Abhishek Hingnikar, and Bobby Tiernay.