Undo Model Change

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

With no annotations, the description carries the full burden and does so well: it declares the tool mutating, states that the undo is itself recorded and irreversible (no redo), explains that verdicts are re-served rather than re-judged, that findings on removed controls are resolved, that version numbers are never reused, and that the discarded version stays readable. It even enumerates the 409 refusal codes with their meanings.

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?

Well front-loaded: the core action and mutation warning come first, then per-target behavior and refusal handling. It is on the long side, and the two explicit response-shape listings duplicate what the existing output schema already conveys, which is slightly wasteful.

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 destructive, two-mode mutation tool with an output schema, the description covers both branches, their side effects, failure modes, and recovery guidance. An agent has everything needed to invoke it correctly and interpret both success and refusal responses.

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 description coverage is 0%, so the description must compensate. It fully specifies the meaning and side effects of the target enum values ('controls' vs 'version'), which is the only non-obvious parameter. model_id and server_version are left undefined, but they are self-explanatory identifiers, so the gap is minor.

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 precise verb+resource ('Undo the latest change to a model's controls, or revert its latest version') and immediately splits the two modes by the target parameter. It also references the sibling tool that supplies the undo_target (list_control_revisions), so an agent can tell this apart from adjacent revision/history tools without opening a 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?

Gives clear operational context: one change undone per call, latest first, no redo, and the precondition that set_diverged must be resolved by undoing the later change first. It lacks explicit guidance on when to prefer this over neighbors like undo_composition_event or discard_control_build, so it falls short of a full when/when-not/alternatives treatment.

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