hmc_lpar_summary

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

The description thoroughly discloses behavior beyond the readOnlyHint annotation: it details the exact endpoints consulted, lists the fields returned, states that mapped_storage is always null with reasons, and documents the ValueError when the partition is not found. This is rich behavioral context with no contradiction to 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 well-structured and front-loaded with a one-line summary, then organized into endpoint lists, return fields, and limitations. However, it states 'three HMC endpoints' while only listing two, and the vSCSI storage explanation is lengthy, adding minor bloat.

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 modest input schema and the presence of an output schema, the description comprehensively covers input semantics, behavior, error handling, and scope limitations. It explains what is included and excluded, making it a complete and self-contained reference for the tool.

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 schema only provides a bare string property, so the description adds essential meaning: 'Accepts either a PartitionName (exact match) or a UUID.' This clarifies accepted input formats, though it stops short of providing examples or further format constraints.

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 'One-call LPAR summary: state, RMC, memory/CPU, OS, adapter count, description,' which clearly states the tool's function and output scope. It distinguishes itself from listing tools like hmc_lpars by emphasizing it is a consolidated summary for a single LPAR.

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 use cases by explaining it composes data from multiple endpoints into one call, which clearly positions it as a quick-summary tool. It also gives an explicit alternative: 'Use hmc_vios for per-VIOS storage mappings.' However, it does not explicitly enumerate when not to use this tool beyond the storage case.

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