Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare non-readonly, idempotent, non-destructive; the description supplies the substance behind those hints: an errored edit saves nothing (atomicity), a no-op edit returns noop, requestId makes a retry return the first result (the mechanism for idempotencyHint), and a conflict enumerates what changed. That is exactly the class of context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the revision/immutability fact, then the required inputs, then failure modes. Every clause carries information, but the heavy parenthetical stacking in one long block makes it denser to parse than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need no prose, and the description covers atomicity, no-op, conflict, and retry semantics for this 8-parameter mutation. Remaining gaps are prerequisites such as permission requirements or whether validation is expected first, and how ops interacts with restoreRevision or brief beyond the mermaid constraint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, and the description adds real meaning beyond it: baseRevision is the revision you last read (an optimistic-concurrency token, not just an integer), and mermaid is applied as a diff against the current view rather than replacing wholesale. It partly restates schema-documented text (one-line message, requestId example), which keeps it off a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Changes a saved diagram") plus the key scope qualifier: it creates a new revision and old ones stay. That revision semantics alone distinguishes it from diagram_create (new diagram) and diagram_delete, so no sibling confusion is possible.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It spells out the mutating modes and their mutual exclusivity: ops, mermaid (which cannot be combined with ops or restoreRevision), restoreRevision, or brief. That is concrete guidance for choosing an approach within the tool, though it never says when to reach for diagram_edit versus diagram_create or diagram_validate first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.