hmc_update_firmware

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

The description discloses the asynchronous job model: 'Submits an UpdateFirmware job to ManagedSystem; poll hmc_get_job for status' and explains the wait flag. However, with no annotations, it does not mention the potentially disruptive nature of firmware updates (e.g., system downtime) or required permissions, leaving a transparency gap.

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 organized, with a clear opening line, parameter explanations, and usage notes. It references related tools to avoid repetition, though the phrase 'Submits an UpdateFirmware job to ManagedSystem' is slightly redundant with the first sentence.

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 the essential workflow: system identification, repository source, job submission, polling, and wait behavior. An output schema exists so return values are covered, but it omits important context like the disruptive nature of firmware updates, prerequisites, and behavior of poll_interval/timeout_seconds. Overall adequate but not complete for a complex operation.

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 low (20%). The description adds meaning to system_name_or_uuid (SystemName or UUID), repository (format reference), and wait (blocking behavior). However, it does not explain poll_interval or timeout_seconds, which remain undocumented in both schema and description.

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 'Submit a managed system firmware update job' with a specific verb and resource. It distinguishes itself from sibling tools like hmc_hmc_update and hmc_vios_update by specifying 'managed system' rather than HMC or VIOS.

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 gives clear context on how to use the tool: identify the system with hmc_systems, reference the repository format from hmc_hmc_update, and poll hmc_get_job for status. It does not explicitly explain when not to use it or directly compare alternatives, but the cross-references provide practical guidance.

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