vm_revert_snapshot

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

Annotations already mark the tool as destructive and not read-only, and the description complements this by explaining the preview workflow, irreversible data loss, duplicate-snapshot handling, and the exact refusal cases. It also discloses what the return dictionary contains, which is especially valuable given there is no output schema.

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 description is long but every sentence carries operational weight: purpose, preview behavior, confirmation safeguard, irreversibility, refusal conditions, prerequisite command, sibling alternative, and return format. It is front-loaded with the most important destructive warning and structured so the agent can quickly extract the key rules.

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 VM operation with no output schema, the description is complete: it explains when to use it, what the preview returns, what the final return looks like, what inputs are required, what can go wrong, and what to do first. Nothing essential for correct invocation is left to guesswork.

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 100%, so the baseline is 3, but the description adds meaning beyond the schema: confirm=false previews versus true applies, snapshot_name must be exact and unique, and snapshot_name is validated against list_snapshots first. This extra context makes the parameter semantics genuinely more actionable.

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 opens with a specific verb and resource: 'Revert a VM to a named snapshot (loses changes since snapshot).' It clearly distinguishes itself from sibling tools by noting that vm_delete_snapshot is for reclaiming space without changing state, so an agent can tell them apart immediately.

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 gives explicit when-to-use guidance: run vm_list_snapshots first for exact names, do not set confirm=True before the user has seen the preview, and use vm_delete_snapshot instead for space reclamation without state change. It also lists refusal conditions, leaving no ambiguity about how to safely invoke the tool.

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