pve_node_disk_wipe

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 correctly discloses the destructive nature (irreversible data destruction) and notes the HTTP endpoint. The caveat 'Smoke-confirm: endpoint and body shape not live-verified' is a useful behavioral hint. However, it omits authentication requirements, potential errors, or what happens on failure. For a high-risk tool, this is adequate but not comprehensive.

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 relatively short and front-loads critical information: 'MUTATION', 'RISK_HIGH, NO UNDO'. Every sentence adds value except perhaps the redundant 'This is irreversible — all data is permanently erased.' which echoes earlier warnings. Overall, it is efficiently structured.

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 tool's high risk and 4 parameters with low schema coverage, the description should provide more context: parameter details, error handling, and usage scenarios. The output schema exists but is not referenced. The description covers safety warnings well but leaves gaps in operational context, making it incomplete for a destructive operation.

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 low (25%): only 'proximo_target' has a description. The tool description does not explain the 'disk' parameter format (e.g., device path like /dev/sda), the 'node' parameter meaning, or the 'confirm' parameter beyond a mention. It adds minimal value beyond the schema, and with low coverage, more explanation is needed.

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 clearly states the tool wipes all data and partition tables on a node disk, using strong terms like 'MUTATION' and 'RISK_HIGH, NO UNDO'. However, it does not explicitly differentiate from sibling tools like pve_node_disk_initgpt, which may initialize a disk but not wipe data. The purpose is specific and clear but lacks sibling contrast.

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 provides minimal guidance: it mentions that 'confirm=True' is required to execute and warns about high risk. However, it does not explain when to use this tool versus alternatives (e.g., pve_node_disk_initgpt for initializing GPT, or pve_disk_move for moving disks). No context on prerequisites or post-conditions.

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