hmc_remove_vnic

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

Beyond the destructiveHint annotation, the description adds valuable context: a WARNING that this modifies the LPAR configuration, a requirement to confirm all three parameters, and a note that the operation is immediate with no job to poll. It also discloses the internal UUID-to-name resolution process (REST with SSH fallback), which is not captured by the annotation.

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 efficiently structured: a one-sentence purpose, a command reference block, a short paragraph on identifier resolution, and a concise warning/return note. Every sentence earns its place; the length is justified by the destructive nature and the need to clarify prerequisites. It is front-loaded with the core purpose.

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 destructive nature, the description covers all necessary context: what it does, how it runs (SSH command), identifier handling, prerequisite (vnic_id from list), warning, and return behavior (HMC CLI output, no job polling). The presence of an output schema is noted, and the description appropriately summarizes the return value without duplicating schema details.

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?

The input schema provides only parameter names and types, with 0% description coverage. The tool description compensates by explaining that system_name_or_uuid and lpar_name_or_uuid can be CLI names or UUIDs (with conversion logic) and that vnic_id is the numeric ID from hmc_list_vnics. This is meaningful beyond the schema, though it does not delve into formatting or constraints for each parameter in exhaustive detail.

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 specific verb and resource: 'Remove a vNIC from an LPAR via the HMC CLI.' This clearly states the action and distinguishes it from sibling tools like hmc_add_vnic or hmc_list_vnics. The resource is unambiguous (vNIC from an LPAR) and the method (HMC CLI) is explicit.

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 clear context for use: it states that vnic_id is 'the numeric ID as reported by hmc_list_vnics', implying a prerequisite to list first. It also explains how system and partition identifiers may be given (CLI name or UUID). However, it does not explicitly name alternatives or exclusions (e.g., when not to use this vs. hmc_delete_adapter), so it earns a 4 rather than a 5.

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