undo_changes

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

Annotations only declare destructiveHint=true; the description adds genuinely useful behavior beyond that by stating the per-change-type effect of an undo, so the agent knows a restore also implies deletion of created objects. It still omits whether the undo itself is reversible, permission requirements, and what happens when a mixed batch is partially unappliable.

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?

One front-loaded sentence states the operation and its per-type effects, followed by a two-word imperative on dry running. No filler, and the most decision-relevant information (what will actually happen to my data) comes first.

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?

For a four-parameter, destructive mutation with no output schema, the description covers the crucial question of what is changed in the data store. Remaining gaps — returned shape of the dry run, behavior on partial failure, and the meaning of the required workspace — are moderate but not blocking.

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%, so baseline is 3, and the description earns above it by scoping 'your last changes' (only changes made through this server) and by elevating dryRun from an optional flag to a recommended first step. The required 'workspace' parameter and the force-overwrite risk are left to the schema.

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?

It names a specific operation (undo) and then spells out the exact semantics per change type — created items are removed, changed items get old values back, deleted items are restored. This inverse-mapping detail lets an agent distinguish it from read-only history tools like changes_since without inspecting the schema.

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?

"Dry run first" gives a concrete operating principle and signals that dryRun defaults to showing the plan. However, there is no explicit when-to-use/when-not-to-use guidance — it never says whether it only affects your own changes, whether it can be chained repeatedly, or which sibling to use for inspecting history instead.

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