No mechanism for tool deprecation or soft removal

[vaibhavk270]

Sites evolve over time. There's no way for a developer to mark a tool as deprecated, provide a migration hint, or gracefully retire it. An agent that has cached tool descriptions (e.g., via a PWA manifest as mentioned in "Future Explorations") could try to call a removed tool. The spec needs a deprecated annotation with a reason/successor field, similar to how OpenAPI handles this.

[johannhof]

I'm not sure how this works in practice. Who would take action on being warned that something is a deprecated tool?

[vaibhavk270]

I'm not sure how this works in practice. Who would take action on being warned that something is a deprecated tool?

This will be help full in multiple layers

The agent— >a capable model can read a deprecated annotation (especially if it includes a successor field) and prefer the replacement tool without any hard removal needed.
The developer —> an MCP client SDK can surface deprecation warnings when a manifest is fetched or refreshed, similar to browser DevTools warnings for deprecated Web APIs. Developers get advance notice rather than discovering breakage at runtime.
The runtime/cache layer—> this is the core motivation. If a PWA or offline agent has cached a tool manifest and that tool gets removed, there's currently no graceful path. A deprecated flag + removedAfter date lets the client warn proactively, fall back to a successor, or return a meaningful error with a migration hint instead of a silent failure.
This is essentially how HTTP Deprecation headers (RFC 9745) and OpenAPI's deprecated field work — the signal is emitted once, and each layer of the stack consumes it in the way that makes sense for that layer. The spec doesn't need to mandate who acts on it; it just needs to make the signal available.

[bwalderman]

This project is moving in a different direction than a PWA-like manifest that was mentioned in the explainer. As of right now, tool defintions are either imperative or declarative, and both of these types of tools need a live web page to exist. In other words, the page is the manifest. If a web page is active and able to receive WebMCP tool calls, then any agents connected to it should by definition be aware of the latest toolset. I don't see a situation where the web page and the agent (which live on the same device) ever fall out of sync.