pool_delete

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: the deletion is irreversible, the refusal set (.mgr, .rgw.root, mgr-owned pools) and why — deleting the mgr pool severs the REST transport the tool itself uses — and that these guards hold even under dry_run. That is exactly the kind of behavioral disclosure annotations cannot carry.

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 write/risk tag and the core consequence, then the preview path, then the refusals, then the Args block — a sound ordering. Minor redundancy: 'Irreversible' and 'no undo once the data is gone' restate the same fact, and the refusals are already stated in the header text.

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 high-risk mutation with no output schema and three undocumented-by-schema parameters, the description supplies the consequences, the preview workflow, the refusal conditions, and the target semantics. An agent has everything needed to call this safely.

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 description coverage is 0%, so the description must carry the load and it does: pool_name is documented with its provenance (from pool_ls), dry_run with its effect (preview without deleting), and target as the Ceph target name from config that can be omitted for the default. All three parameters are meaningfully explained beyond their bare names.

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?

Opens with an explicit verb and resource ('Delete a pool') plus a scope statement that distinguishes it from siblings like pool_create or osd_purge. The [WRITE][risk=high] tag and 'destroys all of its data' immediately identify it as the destructive pool-level operation.

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?

Tells the agent to preview with dry_run=True and points at pool_ls as the source of the pool_name, which is concrete usage context. It also implies undefined undo paths ('there is no undo'), but never names undo_list/undo_apply as the alternatives, so the routing guidance stops short of explicit when-not/alternatives.

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