hmc_install_lpar_os

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains the PXE-boot process, return value (submitted job), and wait behavior. However, it does not explicitly state that installing an OS is destructive or will overwrite existing data on the LPAR, which is a significant omission for a potentially disruptive operation. The description also does not mention any post-install power state changes.

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 concise and front-loaded with the primary purpose. It uses a short paragraph with clear sentences separating parameter explanations from workflow guidance. It could be slightly more structured (e.g., bullet points for parameters), but it remains information-dense without waste.

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?

For a tool with 10 parameters, no annotations, but an output schema, the description covers the core workflow: prerequisites, network setup, job submission, and post-submission steps. It does not explain poll_interval and timeout_seconds, nor does it describe the output schema structure, but the output schema is available. Overall, it is reasonably complete for a complex tool, though a bit more detail on polling parameters would elevate it.

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 explains the meaning of 7 of 10 parameters (lpar_uuid, nim_ip, nim_gateway, nim_subnetmask, lpar_ip, vlan_id, timeout, wait), including practical details like 'use 0 for untagged' for vlan_id. However, it omits poll_interval and timeout_seconds, and does not clarify the relationship between timeout and timeout_seconds, which is a minor gap.

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: 'Submit a NIM-based LPAR OS installation job.' This clearly distinguishes it from sibling tools like hmc_install_vios (VIOS install) and hmc_create_lpar (LPAR creation). The scope 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 usage context, including prerequisites (existing powered-off LPAR), network configuration requirements, and the option to set wait=True to block. It mentions polling hmc_get_job for status, which implies an alternative workflow. However, it does not explicitly state when not to use this tool or compare it directly to alternatives like hmc_install_vios, so it falls short of a 5.

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