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