hmc_delete_virtual_network

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

The description discloses that the operation is immediate and returns a confirmation string (no job to poll), which goes beyond the 'destructiveHint' annotation. It also exposes a critical dependency/constraint regarding NetworkBridges and trunk adapter PVIDs, adding meaningful behavioral context.

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 compact and includes purpose, parameter guidance, a usage note, and return behavior in a few sentences. It is well-structured and front-loaded with the core purpose, though the note about PVIDs adds a slightly dense clause.

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 moderate complexity and the presence of an output schema, the description covers essential aspects: what it does, how to specify the system, a critical deletion constraint, and the immediate response format. No critical context is missing.

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 0% schema description coverage, the description is the only source of parameter meaning. It explicitly explains system_name_or_uuid (accepts SystemName or UUID, find it via hmc_systems), but network_uuid is left to the reader's inference from the tool name and the mention of virtual network deletion. This is acceptable but not fully compensatory.

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 a clear and specific verb-object combination: 'Delete a Virtual Network from a managed system.' This unambiguously distinguishes the tool from sibling tools like hmc_create_virtual_network or hmc_list_virtual_networks.

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?

It provides a clear precondition: a network referenced by a NetworkBridge or equal to a trunk adapter's PVID cannot be deleted until the bridge is removed. It also suggests hmc_systems as a way to find the system_name_or_uuid, giving useful context for when to use this tool. It does not explicitly name alternative deletion tools, but the given guidance is sufficient.

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