pbs_prune

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 openly declares the tool is a mutation, that it deletes recovery points permanently when dry_run=False (PLAN is HIGH, no undo), and that it is synchronous. It could mention required permissions, but overall it is highly transparent.

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 concise and front-loaded, with four sentences that each earn their place. It starts with a clear action label 'MUTATION', explains safety gates, notes the default behavior, and finishes with a distinct alternative. No wasted words.

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?

Given the complexity of 12 parameters and a mutation tool with output schema, the description covers essential behavioral aspects: safety mechanisms, synchronization, and alternative for single snapshots. It does not need to explain return values due to the output schema, and it provides critical context about irreversibility.

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. The description adds value beyond the schema by explaining the interplay between the confirm and dry_run parameters, framing them as safety gates. It does not repeat schema details but provides high-level context that aids correct parameter usage.

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 starts with 'MUTATION: prune backup snapshots per a retention policy,' clearly specifying the verb (prune), resource (backup snapshots), and action (per retention policy). It also differentiates from sibling pbs_snapshot_delete by stating 'For one specific snapshot use pbs_snapshot_delete instead.'

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 explicitly outlines two safety gates—confirm and dry_run—with clear explanations: 'dry_run=True (default) only previews; dry_run=False DELETES recovery points.' It also explicitly mentions when not to use this tool, directing to pbs_snapshot_delete for single snapshot deletion.

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