migration_rollback_step

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

Goes well beyond the idempotentHint/destructiveHint annotations: it explains that nothing is deleted, posted entries are append-only, correcting entries persist on record, the approval is voided, and a locked period causes a refusal rather than a partial rollback. The explicit 'CONSEQUENCE' framing is exactly the kind of disclosure a mutation tool needs. Minor loss for the unclear commit_migration relationship.

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?

The behavioural core is front-loaded and useful, but the final 'CONSEQUENCE' block largely restates'correcting entries and archives its records' and 'the step returns to the mapped state' from earlier sentences. The locked-period sentence and the re-commit sentence are the only new content in the tail, so some trimming is warranted.

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?

No output schema exists, and the description carries the reversal semantics well, but with five undocumented parameters and only a hint-level annotation set, an agent still lacks what it needs on inputs (notably 'confirmed') and on what the call returns. Adequate for behaviour, incomplete for invocation.

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% and the description names no parameters at all. Names like workspaceId/planId/stepId are inferable, but the optional 'confirmed' boolean — presumably a confirmation gate for a reversal on live books — is neither mentioned nor explained anywhere, leaving real semantic work undone.

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 ('Reverse a committed step') and names the mechanism (A02 reversing entries, archive master rows through their owning verbs), which clearly separates it from migration_commit_step and migration_check_step. The closing sentence 'this verb requires commit_migration' is ambiguous — it is unclear whether it means the step must have been committed first or that another call is needed afterward — which slightly muddies an otherwise precise purpose statement.

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 concrete conditions: it applies after a commit, it refuses when the opening reversal hits a locked period and leaves the step committed, and the step can be re-committed after a new check. It never explicitly contrasts itself with migration_check_step, migration_preview_step or migration_abandon_plan, so the routing guidance is descriptive rather than exclusionary.

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