Proposal: Add cacheControl hint to ToolAnnotations for volatile data

[renatomarinho]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

While building a multi-agent architecture on top of MCP for a SaaS product, I ran into a consistent failure mode with stale context in multi-turn conversations. I'd love to get the community's input on a small addition to the spec.

The Problem: Out-of-band mutations

The scenario is straightforward:

1. User asks: "What are the dates for Sprint 123?"
2. Agent calls sprints.get, gets "Nov 1 to Nov 10", replies correctly.
3. A project manager updates the sprint dates via the web UI — outside the chat. Database now says "Nov 15".
4. User asks: "Did the dates change?"
5. Agent finds the answer already in its context window and replies: "No, the dates are still Nov 1 to Nov 10."

The agent operates under a closed-world assumption — it behaves as if it's the only actor mutating data. This failure mode has been formally studied: Cheng et al. (arXiv:2510.23853) coined the term Temporal Blindness for exactly this, showing that no tested model achieved better than 65% alignment with real-world state after out-of-band mutations. Singh (Preprints:202601.0910) formalized State Drift — the persistent, hidden misalignment between an agent's internal state and the environment — showing that increasing context capacity alone does not prevent it. The causal variant, where the agent's own writes create contradictory representations within the same context window, is particularly dangerous in agentic MCP workflows.

The core issue in MCP

Right now, the protocol treats all tool results as equally durable. A tool returning "The capital of France" and a tool returning "Current Sprint Status" carry the same epistemological weight in context. There's no standard way for the server to communicate data volatility to the client.

The Proposal

Extend ToolAnnotations with a cacheControl hint:

interface ToolAnnotations {
  readOnlyHint?: boolean;
  destructiveHint?: boolean;
  // Proposed:
  cacheControl?: 'no-store' | 'immutable';
}

Semantics map to RFC 7234 conventions:

• immutable — result will never change (git commit hash, country codes, ICD-10 codes). Safe to reuse across turns.
• no-store — result is volatile. The model should re-invoke the tool on the next relevant turn rather than answering from context.

The rationale for borrowing RFC 7234 vocabulary is that these terms carry strong pre-existing semantic weight from LLM training data. The association between no-store and "do not reuse this response" is already embedded in the model's weights from exposure to HTTP documentation, API specs, and developer discussions. There is intentionally no max-age — LLMs have no clock, so time-based expiration is meaningless inside a context window.

Related work in the spec

I noticed SEP-1862 (Tool Resolution) by @SamMorrowDrums proposes a tools/resolve mechanism for argument-aware annotation refinement. These two proposals are complementary rather than overlapping:

• SEP-1862 solves: "Is this tool destructive given these specific arguments?" (refining existing annotations at runtime)
• This proposal solves: "Is the result of this tool volatile or permanent?" (a new annotation that doesn't exist yet)

If both land, they compose naturally: tools/list could declare a static cacheControl: 'no-store', and tools/resolve could refine it — e.g., a manage_data tool might be no-store for action: 'get_balance' but immutable for action: 'get_currency_code'.

Prior art / reference implementation

I've been running this pattern in production and open-sourced a layer that implements it today as a workaround: vinkius-labs/mcp-state-sync. It decorates tool descriptions with [Cache-Control: no-store] at tools/list time and injects causal invalidation signals into write responses. It's not a spec replacement — it's an application-layer patch that demonstrates the mechanism works in practice across fintech, healthcare, and infrastructure scenarios.

Questions for the community

1. Does this problem resonate with others building multi-turn or multi-agent systems?
2. Is ToolAnnotations the right place for this, or should volatility hints live elsewhere in the spec?
3. Would this compose well with SEP-1862's tools/resolve for argument-aware cache hints?
4. Are there simpler native solutions I'm missing?

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[renatomarinho]

May 2026 update

Since filing this in February, the MCP team published Tool Annotations as Risk Vocabulary (March 16), which introduced a Tool Annotations Interest Group and a formal evaluation framework for new annotation proposals. That post also lists the five SEPs currently under active review - all addressing trust, sensitivity, and security boundaries. None of them address result volatility. I want to use their framework to sharpen the two open questions I left unresolved.

---

On Q2: Is ToolAnnotations the right place?

The Interest Group has explicitly placed on its agenda whether annotations should live on tool responses as well as tool definitions. That question is directly relevant here.

cacheControl belongs on the definition, not the response, and the reason is mechanical: the volatility signal must reach the client at tools/list time, before a result is ever produced and written into context. A response-level annotation arrives too late - the result is already in context by the time the client could act on it. The failure mode described in this proposal (the agent answering from a stale context entry) is prevented only if the client knows, before the first invocation, that subsequent results from this tool must not be reused.

This also makes cacheControl structurally consistent with the existing hints. destructiveHint, idempotentHint, and readOnlyHint are all pre-invocation signals that inform client behavior before the call. cacheControl is a pre-invocation signal that informs client behavior before reuse of a prior call's result. Same layer, same contract.

On Q4: Are there simpler native solutions?

The Interest Group's own post answers this directly:

"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."

The failure mode here is not deployment-specific. Any MCP client - regardless of vendor - that does not distinguish between volatile and durable tool results will exhibit temporal blindness after out-of-band mutations. _meta solves the problem within a single controlled deployment. It does not solve it at the protocol level.

On the trust profile

One concern that tends to come up with new annotations is how much trust they require to be useful. cacheControl has a favorable profile:

• A server lying about no-store causes over-invocation - wasted tokens, no security impact.
• A server lying about immutable causes stale context - the original failure mode, no security boundary crossing.

Compare this to destructiveHint: false from an untrusted server, where the lie can cause data loss. cacheControl is at the safer end of the existing annotation trust spectrum.

---

The evaluation framework in the March post ends with: "If you're thinking of proposing a new annotation, the questions above are a good place to start shaping it." This comment is that exercise. The next step from my side would be a formal SEP draft. Is there a preferred path to bring this to the Tool Annotations Interest Group?