rollback_guide

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

No annotations are provided, so the description carries the full burden. It discloses that the tool produces a plan including risk notes, but does not explain if it modifies state, requires permissions, or any side effects beyond composition.

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?

A single sentence efficiently conveys purpose and contents. No redundant words, and key information is front-loaded.

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?

The description adequately explains what the plan contains, but lacks details on output format (text/structured) or any prerequisites beyond the snapshot_id. For a simple tool with one parameter, this is nearly sufficient.

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?

The input schema describes 'snapshot_id' as 'Pre-upgrade snapshot to roll back to'. The description adds context by specifying 'pre-upgrade snapshot' and 'roll back plan', reinforcing the parameter's role. With 100% schema coverage, the description adds value beyond 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?

The description clearly states it composes a rollback plan for a pre-upgrade snapshot, listing specific components (downgrade command, state-restore steps, risk notes). This distinguishes it from siblings like upgrade_guide (upgrade planning) and list_snapshots (listing snapshots).

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?

The description implies usage when needing a rollback plan for a snapshot, but does not explicitly state when to use this tool vs alternatives, nor does it provide exclusions or cross-references to siblings.

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