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

Annotations only declare destructive/not-idempotent; the description goes far beyond by disclosing the live read of volumes and claims, the 'Not checked' refusal path, the confirmation card contents, the CSI snapshot-before-delete protocol with Retain policy and 5-minute bounded wait, per-volume re-check before delete, and the kubernetes.write requirement. Non-reversibility and permanent data loss are stated outright.

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 core rule and eligibility gate are front-loaded, and nearly every sentence carries operational weight (snapshot behavior, failure modes, restore path). It is a single dense block, though; the snapshot and result-contract material would scan much better as short structured segments, and "Not reversible" partly restates the permanent-data-loss sentence.

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 compensates by describing what the confirmation card shows (size, age, StorageClass, reclaim policy, backing volume, data outcome) and what the result returns (snapshot names plus the PVC dataSource restore recipe). For a destructive, asynchronous, snapshot-gated operation this is complete enough to call correctly.

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 real meaning to `names`: each named volume must itself be Released or Available ble, the 20-per-call ceiling, and the fact that one failing snapshot blocks only that volume. It adds nothing on `cluster_id`, and most of its value is behavioral rather than per-parameter.

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?

Opening clause states a specific verb, resource and safety precondition ("Delete PersistentVolumes no claim uses"), then sharpens it with the exact eligibility states (Released or Available). An agent can distinguish this from delete_resource or delete_storage_class without consulting any other field.

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?

Explicit when-to-use (volume must be Released/Available and unbound), explicit when-not (a Bound volume is refused naming its claim), and named alternatives for the safer path (create_stack_restore_point on the stack that used the claim, list_restore_points). It even points to the discovery tool with the exact filter: describe_resources on kind PersistentVolume with status.phase.

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