hmc_power_off_lpar

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

Beyond the destructiveHint annotation, the description adds valuable context: it submits a job (async behavior), returns the job, and changes the state of a real partition. It also explains the semantics of immediate and wait, which helps the agent understand side effects and blocking behavior.

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 brief and well-structured: a one-sentence purpose, then parameter explanations, then a note about wait. Every sentence adds value, with no fluff or repetition of schema/annotation data.

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?

The description covers purpose, key parameters, return behavior, and side effects. With an output schema present, return values are already specified. Missing details about poll_interval/timeout are minor given their optional nature, but the absence of any mention of permissions or prerequisites leaves a small gap.

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 description explains lpar_name_or_uuid (accepts name or UUID), immediate (forces no graceful shutdown), and wait (blocks until terminal state). This adds meaning beyond the bare schema. However, poll_interval and timeout_seconds are not described, and with 0% schema coverage the description partially compensates but leaves those unexplained.

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 clearly states it 'Submit a PowerOff job for a logical partition', using a specific verb and resource. It distinguishes from sibling tools like hmc_power_off_system and hmc_power_off_vios by targeting logical partitions, and from hmc_power_on_lpar by the action.

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?

Provides context on when to use the tool by explaining the immediate flag ('forces an immediate power off, no graceful OS shutdown') and the wait flag ('block until the job reaches a terminal state'). It does not explicitly name alternatives (e.g., power_off_system) but the distinction is clear from the resource type. There are no explicit exclusions or prerequisites.

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