hmc_list_adapters

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

Annotation readOnlyHint=true already communicates the read-only safety profile. The description adds context about the accepted adapter types and LPAR identifier flexibility, but it does not disclose output details or other behavioral traits. This is acceptable given the annotation coverage, so a 3 is appropriate.

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 three short sentences, front-loaded with the core purpose and followed by parameter explanations. Every sentence contributes value with no redundant words or unnecessary detail.

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 simplicity, the readOnlyHint annotation, and the presence of an output schema, the description covers the essential aspects. It could have mentioned the default value of adapter_type explicitly, but the schema already provides that, so overall it is sufficiently complete.

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 compensate. It fully explains both parameters: lpar_name_or_uuid accepts a PartitionName or UUID (with a helpful reference to hmc_lpars), and adapter_type explicitly lists all four allowed values. This goes well beyond the bare schema and is essential for correct invocation.

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 starts with 'List an LPAR's virtual adapters of a given type,' which clearly states a specific verb, resource, and scope. It distinguishes this listing tool from sibling tools like hmc_add_network_adapter and hmc_delete_adapter.

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 implies when to use the tool (listing LPAR adapters) but does not explicitly discuss alternatives or provide exclusion criteria. It does reference hmc_lpars for finding the LPAR identifier, which is a helpful pointer, but lacks direct comparison with related list tools.

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