# What happens when an MCP server changes its tool schema?

That "stale catalog" error means the client is still holding tool schemas from an old `tools/list` call: MCP clients cache those schemas, and a server that changes a tool's parameters mid-session keeps getting called against the outdated version until the client asks again. The spec gives servers a way to signal the change: a server that declares the `listChanged` capability can send a `notifications/tools/list_changed` message, and a client that acts on it re-fetches the list before the next call.

A server that doesn't declare the capability, or a client that doesn't act on the notification, leaves the model building arguments for a tool that no longer looks like that, and the call either fails validation as a tool execution error or fails outright as a malformed request. [A renamed tool parameter breaks an agent the same way](/answers/tool-calling/why-does-renaming-a-tool-parameter-break-my-agent) whether the stale definition came from a cached MCP schema or a copy baked into a prompt. Treat a schema change like a deploy: version the tool name or restart the session, since caching gives a client no other trigger to refresh mid-conversation.

---

Sources:
- Model Context Protocol specification: Tools: https://modelcontextprotocol.io/specification/2025-11-25/server/tools (fetched 2026-09-12)

Source: https://tessary.ai/answers/mcp-tool-reliability/what-happens-when-an-mcp-server-changes-its-tool-schema
More on Mcp tool reliability: https://tessary.ai/answers/mcp-tool-reliability
From Tessary, agent reliability for AI agents in production: https://tessary.ai