Roll back application

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

Beyond the annotations (destructiveHint=true, idempotentHint=true, openWorldHint=true, readOnlyHint=false), it discloses the specific destruction ('replacement of current application data by that backup'), the auth requirement ('applications:manage'), the preconditions that cause refusal ('arbitrary targets are refused'), and how to retry safely with the same idempotency key even after availability changes. This meaningfully extends what structured fields already convey.

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?

Front-loaded with the action, then a tight sequence of precondition, disclosure, polling, idempotency, and permission sentences, each carrying distinct operational information. Dense but justified by the destructive multi-parameter nature of the tool, with no filler.

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 an async destructive operation with no output schema, it tells the agent where the result surfaces ('poll installation and events'), what must be disclosed and approved, what the version preconditions are, and the retry contract. Nothing essential to correct invocation is missing.

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 baseline is 3, but the description adds real meaning: expected_blueprint_version and expected_upstream_version must be copied from the advertised rollback release and act as execution preconditions, and idempotencyKey must be reused only for an unchanged retry. This supplements the schema's field-level descriptions with cross-parameter rules.

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 (rollback/queue the exact reverse transition) and resource (application), and pins the target to the transition 'advertised as type=rollback by get_application_installation', which clearly separates it from rollback_firecracker_snapshot and rollback_snapshot. An agent can identify scope and the source of truth without opening any 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 an explicit call sequence: query get_application_installation, read its release/backup, disclose the data replacement, and obtain explicit approval before invoking. Prerequisites and the required permission (applications:manage) are stated. It lacks an explicit when-not or direct alternative comparison, but the workflow context is strong.

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