A client asks for `tools/list`, gets the tool set, and under this revision may keep it: the server advertises a lifetime and a cache scope, and clients may hold the list for as long as that permits [3]. A rename is therefore not atomic with the deploy. The old name is gone from the server and still live in whatever a client cached, alongside the saved configurations, prompts and allowlists written against it [4].
The guide gives no bound on that lifetime, so how long the stale name keeps failing cannot be computed from what it quotes [1]. You can bound it, because you are the one advertising it. The cache lifetime you publish is the deprecation window you have committed to for every name in the list.
Aggregation makes the same problem worse in a different direction. Uniqueness is guaranteed only inside a single server [5], so a proxy fronting several servers can end up holding two tools called `search`, and the specification expects the aggregator to disambiguate, typically by prefixing a server identifier [6]. It also warns against using the server's self-reported name for that prefix, since that name is not guaranteed unique either [7]. The disambiguation key is chosen by whoever aggregates you. `orders.get_status` survives that treatment; `process` or `run` does not carry enough intent to survive anything [8].
The older failure modes are cheaper to fix and still worth naming. A parser cannot catch a vague description that sends the model to the wrong tool, an over-strict `required` list that blocks requests which should work, or an open-ended object that quietly accepts a misspelled field [9]. The dev.to guide's blunter version: a schema cannot prove the handler is authorized, safe, or correct [10]. That is the argument for describing what the tool returns and when a different tool is preferred, and for keeping behavioral rules in the description while machine-checkable limits stay in the schema [15].
What the material does not establish is which older schema guidance has actually gone stale. The guide asserts that the 2026-07-28 revision is the largest rework since launch and that several older guides are now incomplete [2], and it follows that revision together with JSON Schema Draft 2020-12 [1], but the changed behaviours it names are caching and aggregate naming. What the evidence supports is narrower: it documents that existing names have become more expensive to change, not that existing schemas have become wrong.
Two defaults are worth copying regardless. For a tool with no arguments, publish the closed object form with `additionalProperties` set to false, which is what the specification recommends for that case; a bare `{"type": "object"}` is valid and weaker [11]. Optional fields such as `title`, icons, `outputSchema` and annotations go in when the server and its clients can use them, not to make the definition look finished [13].
The guide also points to a browser-based generator that infers property types and nested shapes from one representative JSON object without calling a model, and says to treat the output as editable source rather than a finished contract [14]. That is the correct amount of trust to place in anything inferred from a single example.
