hmc_delete_vios

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

Beyond the destructiveHint annotation, the description reveals that deletion is permanent and irreversible, that the tool refuses to delete if state is not 'not activated', and that it returns a confirmation string with no job to poll. It also documents the HMCError raised on HTTP 409.

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 moderately long but every sentence contributes essential information: purpose, preconditions, mutation behavior, return type, and error handling. It is well-organized and free of fluff.

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 destructive and conditional nature of the operation, the description fully covers prerequisites, behavior, return value, and exceptions. Since an output schema exists, the lack of detailed return-field explanation is acceptable. The description is complete for safe invocation.

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?

With schema description coverage at 0%, the description compensates by identifying the parameter as a UUID and pointing to hmc_vios for confirmation. It doesn't provide format examples or a structured parameter definition, but for a single self-explanatory parameter this is adequate and adds practical context.

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 opens with 'Delete (destroy) a VIOS partition by UUID', which is a specific verb+resource+identifier. It clearly distinguishes from sibling tools like hmc_delete_lpar, hmc_delete_user, and hmc_delete_virtual_network by focusing on VIOS partitions.

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 states the precondition that the VIOS must be powered off, referencing hmc_power_off_vios and confirmation via hmc_lpars. It also instructs to confirm the UUID with hmc_vios, and notes the state requirement ('not activated'), giving clear when-to-use guidance.

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