hmc-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Most tools have clearly distinct purposes, but minor overlaps exist: hmc_find_system duplicates hmc_systems(name=...), hmc_provision_lpar overlaps with the create+adapter+storage sequence, and hmc_list_resources is a generic catch-all. Detailed descriptions mitigate most confusion.
Naming Consistency4/5
The vast majority follow hmc_<verb>_<noun> (list, create, delete, modify, power, add, remove, backup, restore, install, migrate, get, set). A few tools use bare plural nouns (hmc_systems, hmc_lpars, hmc_vios) or noun phrases (hmc_console_info, hmc_capacity_report), creating minor inconsistency, but the pattern remains predictable.
Tool Count1/5
At 101 tools, this is far beyond the 3-15 tool sweet spot. Even for a complex domain like HMC management, the sheer number overwhelms agents and makes tool selection costly. The server would benefit from consolidation, e.g., merging some list/get operations into single parameterized tools.
Completeness3/5
The tool set covers a remarkably broad range: LPAR/VIOS lifecycle, power, storage, networking, users, updates, metrics, migrations, and profiles. However, there are obvious gaps: no delete/modify for volume groups or virtual disks, no create for shared memory pools, no management for virtual switches beyond listing, and no CRUD for clusters/SSPs themselves.
Average 4.4/5 across 100 of 101 tools scored. Lowest: 3.4/5.
See the Tool Scores section below for per-tool breakdowns.
- 3 of 3 community issues answered or closed in the last 6 months
- 1882 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses the asynchronous nature via the 'PowerOn job' reference and explains that wait=True blocks to a terminal state. However, it does not describe side effects, permission requirements, or behavior if the VIOS is already powered on. The job-related note adds some value, but other critical behavioral aspects remain undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using two short sentences with no wasted words. It front-loads the purpose and then adds a focused note about the key parameter. A structured list of parameters would be clearer, but the brevity is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and no parameter documentation in the schema, so the description needs to cover them all to be complete. It only covers two of the four, leaving poll_interval and timeout_seconds undocumented. Additionally, it does not explain the job flow or expected behavior when wait=False. The presence of an output schema mitigates the need to describe returns, but the missing parameter semantics create a notable completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains vios_name_or_uuid (accepting name or UUID, with a pointer to hmc_vios) and wait (blocking behavior). However, poll_interval and timeout_seconds are left completely unexplained, despite having defaults in the schema. This leaves a significant gap for an agent trying to use the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Power on a VIOS' with a specific verb and resource, and the (PowerOn job) qualifier adds precision. It distinguishes from sibling tools like hmc_power_off_vios and hmc_power_on_lpar by targeting VIOS specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives some usage guidance by explaining how to identify the VIOS ('vios_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_vios)') and how to use the wait parameter. However, it does not explicitly state when to use this tool versus alternatives like hmc_power_on_system or hmc_power_off_vios, nor does it mention prerequisites or excluded scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It explains parameter semantics (tagged) but does not disclose prerequisites, side effects, asynchronous job behavior, authority requirements, or error cases. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose, followed by targeted parameter clarifications. Every sentence adds value, referencing helper tools and explaining the tagged behavior. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks critical operational context. It doesn't explain name and vlan_id semantics, nor does it describe return value behavior, success/failure conditions, or whether the operation is asynchronous. With no annotations and four required parameters, this is insufficient for an agent to confidently invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It provides useful meaning for system_name_or_uuid, vswitch_id, and tagged, but it fails to explain name and vlan_id, which are two of the five parameters. This partial coverage is better than nothing but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a Virtual Network (VLAN) on a managed system,' using a specific verb and resource. It distinguishes this from sibling tools like hmc_list_virtual_networks and hmc_delete_virtual_network by focusing on the creation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (creating a VLAN) and references helper tools for finding identifiers (hmc_systems, hmc_list_virtual_switches). However, it does not explicitly state exclusions or alternatives, such as when a VLAN might already exist or when using a bridge vs. switch would be preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates this is a read-only operation, lowering the bar. The description adds context about the parameter accepting a name or UUID, but does not disclose output format, pagination, or other behavioral details beyond what the annotation provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundant information. The purpose is stated first, then the parameter explanation follows, making it front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter, an output schema, and readOnlyHint annotation, the description is adequate. It explains what the tool does and how to obtain the required system identifier. The potential ambiguity with hmc_list_sea_adapters is not addressed, but the description itself is complete enough for selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining that system_name_or_uuid accepts either a SystemName or a UUID and references hmc_systems to find it. This goes beyond the raw schema, which only declares the parameter as a string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists NetworkBridges (Shared Ethernet Adapters) on a managed system, using a specific verb and resource. It does not explicitly distinguish from the sibling hmc_list_sea_adapters, which likely refers to the same concept, but the parenthetical clarification adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by explaining that the system_name_or_uuid parameter can be found with hmc_systems, giving some context. However, it does not explicitly state when to use this tool versus alternatives like hmc_list_sea_adapters or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only says 'recover' without explaining side effects, required permissions, or what state changes occur. This is insufficient for a recovery operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with purpose first, then parameter explanation. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it's a recovery tool with a single parameter, the description is minimal. It doesn't mention what recovery entails, whether it's asynchronous, or if a job ID is returned (despite having an output schema). This is a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description explains that the parameter accepts either a PartitionName or UUID and points to hmc_lpars for discovery. This adds value beyond the bare schema, though it doesn't clarify the parameter's role in recovery.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Recover an LPAR after a failed LPM migration' with a clear verb and resource. It distinguishes itself from sibling tools like migrate/validate/abort, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use ('after a failed LPM migration'), and gives a hint to use hmc_lpars for finding the parameter. It doesn't mention alternatives or exclusions, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full transparency burden. It discloses 'The HMC generates the WWPNs' and clarifies server-side vs client-side roles. However, it does not mention whether the LPAR must be powered off, whether the operation is asynchronous (e.g., returns a job), or any permission requirements—common gaps for a mutation tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 70 words and front-loaded with the core action. Each sentence adds value: the main action, parameter semantics, and usage guidance. No filler or redundancy, though the parameter explanations could be more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters, zero schema coverage, and no annotations, the description covers the core concept and three of four parameters. It fails to explain slot_number and doesn't mention whether the operation is asynchronous (common for HMC jobs) or if there are prerequisites (e.g., LPAR existence, VIOS readiness). The output schema may document return values, but the description leaves these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 lpar_name_or_uuid (accepts PartitionName or UUID, find with hmc_lpars), vios_partition_id (integer PartitionID of serving VIOS), and vios_slot (server-side virtual FC slot number). Critically, it omits slot_number, which remains undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add a Virtual Fibre Channel (NPIV) client adapter to an LPAR,' clearly stating the verb, resource, and target. It explicitly distinguishes from vSCSI with 'instead of vSCSI,' which differentiates it from sibling tools like hmc_add_vscsi_adapter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use guidance: 'Use this for SAN storage via NPIV instead of vSCSI.' It also instructs finding lpar_name_or_uuid via hmc_lpars, providing a lookup path. However, it doesn't enumerate other exclusions or prerequisites beyond this alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation destructiveHint=true already indicates the operation is destructive. The description adds context that it is for failed LPARs and another managed system, but does not disclose details such as what happens to the original LPAR, whether it is a long-running job, or if there are prerequisites. This is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, followed by a compact parameter tip. Every sentence earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action and one parameter, but given the existence of an output schema and the context of sibling job-related tools, it omits useful behavioral context such as whether the operation is asynchronous, how to track progress, or any preconditions. It is minimally adequate but lacks completeness for a destructive remote operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must document both parameters. It explains lpar_name_or_uuid (accepts PartitionName or UUID, find with hmc_lpars) but provides no explanation for target_system. This is a significant gap for one of two required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Remote-restart' and a specific resource 'failed LPAR' with a clear scope 'on another managed system.' This distinguishes it from sibling tools like hmc_power_on_lpar (local power-on) and hmc_migrate_lpar (migration), providing unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for failed LPARs that need restart on a different managed system, which is clear context for when to use it. However, it does not explicitly exclude alternatives or name them, though the 'remote' and 'failed' conditions contextually differentiate it from local power operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavioral traits. It mentions a key constraint (only one per VIOS) and the repository's role, but it does not mention potential side effects, required privileges, idempotency, or what happens if a repository already exists. This is partial but insufficient for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a main sentence stating the action, followed by brief parameter notes and a constraint. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core purpose and a key constraint, but it lacks information about prerequisites (e.g., the Volume Group must exist), the meaning of vg_uuid, and the outcome of the operation. The presence of an output schema reduces the need to describe return values, but other contextual details are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions, so the description must compensate. It explains vios_name_or_uuid (accepts PartitionName or UUID, find with hmc_vios) and size_mb (RepositorySize), but provides no explanation for vg_uuid, leaving one of three parameters underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Create the Virtual Media Repository (named VMLibrary) on a Volume Group.' It specifies the resource (Volume Group), the resulting object (VMLibrary), and its purpose (holding file-backed ISO images), which distinguishes it from sibling tools like hmc_delete_media_repository.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: it is for creating a repository that holds ISO images, with the constraint that only one can exist per VIOS. It also hints at dependency on hmc_vios to find the vios_name_or_uuid. However, it does not explicitly state when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It reveals that only blank media can be created and describes parameter acceptance for vios_name_or_uuid, but it omits behavioral details like whether the operation creates a job, requires a pre-existing volume group (vg_uuid), or has other side effects. The disclosed constraints are useful but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: first sentence states the purpose, second sentence clarifies the key identifier parameter, and third sentence covers the remaining parameters and a constraint. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action and several parameter semantics, but it omits the role of vg_uuid entirely and does not mention whether the operation is asynchronous or returns a job ID. Since an output schema exists, return values are covered, but the missing parameter and operational context leave gaps for a tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 vios_name_or_uuid (PartitionName or UUID), media_name (file name), and size_mb (MediaSize). However, vg_uuid is left unexplained, so it does not fully cover all four parameters. Given the high gap in schema, this is still a solid contribution.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create a blank VirtualOpticalMedia (ISO container) in the media repository.' It uses a specific verb (create) and a specific resource (VirtualOpticalMedia), and the distinction from sibling tools like create_virtual_disk is evident from the phrasing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a constraint ('Only blank media can be created via the API') and a hint for finding the vios_name_or_uuid parameter (hmc_vios), but it does not explicitly state when to use this tool versus alternatives such as create_virtual_disk or create_media_repository, nor does it mention exclusions or prerequisites like an existing media repository.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description aligns with that. It adds that the tool returns status/result, but doesn't disclose behavior for in-progress jobs, missing UUIDs, or whether it polls. Minimal extra context beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the primary action, and no filler. Perfectly concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, read-only, has output schema), and the description accurately covers its purpose. It could mention how to obtain the UUID, but the overall context is sufficiently complete given the structured data available.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. Saying 'by UUID' only restates the property name (job_uuid) without adding meaning such as where the UUID comes from, format expectations, or examples. It adds little value over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') with a clear resource ('HMC job') and qualifier ('by UUID'). It distinguishes from siblings like hmc_recent_jobs and hmc_wait_for_job by indicating this is a direct lookup by identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context of usage is clear: when you have a job UUID and want its current status or result. However, it does not explicitly mention alternatives (e.g., hmc_wait_for_job for polling) or exclusions, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It adds valuable context by mentioning that validation runs as a job and that wait=True blocks until a terminal state. However, it does not disclose whether the operation is non-destructive, any prerequisites, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with the purpose first, followed by essential parameter specifics. There is no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core purpose is clear, but the description is thin for a 7-parameter tool. It omits important context like whether validation modifies anything, how to interpret the validation output (though an output schema exists), and the meaning of target_profile_name. It also does not connect to the actual migration workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only lpar_name_or_uuid and wait are explained, with clear detail about accepted name/UUID formats and wait blocking behavior. Since schema description coverage is 0%, the description should compensate for all parameters, but target_system, target_profile_name, wait_time, poll_interval, and timeout_seconds are left to names/defaults only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Validate whether an LPM migration of an LPAR to target_system would succeed' with a specific verb and resource, clearly distinguishing this validation tool from sibling migration tools like hmc_migrate_lpar and hmc_migrate_abort_lpar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: validating migration success before performing it. It also provides practical guidance on the wait parameter and lpar_name_or_uuid format. However, it does not explicitly name alternatives or exclusions such as 'use hmc_migrate_lpar to actually migrate'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint=true, so the agent already knows this is destructive. The description adds valuable behavioral context beyond annotations: it mentions the PowerOff job, explains that immediate skips graceful shutdown, and clarifies that wait blocks for terminal state. It does not detail side effects on running LPARs or error conditions, but the provided context is meaningful and consistent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of three short sentences with the core action first. Every sentence adds relevant information without redundancy or fluff. The structure is front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a destructive action and an output schema, but the description does not cover what happens to running LPARs or the system's state after the job, nor does it elaborate on the job lifecycle beyond 'terminal state'. Given the presence of an output schema, return values need not be described, but for a power-off operation, more context on consequences would improve completeness. It is sufficient but not fully thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, requiring the description to compensate. It explains system_name_or_uuid (accepts SystemName or UUID) and wait (block until terminal state), and implies immediate behavior via 'immediate skips graceful shutdown'. However, poll_interval and timeout_seconds are not explained, leaving a gap. The parameter names themselves are somewhat self-explanatory, so the partial coverage earns a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action: 'Power off a managed system (PowerOff job).' It uses a specific verb and resource, distinguishing it from sibling tools like hmc_power_off_lpar or hmc_power_on_system. The mention of 'immediate skips graceful shutdown' further clarifies a key variant of the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage guidance, such as setting wait=True to block for terminal state, but does not explicitly compare with alternative tools like hmc_power_off_lpar or hmc_power_on_system. The sibling list implies a distinction between system and LPAR power operations, but the description itself does not state when to use this versus those alternatives, so it is minimally adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It explains the prerequisite that physical volumes must be free and the outcome (pools disks for carving virtual disks), but does not mention side effects, reversibility, or error conditions. Some transparency is present, but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main purpose. Each sentence adds value, giving parameter details and prerequisite discovery without fluff. Ideal length for a 3-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, parameter semantics for two of three parameters, and prerequisite discovery. Output schema exists so return values need not be described. It lacks side-effect disclosure and the name parameter explanation, but is otherwise complete enough for a simple create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), so the description must compensate. It explains vios_name_or_uuid (accepts PartitionName or UUID, find with hmc_vios) and physical_volumes (list of free PV names, example provided, how to find). However, the 'name' parameter is not explained, leaving one of three parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a Volume Group on a VIOS from one or more physical volumes') with a distinct verb and resource. It distinguishes from sibling tools like hmc_list_volume_groups and hmc_create_virtual_disk by describing the exact creation scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides practical guidance on finding the VIOS (via hmc_vios) and free physical volumes (via GetFreePhysicalVolumes or lspv), and explains the purpose of pooling disks for virtual disk creation. It does not explicitly mention exclusions or alternative tools, but gives clear context for when to use this operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, and the description adds valuable context by stating this is an immediate synchronous delete with no job to poll, returning a confirmation string. This goes beyond the annotation's safety warning to clarify execution mode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with zero fluff, front-loading the purpose before explaining the parameter format and synchronous behavior. Every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter delete operation, the description covers the purpose, the synchronous nature, and the vios identifier format. The output schema presumably documents the return confirmation string, so the description is complete enough. It could explicitly clarify vg_uuid, but the tool name and purpose make it predictable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no descriptions (0% coverage). The description explains vios_name_or_uuid as accepting either a PartitionName or a UUID (findable via hmc_vios), which adds meaning. However, vg_uuid is not explained, though its role is implied by the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete the Virtual Media Repository from a Volume Group,' which is a specific verb+resource+target. This distinguishes it from sibling tools like hmc_create_media_repository and other delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but it implies usage by identifying the resource to delete and instructing 'find it with hmc_vios' for the vios_name_or_uuid parameter. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already conveys the safe read-only nature. The description adds examples of resource types but provides no extra behavioral context such as pagination, error behavior, or output structure. Since the output schema exists, the lack of return details is tolerable, but no operational nuances are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and well-structured: the main action in one sentence, followed by a list of examples. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list-by-type tool with one parameter and an output schema, the description provides sufficient orientation. The examples clarify allowed values, and the output schema covers return structure. It could note that specific types have dedicated sibling tools, but that is not essential for using this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. The phrase 'List any uom resource type' and the explicit examples (ManagedSystem, LogicalPartition, etc.) effectively explain what to pass in the required resource_type parameter, compensating for the bare string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List any uom resource type exposed by the HMC' with a specific verb and object. It distinguishes itself from sibling-specific listers like hmc_systems and hmc_lpars by its generic nature, reinforced by the varied examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies general use for any resource type but does not explicitly advise when to use this over the many specific sibling tools. No exclusions or alternatives are mentioned, leaving the agent to infer that this is the catch-all for types without dedicated tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given readOnlyHint=true, the annotation already conveys safety, but the description adds substantial behavioral context: it details what each mode returns, mentions the empty `{}` result for fetch, specifies ISO-8601 UTC timestamps and ~2h retention, and lists the key structure of links output. This goes beyond the annotation and helps the agent anticipate edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a well-organized paragraph that leads with an action-oriented summary, then provides essential context and mode details. No sentence is redundant; every part adds useful information, and it remains concise given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main behaviors: listing, fetching, required parameters, timezone/retention, and the empty result case. It is slightly incomplete in that `end_ts` and `no_of_samples` are not explicitly described, and there is no mention of pagination or limits, but the presence of an output schema mitigates the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description is the only source of parameter meaning. It clearly explains `category`, `resource_name_or_uuid`, `start_ts`, and `mode` with examples and default behavior. However, `end_ts` and `no_of_samples` are not explicitly defined—only implied by 'requested range'—leaving a gap for those parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List or download processed PCM metrics JSON documents,' a specific verb-resource combination that clearly identifies the tool's function. The context about 30s granularity and ~2h retention further distinguishes it from siblings like hmc_aggregated_metrics, even though no explicit alternative is named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the purpose of the tool and the modes ('links' vs 'fetch'), which implies when to use it (when processed metrics are needed). However, it does not explicitly compare with alternative tools such as hmc_aggregated_metrics or provide exclusion criteria, so the guidance is inferred rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly warns that this modifies the LPAR configuration on the HMC, shows the exact HMC command executed via SSH, and explains the UUID resolution fallback. This is significant transparency for a mutation tool, though it does not mention permission requirements, rollback, or effect timing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose, the exact command, the UUID resolution note, and a warning. Every sentence adds value and the warning is appropriately placed for a mutating operation. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, the description covers the critical operational aspects: what it does, how it executes (SSH + REST fallback), and the risk of modifying config. It lacks guidance on valid mode values and prerequisites (e.g., LPAR state), but given the existence of sibling tools like hmc_get_proc_compat_modes and an output schema, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no property descriptions (0% coverage), so the description must compensate. It does explain that system_name_or_uuid and lpar_name_or_uuid can be CLI names or UUIDs and that UUIDs are resolved to names. However, it does not clarify valid values for 'mode', which is a critical gap. The connection to the chsyscfg command structure gives some parameter mapping, but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Set the processor compatibility mode of an LPAR.' This clearly distinguishes it from related siblings like hmc_get_lpar_proc_compat (read operation) and other setters (e.g., hmc_set_lpar_msp, hmc_set_lpar_description).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied by the tool name and first sentence, but there is no explicit guidance on when to choose this tool over alternatives like hmc_modify_lpar or when not to use it. The description does mention the underlying command and UUID resolution, which gives some operational context, but stops short of clarifying exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the underlying chsyscfg command, the append behavior, the --force flag, and the UUID-to-name resolution with REST/SSH fallback. It does not cover error conditions or permission requirements, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the purpose. It uses a code block to show the executed command and then briefly explains behavior and edge cases. Every sentence contributes, though the UUID resolution detail adds some density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, the description sufficiently covers what it does, how it executes, parameter flexibility, and the return value. It lacks explicit guidance on selecting this tool over siblings, but the operation is well-scoped and the output schema note is handled by the 'returns raw command output' statement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds value by explaining that system and LPAR can be given as name or UUID and how UUIDs are resolved, providing extra meaning for system_name_or_uuid and lpar_name_or_uuid.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Add a physical I/O slot DRC index to an LPAR's profile.' This clearly distinguishes the tool from sibling adapter tools like hmc_add_network_adapter or hmc_add_vnic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context about the operation and mentions 'Use --force to override any conflicts,' but it does not explicitly state when to use this tool versus alternatives or when not to use it. No sibling tools are referenced as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing side effects. It explicitly warns 'This creates a real account — confirm the taskrole before calling' and clarifies that password is initial and pwage controls expiration. However, it does not mention required permissions, behavior on duplicate usernames, or irreversibility, leaving some gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the primary purpose, and every sentence contributes value. It covers parameter semantics, an important side-effect warning, and the return type without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides sufficient information for a create operation: purpose, all parameter meanings, a critical side-effect warning, and return value. Since an output schema exists, the return dict mention is a bonus. It loses a point for not covering alternatives or prerequisites, but overall it is complete enough for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully by explaining every parameter: name is the login username, taskrole controls permissions with examples, password is the initial password, description is optional, and pwage is expiration in days with 0 meaning never. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new HMC local user account,' which clearly identifies the verb, the resource, and the scope (local user). It distinguishes itself from sibling tools like hmc_delete_user, hmc_modify_user, and hmc_users, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool (to create a user) and includes a caution to confirm the taskrole. However, it does not explicitly mention when not to use it or point to alternatives such as hmc_modify_user or hmc_delete_user, so guidance is more implied than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The read-only nature is already declared via readOnlyHint=true, and the description adds the useful context that clusters are sets of VIOS nodes sharing a storage pool. However, no additional behavioral traits such as return format, pagination, or filtering behavior are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'List Clusters (sets of VIOS nodes sharing a storage pool).' It contains no unnecessary words and immediately conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, a read-only annotation, and an output schema present, the description is fully adequate. It defines the key term 'clusters,' which is the only contextual information needed for this simple listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline for parameter semantics is 4. The description does not need to document parameters, and its clarification of what a cluster is adds context to the result set without being parameter-related.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('Clusters'), and defines clusters as 'sets of VIOS nodes sharing a storage pool.' This clarifies the tool's scope and distinguishes it from related siblings like hmc_shared_storage_pools and hmc_vios.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used for listing clusters, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. There is no mention of related tools or conditions that would favor this one, so usage guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, and the description adds that the migration is 'in-progress' but does not disclose side effects, reversibility, or error behavior beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-load the action and then give parameter detail with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool with an output schema and annotation, the description covers purpose and parameter enough; it doesn't elaborate on error states or return values, but that is covered elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only a bare string property, but the description clarifies that the parameter accepts either a PartitionName or UUID and tells how to find it using hmc_lpars, fully compensating for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action 'Abort an in-progress LPM migration' with a clear resource (LPAR), and the verb 'Abort' distinguishes it from sibling tools like hmc_migrate_validate_lpar and hmc_migrate_recover_lpar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when an LPM migration is in progress, but it does not explicitly mention when to use this tool versus alternatives like hmc_migrate_recover_lpar or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the operation is job-based and explains that wait=True blocks until a terminal state, which is useful behavioral context. It doesn't mention permissions or edge cases, but the core async behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear topic sentence followed by parameter guidance. Every sentence contributes value, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described. However, the description doesn't explain poll_interval and timeout_seconds or how they relate to wait. This is a notable gap for a tool with four parameters and no annotations, making it adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to system_name_or_uuid (accepts SystemName or UUID, find via hmc_systems) and wait (block until terminal state). However, poll_interval and timeout_seconds are left unexplained, and schema coverage is 0%, so the description only partially compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Power on a managed system') and identifies it as a 'PowerOn job'. This clearly distinguishes it from siblings like hmc_power_on_lpar and hmc_power_off_system, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides helpful context by telling users to find the system name or UUID with hmc_systems and explains when to use the wait parameter. It does not explicitly name alternatives or exclusions, but the context is clear enough for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It explains partial-update semantics, the implicit side effect of enabling aggregation, prerequisites for aggregated metrics, the return format, and the ValueError when no flags are supplied. This is strong coverage, though it omits potential details like permissions or other error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well organized and front-loaded with purpose, followed by parameter roles, behavioral notes, return value, and exception. Every sentence contributes necessary information, and there is no redundancy or filler. It is concise yet covers the essential aspects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex with 7 parameters, no annotations, and an output schema. The description covers partial updates, implicit dependencies, prerequisites, return format, and an exception. It does not explicitly contrast with hmc_get_pcm_preferences or detail all optional flags, but overall it provides enough context for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 'category' and 'resource_name_or_uuid' well, and notes that only supplied flags are changed. However, it fails to define the five optional flags individually (aggregation, compute_ltm, energy_monitor, long_term_monitor, short_term_monitor), leaving their specific meanings ambiguous. This is a significant gap given the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Enable/disable PCM data collection for a resource', which is a specific verb plus resource and clearly states the tool's function. It distinguishes itself from the sibling hmc_get_pcm_preferences by focusing on modification rather than retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context on when and how to use the tool: 'Only the flags you set are changed' and 'Turning on aggregation implicitly enables long-term monitoring' plus the requirement for long-term + aggregation before processed/aggregated metrics are available. It does not explicitly name alternatives, but the guidance is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint. The description goes beyond by explaining the fetch mode returns the most recent document or an empty object when no metrics are available, and notes the prerequisite about PCM preferences. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the main action. It is concise, using line breaks to separate key details, and every sentence adds value—mode behavior, parameter definitions, and a prerequisite. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are covered there. The description effectively conveys the tool's purpose, required parameters, mode semantics, fallback behavior, and a prerequisite. The only minor gap is the undocumented optional parameters, but overall it's a comprehensive description for moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 'category', 'resource_name_or_uuid', 'start_ts', and 'mode' with examples and semantics. However, it does not explain 'end_ts' or 'no_of_samples', leaving two parameters without any descriptive help, which is a clear gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists or downloads aggregated PCM metrics JSON documents. It provides concrete examples of resource types and distinguishes 'aggregated' as the long-term rollup for trend analysis, setting it apart from sibling metrics tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains the two modes (links and fetch) and which one is the default, along with the prerequisite that aggregation must be enabled. It doesn't explicitly mention alternative tools for non-aggregated metrics, but the trend-analysis context implies when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint by revealing the response includes links to managed systems and characterizing the call as cheap. It doesn't contraindicate 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose, no redundant wording. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no parameters) and has an output schema, so the description is sufficient. It covers the essential purpose and a use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the schema fully covers any inputs, and the description doesn't need to add parameter semantics. Baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets HMC version, network configuration, and links to managed systems. It uses a specific verb and resource, but does not explicitly contrast with sibling tools like hmc_systems or hmc_list_resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence explicitly frames this as a connectivity check and notes it's the cheapest HMC call, giving clear use context. It does not mention exclusions or alternative tools, but the guidance is useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the VIOS is created powered off with default settings, that it is a real partition, and warns to confirm name/system_uuid before calling. This is useful behavioral context beyond just 'create'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, and every sentence adds value: units, power state, follow-up action, and a safety warning. It is appropriately sized for the complexity and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 params, no annotations), the description covers essential context: what it creates, how to find the system, defaults, and the necessary next step (install_vios). Output schema is present, so return values are not required. It could mention job execution or validation, but it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 adds meaning for system_uuid (target managed system), memory (MiB), and procs (fractional units), but does not explain all 11 parameters. The defaults are in the schema, but relationships like min/desired/max are not clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new Virtual IO Server (VIOS) partition on a managed system, using a specific verb and resource. It also distinguishes the tool from siblings like hmc_create_lpar by specifying 'VIOS' and mentions it creates a 'real partition'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on finding the target managed system via hmc_systems and instructs to install the OS with hmc_install_vios before use. This indicates a clear prerequisite and follow-up step. However, it does not explicitly mention when not to use this tool versus alternatives like hmc_create_lpar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure. It does mention that the disk becomes backing storage and specifies capacity units, which adds some context. However, it does not disclose whether the create operation is asynchronous, what side effects occur beyond creation, or any permission/authorization requirements, leaving a transparency gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph with the core purpose first, followed by parameter-specific guidance. Every sentence carries useful information, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main workflow (create then attach), parameter discovery references, and unit specification. It does not mention prerequisites like needing a valid Volume Group state or whether the disk becomes immediately available, but for a create tool with an output schema, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining vios_name_or_uuid (accepts PartitionName or UUID, find via hmc_vios), capacity_mb (size in MiB), and vg_uuid (find via hmc_list_volume_groups). The disk_name parameter is left undefined, but three of four parameters are enriched.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the action: 'Create a Virtual Disk (logical volume) inside a Volume Group.' It uses a specific verb and resource, and the scope ('inside a Volume Group') distinguishes it from siblings like hmc_create_volume_group or hmc_map_storage_to_lpar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides contextual workflow guidance: the disk becomes backing storage to be attached to an LPAR via hmc_map_storage_to_lpar, and tells how to find vg_uuid with hmc_list_volume_groups. It lacks explicit 'when not to use' or exclusion against alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly reveals that this is an asynchronous operation ('Submits a Deploy job; poll hmc_get_job for status') and explains the wait behavior ('Set wait=True to block until the job reaches a terminal state'). This goes beyond a simple one-liner and gives the agent a clear mental model of the execution flow. It doesn't detail permissions or side effects, but the async job pattern is a key behavioral trait well covered here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a lead line stating the action, then clarification of the two required UUIDs, then the job submission/polling behavior, and finally the wait option. Each sentence adds needed context, with no fluff. It uses formatting effectively for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (async job, 5 parameters, output schema), the description is largely complete. It explains the workflow (deploy from draft template, submit job, poll, wait), clarifies the two required params, and covers the wait flag. It doesn't mention potential prerequisites like system state or template compatibility, but the output schema may capture return values, and the description suffices for an agent to select and invoke the tool correctly. A minor gap is lack of explicit exclusions, but overall it's quite solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It does for the essential parameters: draft_template_uuid is explained as the transformed/replica template UUID from capture/transform, and target_system_uuid as the managed system to create the partition on. It also adds semantics for wait=True. The remaining params (poll_interval, timeout_seconds) are conventional and self-explanatory from their names, and the description's coverage of the most critical parameters is sufficient to use the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Deploy a partition from a *draft* partition template.' This is a specific verb+resource combination that distinguishes it from siblings like hmc_partition_templates (listing templates) and hmc_create_lpar (creating an LPAR directly). The emphasis on 'draft' template further clarifies the exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context about when to use the tool (when you have a draft template and a target system) and provides operational guidance (submits a Deploy job, poll hmc_get_job, set wait=True). However, it does not explicitly mention alternatives or exclusions relative to sibling tools like hmc_provision_lpar or hmc_create_lpar. It's more than vague implication but lacks direct comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides meaningful behavior beyond the readOnlyHint annotation, including the exact lssyscfg command executed and the UUID-to-CLI-name resolution with fallback via REST and SSH. These behavioral details help the agent understand how the tool works, though it omits potential error cases or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise at four sentences, includes the crucial command example, and provides necessary parameter handling context. No redundant wording is present, though the command and fallback explanation add a bit of length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description does not need to explain return values. It covers what the tool does, how it executes, and how the input parameter is handled. It lacks explicit error scenarios or performance implications, but these are not essential given the tool's simplicity and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% coverage, and the description fully compensates by explaining that system_name_or_uuid accepts a CLI name or UUID, and that UUIDs are resolved via REST with an SSH fallback. This gives clear semantic meaning to the only parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get processor compatibility modes supported by a managed system', which is a specific verb+resource. It also names the underlying command and distinguishes this system-level query from sibling tools like hmc_get_lpar_proc_compat by referring to 'a managed system'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does and how the system parameter is resolved (CLI name or UUID), but it does not explicitly state when to use this tool versus alternatives such as hmc_get_lpar_proc_compat or hmc_get_pcm_preferences. The usage context is implied but not made explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not contradict the readOnlyHint annotation. It adds minimal behavioral context beyond the annotation: it clarifies the resource type (VLANs) and the requirement of a system identifier. However, it does not disclose any additional behavior such as filtering, pagination, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose in the first sentence. The second sentence efficiently explains the parameter with a practical pointer. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (single parameter, read-only, output schema present), the description is adequate. It covers the essential purpose and parameter usage. It does not describe the output format, but an output schema exists, so that is not required. It could benefit from noting that it lists all VLANs on the system, but this is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the single parameter system_name_or_uuid, stating it accepts either a SystemName or a UUID and where to find it (hmc_systems). This adds value beyond the schema, which has no descriptions (coverage 0%). However, the property name is already self-descriptive, so the added value is modest.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('Virtual Networks (VLANs)') with the scope ('on a managed system'). It distinguishes from sibling tools like hmc_list_virtual_switches by specifying VLANs specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to list virtual networks on a managed system. It also instructs how to find the system identifier using hmc_systems, which is practical guidance. However, it does not explicitly mention alternatives for similar list tools, such as hmc_list_virtual_switches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It explains storage_kind semantics and the optional target_device pinning, and names the vSCSI prerequisite, but does not disclose side effects, reversibility, permission needs, or asynchronous behavior. 'Map' implies mutation, yet transparency beyond that is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a structured, front-loaded paragraph followed by parameter-by-parameter explanations. Every sentence adds necessary information without redundancy, though it is longer than the minimal two-sentence style.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter tool with no schema descriptions and no annotations, the description covers all parameters, prerequisite, and sibling references. It is slightly incomplete in that it doesn't mention whether the operation returns a job or is synchronous, but an output schema exists and the operational details provided are strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully: it explains vios_name_or_uuid and lpar_name_or_uuid accept PartitionName or UUID, expands each storage_kind enum value, defines storage_name, and clarifies target_device is optional for pinning the vtscsi device name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Map backing storage to an LPAR via a Virtual SCSI mapping on a VIOS,' providing a specific verb, resource, and method. It clearly distinguishes the tool from related storage/adapter operations like hmc_create_virtual_disk and hmc_add_vscsi_adapter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a hard prerequisite: 'The LPAR must already have a vSCSI adapter paired to this VIOS — see hmc_add_vscsi_adapter.' It also points to hmc_vios and hmc_lpars for finding identifiers. It lacks an explicit when-not-to-use alternative, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the key partial-update behavior ('Only the fields you pass are changed; omitted fields are left as-is') and explains parameter effects. With no annotations, it carries the disclosure burden but notably omits operational traits like whether changes require a reboot, are asynchronous (job), or need specific permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a one-sentence summary, a clear partial-update note, then a bullet-like parameter list with no fluff. Every sentence adds value and the length is appropriate for 7 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the parameter semantics are thorough, the description lacks operational context: it doesn't mention potential job creation, whether changes are pending or applied immediately, prerequisites (e.g., system state), or error scenarios. The output schema exists, but it doesn't cover this operational behavior, leaving gaps for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains every parameter in detail, including allowed values and units (e.g., 'pend_mem_region_size: pending memory region size (MiB)', 'power_off_policy: 1 powers the system off...'). This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Modify a managed system's configuration' with a specific verb and resource, and the listed parameters (new_name, power_off_policy, etc.) confirm system-level scope. This distinguishes it from sibling modify tools like hmc_modify_lpar or hmc_modify_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear that this tool is for modifying system-level configuration, and the parameter list reinforces that context. However, it does not explicitly mention alternatives or exclusions, such as using hmc_power_on_system for power control, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the burden of disclosure. It reveals partial-update semantics, the effect of enable=True/False, and that the tool returns the updated user resource dict. It does not mention permissions or side effects, but the described behaviors are meaningful and go beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with four sentences that each add value: purpose, partial-update behavior, enable semantics, and recommended pre-check. It is front-loaded with the core verb and resource, and there is no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so the description does not need to explain return values in depth. It covers the essential aspects of a modify operation: what it does, partial-update semantics, a specific parameter behavior, and a recommended pre-call verification. Missing details like permission requirements are not critical given the output schema and sibling context, but the description could be more complete about acceptable values for fields like taskrole.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description compensates for the schema's lack of parameter descriptions by stating that only supplied fields are changed, which applies to all optional parameters. It explicitly clarifies the enable parameter's semantics. However, it does not provide additional detail for password, taskrole, or description parameters beyond what the schema's types already imply (e.g., expected formats or constraints).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool modifies an existing HMC user account, using a specific verb and resource. It distinguishes itself from sibling tools like hmc_create_user and hmc_delete_user by focusing on modification of existing users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance to use hmc_users(name=...) to confirm the current state before calling, which is a recommended prerequisite. It also implies partial-update usage ('Only the fields you supply are changed'), but does not explicitly mention when not to use the tool or compare to alternatives beyond this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It notes that slot_number is auto-assigned if omitted and that storage devices are mapped on the VIOS afterward, which adds value. However, it does not disclose whether the operation is asynchronous, requires specific permissions, or has side effects like modifying existing adapters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, then explains each parameter in a clear, sequential manner. Every sentence contributes useful information; there is no filler. The line breaks for parameters improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of adding a vSCSI adapter with dependencies on VIOS and slot numbers, the description covers the key relationships and next steps. It also references sibling tools for lookup. However, it omits important operational context like whether the operation is long-running or reversible, especially since no annotations exist to cover these aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for its 4 parameters (0% coverage), so the description fully compensates. It explains each parameter's meaning, how to obtain it (e.g., 'find it with hmc_lpars'), and clarifies the auto-assignment behavior of slot_number. This goes well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Add a Virtual SCSI client adapter to an LPAR, paired to a VIOS.' This clearly distinguishes it from sibling tools like hmc_add_network_adapter and hmc_add_vfc_adapter by specifying the adapter type and VIOS pairing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on how to find required identifiers using hmc_lpars and hmc_vios, and explains the relationship between the VIOS, slot number, and backing storage. It does not explicitly mention when not to use this tool or alternatives, but the guidance is sufficient for typical invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds value by explicitly stating that only supplied fields are changed (partial update) and that the tool returns the updated LDAP configuration resource dict. While it doesn't explicitly warn about mutating state or prerequisites like HMC admin rights, the 'Configure' verb and the partial-update note provide useful transparency beyond a bare description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the main purpose, followed by a clear parameter list. Every sentence provides information, and the examples are useful. It is slightly longer than strictly necessary, but the length is justified by the need to document seven parameters with zero schema coverage. It could be slightly more compact, but it remains efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, one required) and absence of annotations, the description is remarkably complete. It covers every parameter, describes the partial-update behavior, states the return value (which is redundant with the output schema but still helpful), and even maps it to an Ansible equivalent for cross-reference. This provides a full contextual picture for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description fully compensates by explaining each parameter in plain language with examples. For example, 'server_url is the LDAP or LDAPS URL' with concrete URL formats, and 'hmc_groups: comma-separated LDAP groups mapped to HMC access.' This adds significant meaning beyond the bare schema property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource statement: 'Configure the HMC LDAP server integration.' This distinguishes it from sibling tools like hmc_get_ldap_config and hmc_remove_ldap_config, and the specific focus on LDAP configuration leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides partial usage context by stating 'Only the fields you supply are changed,' indicating a partial update model. However, it does not explicitly say when to use this tool versus alternatives, such as mentioning that hmc_get_ldap_config should be used for viewing or hmc_remove_ldap_config for deletion. The guidance is implied but not explicitly contrasted with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains each parameter's effect in detail and states the return value ('Returns the created policy resource dict'). However, it does not disclose what happens on duplicate policy_name, whether the operation requires specific permissions, or any side effects. With no annotations, this is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a single opening sentence states the purpose, followed by a compact list of parameter definitions, a usage tip, and a closing return statement. No wasted words; everything is relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 10 parameters and no schema descriptions, the description covers all parameter semantics, the return value, and a usage caution. It lacks details on error handling or idempotency, but the presence of an output schema mitigates the need for return explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description compensates fully by explicitly defining the meaning of every parameter (pwage, min_length, hist_size, etc.) in plain language. This exceeds the baseline and adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Create a new HMC password policy.' This clearly distinguishes the tool from its siblings (modify/delete/list) and immediately states the tool's core action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (creating a new policy) and includes a practical tip: 'Confirm the policy_name before calling.' However, it does not explicitly compare with alternatives like modify or delete, so it lacks the when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It explains the PXE-boot mechanism, the job submission nature, and the wait behavior. However, it does not explicitly warn that the installation will overwrite the VIOS's existing OS, nor does it mention any permission requirements. The timeout definition is also slightly misleading given the presence of timeout_seconds.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary action, followed by a clear per-parameter explanation and a note on wait behavior. It is a bit long but every sentence carries information; no redundant fluff. The structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a 10-parameter tool with no annotations, the description covers the main workflow, prerequisites, network configuration, and how to obtain the result. It misses two parameters and leaves the timeout/timeout_seconds ambiguity unresolved. Also lacks side-effect warnings. Overall it is fairly complete but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 8 of 10 parameters (vios_uuid, nim_ip, nim_gateway, nim_subnetmask, vios_ip, vlan_id, timeout, wait) with meaningful semantics. It omits poll_interval and timeout_seconds, and does not clarify the relationship between timeout (minutes) and timeout_seconds (seconds), which is a notable gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Submit a NIM-based VIOS installation job.' It clearly distinguishes from sibling tools like hmc_install_lpar_os (for LPARs) and hmc_create_vios (for creating a partition) by focusing on installing the OS on an existing VIOS via NIM. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: vios_uuid must be an existing powered-off VIOS partition. Also states the follow-up action ('poll hmc_get_job for status') and the wait=True option to block until terminal state. It doesn't explicitly name alternative tools for similar tasks, but the context is sufficient for selecting this tool over the many siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool submits an asynchronous Migrate job, that wait=True blocks until completion states, and that the job status is polled via hmc_get_job. It also mentions optional target profile pinning and timeout behavior. It doesn't mention potential side effects like downtime, but the core behavioral traits are well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description starts with a clear one-sentence purpose, then logically flows into parameter explanations and workflow. It is somewhat long but each sentence adds value, covering asynchronicity, prerequisites, and optional waiting. It could be tightened with bullet points but is still well organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (LPAR migration with async job), the description covers the essential workflow: validate first, submit job, poll status, and optionally wait. It mentions output indirectly by telling to poll hmc_get_job. Since an output schema exists, return values needn't be explained. Missing are potential error scenarios or prerequisites like LPAR state, but overall it is a complete guide for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It explains lpar_name_or_uuid (PartitionName or UUID, find with hmc_lpars), target_system, target_profile, wait, and timeout_seconds. It also vaguely references wait_time. However, poll_interval is not described at all, and wait_time vs timeout_seconds is ambiguous, creating a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Live-migrate (LPM) an LPAR to another managed system', which is a specific verb+resource. It distinguishes from sibling tools like hmc_migrate_validate_lpar by explicitly instructing to 'Run hmc_migrate_validate_lpar first to pre-check', and from abort/recover by focusing on the migration job submission.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to live-migrate an LPAR. It gives an explicit prerequisite ('Run hmc_migrate_validate_lpar first') and explains the async workflow (submit job, poll hmc_get_job, optionally wait). However, it doesn't explicitly mention when not to use it (e.g., for validation only), which would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool modifies LPAR configuration, runs a specific HMC CLI command, performs UUID resolution with fallback, returns raw command output, and raises HMCCLIError on failure. It also issues a warning to confirm parameters. This is comprehensive and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, command details, scope boundary, return value, warning, and error raising. It uses formatting (bold, inline code) effectively and every sentence adds value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, no annotations, no schema coverage), the description covers the key aspects: what the command does, how UUID resolution works, scope limitations, return value, warning, error handling, and prerequisites. It could be more complete with per-parameter examples or allowed values, but overall it provides enough context for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 lists the supported parameters (capacity, vswitch_name, port_vlan_id, backing_devices) and clarifies backing_devices is an opaque string, plus explains that system/lpar may be names or UUIDs. However, it does not define units for capacity, valid ranges for port_vlan_id, or the meaning of vswitch_name beyond its name, leaving some param semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add a vNIC (SR-IOV-backed Virtual NIC) to an LPAR via the HMC CLI' which clearly states a specific action, target resource, and technology. It distinguishes itself from sibling tools like hmc_add_vscsi_adapter and hmc_add_vfc_adapter by focusing on SR-IOV vNIC creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: it adds an SR-IOV vNIC and notes a prerequisite (underlying adapter must be in SR-IOV mode, see hmc_set_sriov_adapter_mode). It also states what is out of scope for v1 (complex backing-device topology). However, it does not explicitly compare against alternative adapter-creation tools or state 'use this instead of...'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral details: it runs 'bkprofdata' via SSH, returns raw command output, resolves UUIDs via REST with a fallback to lssyscfg, and clarifies that the backup file is created on the HMC host. This is substantial transparency, though it doesn't address failure modes or file-overwrite behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a one-sentence purpose, the exact command, the name-resolution detail, and a bolded critical caveat. Every sentence carries essential information with no redundancy or fluff, and the most important note is visually highlighted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the command execution, output behavior, argument resolution, and the remote-path caveat. Given that an output schema exists, return-value details are not needed. It lacks explicit prerequisites or failure semantics, but for a backup CLI tool the described context is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers both parameters with clear descriptions (100% coverage). The description adds non-obvious semantics by explaining how UUIDs are resolved to CLI names and emphasizing that file_path is on the HMC filesystem, which goes beyond the schema's static field descriptions. It earns extra credit for this context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Backup') and resource ('all LPAR profiles') on a Power system via the HMC CLI, clearly distinguishing it from restore or sync operations. The underlying command and scope are explicit, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context, including that the system may be specified by name or UUID, and that the file path is on the HMC filesystem. It does not explicitly name alternative tools for restore/sync or state when not to use it, so it stops short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It discloses the async job model, result field LUCreated, and wait behavior, and explains the meaning of key parameters like cloned_from. It does not mention failure modes, permissions, or side effects, but covers the essential behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the primary purpose, and every sentence contributes useful information about workflow, parameters, or helper tools. It avoids filler and is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, no annotations, and an output schema, the description covers key semantics, job polling, and wait options. Minor gaps remain around poll_interval/timeout details and explicit prerequisites, but the description is substantially complete for operational use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by defining lu_type, device_type, cloned_from, cluster_uuid, and wait. It leaves poll_interval and timeout_seconds unexplained, but the core required and distinguishing parameters receive meaningful clarification beyond raw names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Create a Logical Unit (file-backed disk) in a Cluster/SSP.' It clearly distinguishes the tool as creating a storage logical unit rather than a VM or adapter, which fits the sibling context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: submit job, poll hmc_get_job, use LUCreated for UDID, find cluster_uuid via hmc_list_clusters, and set wait=True to block. It clearly outlines the asynchronous workflow, though it does not explicitly contrast with hmc_create_virtual_disk or other similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the operation is immediate and returns a confirmation string (no job to poll), which goes beyond the 'destructiveHint' annotation. It also exposes a critical dependency/constraint regarding NetworkBridges and trunk adapter PVIDs, adding meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and includes purpose, parameter guidance, a usage note, and return behavior in a few sentences. It is well-structured and front-loaded with the core purpose, though the note about PVIDs adds a slightly dense clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the presence of an output schema, the description covers essential aspects: what it does, how to specify the system, a critical deletion constraint, and the immediate response format. No critical context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description is the only source of parameter meaning. It explicitly explains system_name_or_uuid (accepts SystemName or UUID, find it via hmc_systems), but network_uuid is left to the reader's inference from the tool name and the mention of virtual network deletion. This is acceptable but not fully compensatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear and specific verb-object combination: 'Delete a Virtual Network from a managed system.' This unambiguously distinguishes the tool from sibling tools like hmc_create_virtual_network or hmc_list_virtual_networks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear precondition: a network referenced by a NetworkBridge or equal to a trunk adapter's PVID cannot be deleted until the bridge is removed. It also suggests hmc_systems as a way to find the system_name_or_uuid, giving useful context for when to use this tool. It does not explicitly name alternative deletion tools, but the given guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and covers important behavioral details: memory values are in MiB, only passed fields are changed, and the RMC connection condition yields profile-only changes without a reboot. It does not disclose permissions, error cases, or return behavior, but the core side effects are well explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences, each adding distinct value: purpose, parameter flexibility, units/update behavior, and RMC caveat. No filler or repetition; it is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex with a conditional behavior profile, and the description covers the key operational context (running LPAR, profile-only fallback, units, partial updates). An output schema exists, so return values are not the description's responsibility. Missing prerequisites like required permissions or HMC version are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining lpar_name_or_uuid (PartitionName or UUID) and that memory values are in MiB, with only passed fields being changed. It does not individually describe min_memory, max_memory, and desired_memory, but their meaning is standard and the null default is clarified by the 'only fields you pass are changed' statement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'DLPAR memory hot-plug: change memory resources on a running LPAR,' which names the specific verb (change/hot-plug) and resource (memory on an LPAR). This clearly distinguishes it from the sibling tool hmc_dlpar_proc (CPU) and other LPAR modification tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use the tool ('on a running LPAR') and the conditional RMC connection behavior. However, it does not explicitly name alternatives like hmc_dlpar_proc for CPU or hmc_modify_lpar for general changes, so some ambiguity remains for an agent deciding among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses filtering thresholds (free memory and processor units), sorting order, and the output structure via reference to hmc_capacity_report. This is useful behavioral context. It does not describe error conditions or edge cases, but for a read-only query that is not a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the main purpose, and contains no fluff. Every clause adds necessary information about inputs, behavior, or output. The formatting with asterisks around parameter names is clear and unobtrusive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, inputs, selection criteria, sorting, and output contract (by referencing hmc_capacity_report). Given its low parameter count and presence of an output schema, this is nearly complete. It does not specify what happens when no system matches, but that is a minor omission for a read-only lookup. The cross-reference to hmc_capacity_report effectively reuses existing documentation, making the description self-sufficient enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates by explaining that desired_memory_mb and desired_proc_units represent the required free resources. It gives units (MiB, processor units) and clarifies that they are lower bounds for acceptance. It does not mention the default value for desired_proc_units, but the schema already includes that. Overall, the prose adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action—'Find managed systems that can host a new LPAR'—and clearly identifies the resource (managed systems) and the purpose (placement for an LPAR of given size). It distinguishes itself from siblings like hmc_find_system and hmc_capacity_report by focusing on placement feasibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (finding placement for a new LPAR) and explains the filtering and sorting criteria. It does not explicitly name alternatives or exclusions, but the context is clear enough that an agent would know when to invoke it. The cross-reference to hmc_capacity_report for output fields also hints at a relationship without providing explicit when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true. The description adds meaningful behavioral context: the exact HMC CLI command executed, the parsed return fields (lpar_name, slot_num, wwpns, remote_lpar_id), and UUID resolution behavior with REST/SSH fallback. These details go well beyond the annotation and help the agent anticipate side effects and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three paragraphs, each sentence earns its place: purpose, underlying command and return fields, UUID resolution, optional parameter, and helper tools. No redundant or vague phrases; it is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (HMC CLI, UUID resolution, optional filtering) and the presence of an output schema, the description is quite complete. It covers the command, return fields, resolution behavior, and optional parameter. Minor omissions like error handling or permission requirements are acceptable because the readOnlyHint annotation and output schema already cover some context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully carries parameter meaning. It explains that system_name_or_uuid accepts either CLI name or UUID, and lpar_name_or_uuid is optional to restrict results to a single partition. This is enough to invoke correctly, though it does not specify format constraints or exact UUID syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'List Virtual Fibre Channel (NPIV) adapters for a managed system via the HMC CLI.' This clearly distinguishes it from sibling tools like hmc_list_adapters or hmc_list_virtual_switches by naming the exact resource type and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to list NPIV adapters, with an optional filter to a single partition. It also references helper tools (hmc_systems, hmc_lpars) for finding UUIDs. However, it does not explicitly state when not to use it or name alternative tools for similar tasks, so it stops short of full differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains partial updates ('Only the fields you pass are changed'), memory units (MiB), dynamic vs static behavior, RMC requirement, and the dedicated flag semantics. It does not mention error handling, permissions, or possible asynchronous job responses, but covers the key operational behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, starts with a clear purpose, and each sentence adds meaningful detail without redundancy. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex 13-parameter tool with no annotations, but an output schema exists so return values need no explanation. The description covers identifier resolution, units, partial updates, dynamic vs static behavior, and dedicated/shared modes. It does not elaborate on every min/max/desired parameter, relying on naming conventions, which is acceptable given the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), so the description must compensate. It explains lpar_name_or_uuid accepts either a name or UUID, memory values are in MiB, dedicated toggles dedicated vs shared CPUs, and omitting dedicated leaves sharing mode unchanged. Other parameters (min_procs, desired_memory, etc.) are not individually explained but their names are self-explanatory in context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Modify an LPAR's name and/or resource assignment (memory / CPU).' It distinguishes from siblings like hmc_dlpar_proc and hmc_dlpar_mem by covering both name and resource changes, not just one resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when changes are dynamic (running partition, requires RMC) versus applied on next activation, and directs users to hmc_lpars for finding the LPAR identifier. It does not explicitly name alternatives like hmc_dlpar_proc/mem, so it lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It states that only supplied fields are changed (partial update) and that activation/deactivation is not a direct field change but requires a PolicyType=status query path via the console. This is significant added context. However, it does not mention required permissions, error conditions, or reversibility, which would make it more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three sentences, with each sentence adding distinct value: purpose, partial-update behavior, prerequisites, activation exclusion, and return value. It is well-structured, front-loaded with the purpose, and contains no filler or redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 parameters and no schema descriptions, the description provides essential context: how to use it safely (list first), what it changes, and what it cannot do. The output schema exists, so return details are covered externally. It could be more complete by mentioning validation rules or prerequisites, but for a modify operation it covers the key contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% parameter description coverage, so the description must compensate. It does convey the key semantic that omitted fields are not changed, which is critical for the optional parameters. However, it does not describe individual parameters (e.g., pwage, hist_size, min_length) or their valid ranges/constraints. The parameter names are suggestive but not fully defined, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Modify an existing HMC password policy.' This is a specific verb+resource combination that clearly distinguishes it from sibling tools like hmc_create_password_policy, hmc_delete_password_policy, and hmc_list_password_policies. It also clarifies that only supplied fields are changed, reinforcing the modify intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use hmc_list_password_policies to confirm the current state before calling, which is a direct usage guideline. It also states that to activate or deactivate a policy, the HMC console must be used instead, providing a clear exclusion and alternative. This is exactly the kind of when-to-use vs when-not-to-use guidance needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation is true, and the description adds critical behavior by stating that 'immediate skips graceful shutdown,' warning about abrupt termination risks. It also discloses that wait=True blocks until a terminal state, providing insight into job execution behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise, with two short paragraphs that front-load the core purpose in the first sentence. Every sentence adds necessary information—behavior, identifiers, and wait behavior—without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with 5 parameters, the description covers key aspects: graceful vs immediate shutdown, identifier format, and wait behavior. It leaves poll_interval and timeout_seconds unexplained, but those are self-explanatory from their names, and the output schema handles return values. This is adequate for an experienced HMC user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly defines vios_name_or_uuid as accepting either a PartitionName or a UUID, which adds clarity beyond the schema's plain string type. It also explains wait and immediate semantics, though poll_interval and timeout_seconds are left to inference. This is helpful given the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Power off a VIOS' with a specific verb and resource, and also clarifies the operation type as a 'PowerOff job'. It distinguishes from sibling tools like hmc_power_off_lpar and hmc_power_off_system by explicitly targeting VIOS.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by naming the resource VIOS, which naturally separates it from LPAR and system power-off tools. It explains the wait parameter's purpose, but does not explicitly mention when not to use this tool or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden, and it does well: it discloses that the tool modifies real state, warns to confirm the target, explains the already_running short-circuit, and describes force and wait behavior. It doesn't cover all edge cases (e.g., error responses), but the key behavioral traits are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but each sentence adds value: main action, parameter guidance, safety warning, special-case behavior, and wait option. It is front-loaded with the action and structured logically, though slightly verbose in the middle.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the input essentials, the output (returns the job, already_running dict), and important warnings. It doesn't mention poll_interval or error handling, but the output schema and sibling context help fill gaps. Overall adequate for a mutation tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description directly explains the critical parameter lpar_name_or_uuid (accepts name or UUID) and describes force and wait semantics. It also mentions timeout_seconds indirectly via wait. This adds substantial meaning beyond the bare schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Submit a PowerOn job for a logical partition.' It clearly distinguishes this from sibling tools like power_off_lpar or power_on_system, and the mention of lpar_name_or_uuid clarifies the target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: confirm target with hmc_lpars, check status with hmc_get_job, and warnings about changing real state. It doesn't explicitly state alternatives or exclusions (e.g., when not to use this vs. power_on_system), but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly warns that the operation modifies LPAR configuration, states it runs via SSH, and discloses the UUID resolution fallback from REST to SSH. This is more transparent than typical setter tools, though it doesn't cover permissions or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, the command invocation, a brief note on UUID resolution, and a warning. Every sentence contributes necessary information without redundancy, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers the essential context: what it does, how it works (SSH command), how parameters are resolved, and that it mutates configuration. It could mention prerequisites or failure cases, but for a focused setter tool, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the schema by showing the underlying CLI command with placeholders: "name=<lpar_name>,msp=<0|1>". This maps the three schema parameters (system_name_or_uuid, lpar_name_or_uuid, enabled) to the command's system name, lpar name, and msp flag respectively. It also clarifies that UUIDs are resolved to CLI names, which explains parameter flexibility.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: "Set the MSP (Migratable Service Partition) flag of an LPAR via the HMC CLI." This clearly distinguishes it from the sibling getter hmc_get_lpar_msp and other set-type tools. It also mentions the exact HMC command, reinforcing the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for setting the MSP flag, and the warning to confirm parameters before calling offers practical usage guidance. However, it does not explicitly mention when not to use it or name alternatives, so it lacks the explicit exclusions of a top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the underlying chhwres command via SSH, raw output return, UUID resolution with REST/SSH fallback, and a prominent WARNING about affecting all partitions using virtual functions on the adapter. It stops short of covering permission requirements, reversibility, or failure modes, but the essential behavioral traits are well captured.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: a clear summary sentence, command detail, UUID resolution, parameter explanations in bullets, and a warning. It is somewhat long but every sentence contributes necessary information—especially the warning and resolution details. No wasted words, though the command snippet could be considered optional given the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a configuration-toggle tool, the description covers purpose, parameters, execution method, output format, and risk warning. It also provides integration context (adapter_id source). An output schema exists, so return-value documentation is covered elsewhere. Minor omissions around permissions and whether a reboot is required prevent a perfect score, but it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero property descriptions (0% coverage), so the description must compensate. It does so thoroughly: adapter_id is explained as the physical adapter identifier from hmc_list_io_slots, mode maps each enum value to its meaning ('sriov' => enable, 'dedicated' => disable), and system_name_or_uuid explains the CLI name or UUID resolution process. All three parameters are given meaningful context beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific, unambiguous statement: 'Toggle a physical SR-IOV adapter between SR-IOV and dedicated mode.' It names the exact resource (physical SR-IOV adapter) and the verb 'toggle' with two clear mode values. This distinguishes it from sibling adapter tools like hmc_add_network_adapter or hmc_delete_adapter, which handle different adapter operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: to switch an SR-IOV adapter between modes, with explicit prerequisites (adapter_id from hmc_list_io_slots) and mode options. However, it does not explicitly state when not to use it or mention alternatives such as hmc_run_command, so it falls short of the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that a job is submitted asynchronously, that hmc_get_job should be polled, and that wait=True blocks to terminal state. It also clarifies the semantic difference between update and upgrade. It does not mention potential system disruption or permission requirements, but the asynchronous nature and polling expectation are useful behavioral disclosures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-structured with line breaks separating the main purpose, parameter clarifications, and wait behavior. Every sentence adds value; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, nested repository object, async job submission) and the presence of an output schema, the description covers the key workflow: how to identify the VIOS, choose update vs upgrade, describe the repository, submit the job, and optionally wait. It references sibling tools for lookup and polling. It falls short only by omitting any prerequisite checks or potential side effects, but the essential context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is only 17% (only the repository object has an inline description). The tool description compensates by explaining vios_name_or_uuid (PartitionName or UUID, find via hmc_vios), kind ('update' vs 'upgrade'), and repository (same format as hmc_hmc_update). It also explains wait=True. However, poll_interval and timeout_seconds are not elaborated beyond their defaults, though their names are self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Submit a VIOS software update or upgrade job' with a specific verb and resource. It explicitly distinguishes between 'kind=update' (PTF fixes) and 'kind=upgrade' (full version upgrade), and the name itself contrasts with sibling tools like hmc_hmc_update and hmc_install_vios. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: references hmc_vios to find the vios_name_or_uuid, hmc_get_job for polling status, and hmc_hmc_update for the repository format. It explains wait=True behavior. However, it does not explicitly state when NOT to use this tool or directly compare with alternatives, stopping short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description explains the derivation process: listing all managed systems and fetching LPAR lists to compute assigned resources, and defines free as total minus assigned. This adds meaningful behavioral context about multi-step computation and formula.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the output summary and followed by the computation method. Every sentence adds value with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only report with an output schema, the description fully covers what the tool does, what it outputs, and how the data is derived. It is self-contained and sufficient for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, so there are no parameter semantics to explain. The description does not need to add parameter details; baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool produces a capacity report for each managed system, detailing total/assigned/free memory and processor units plus LPAR counts. This specific verb+resource+scope distinguishes it from sibling tools like hmc_systems (which lists systems) and hmc_lpars (which lists LPARs individually).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when an aggregated capacity overview across managed systems is needed. It does not explicitly name alternatives or exclusions, but the specific output scope makes the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses the asynchronous nature of the delete, that it submits a job and returns it, and that one should poll hmc_get_job. It also explains the wait=True blocking behavior and the existence of poll_interval/timeout parameters implicitly. This adds meaningful behavioral context not required by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences total, front-loaded with the primary action, then clarifying async behavior and wait option. Every sentence adds value and there is no fluff. It is concise yet informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the complete workflow: submitting an async job, returning it, polling for status, and optionally waiting for terminal state. It distinguishes from immediate delete tools and references the associated monitoring tool (hmc_get_job). Given the output schema exists, return values do not need explanation, making this sufficiently complete for a delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden. It explains that lu_udid is the UDID, cluster_uuid relates to the Cluster/SSP, and wait=True blocks until terminal state. However, poll_interval and timeout_seconds are not explicitly described, leaving the agent to infer their meaning from names. Partial compensation, but not full.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a Logical Unit from a Cluster/SSP by its UDID', using a specific verb and resource. It distinguishes this from sibling delete tools like hmc_delete_lpar or hmc_delete_adapter by naming the logical-unit context (Cluster/SSP) and the UDID identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use this tool: it is asynchronous ('Submits a DeleteLogicalUnit job and returns it') and explicitly contrasts with 'immediate delete tools'. It also mentions polling with hmc_get_job and the wait=True option, giving clear usage guidance without naming alternatives explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the responsibility and does so thoroughly. It discloses that only passed fields are changed, explains the fractional vs integer semantics for procs/vcpus, clarifies the dedicated parameter controls sharing mode, and reveals the profile-only behavior when RMC is inactive. This is rich, non-obvious behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: it leads with a one-sentence purpose, then a parameter-semantics paragraph, and finishes with a behavioral note about RMC. Every sentence contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 9-parameter schema, no annotations, and an output schema that covers return values, the description provides essential context: purpose, key parameter distinctions, and the critical RMC edge case. It is complete enough for an agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 lpar_name_or_uuid, distinguishes procs (fractional) from vcpus (integer), and clarifies the dedicated flag. However, it does not individually describe max_procs, min_procs, desired_procs, max_vcpus, min_vcpus, desired_vcpus, or uncapped, leaving some parameter semantics under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description immediately states 'DLPAR processor hot-plug: change CPU resources on a running LPAR', which clearly identifies the verb (change), resource (CPU resources), and scope (running LPAR). This distinguishes it from the sibling hmc_dlpar_mem (memory) and other LPAR modification tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for changing CPU resources on a running LPAR. It also explains the behavioral implication of an inactive RMC connection (profile-only change). However, it does not explicitly mention alternatives like hmc_modify_lpar or hmc_dlpar_mem, so it lacks direct exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=true. The description adds the exact-match behavior and the return contract (full system dict or None), helping the agent know what to expect for found and not-found cases. It does not discuss pagination or authentication, but for a simple read-only lookup this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the action and resource, and avoids filler. The phrase '(exact match)' adds crucial specificity without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only lookup with an output schema, the description covers purpose, parameter semantics, and return value normalization. It is sufficient for an agent to select and invoke correctly without further context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines only a required string 'name' with no description (0% coverage). The description clarifies that 'name' refers to the SystemName and must be exact, adding critical meaning beyond the schema's generic label.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Find' with the resource 'managed system' and the exact matching criteria 'by its SystemName (exact match)'. This clearly distinguishes it from list tools like hmc_systems and summary tools like hmc_system_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for when you have a specific SystemName and need the full system dict, as opposed to listing all systems. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds concrete behavioral context: it says 'Issues a GET to the ManagementConsole resource with the SoftwareUpdate group' and explicitly states 'Does not submit a job.' This goes beyond the annotation by describing the underlying mechanism and reinforcing the no-side-effect behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, with only three sentences. It front-loads the core purpose and then provides mechanism and parameter context. Every sentence earns its place, with no repetition of schema fields or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description is complete. It explains what the tool does, how it works, and where the input comes from. The output schema eliminates the need to describe return values. The sibling list confirms the tool fits into a larger update workflow, and the description provides enough context to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines console_uuid as a string with no description (0% coverage). The description adds critical meaning by stating 'console_uuid is the ManagementConsole UUID (from hmc_console_info).' This tells the agent where to obtain the value, effectively compensating for the schema's lack of detail. It could have included format or example, but the provided context is sufficient for a simple identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence uses a specific verb and resource: 'Get available PTFs (fixes) for the HMC software.' This clearly distinguishes it from sibling update tools like hmc_hmc_update, which apply fixes. The addition of 'Does not submit a job' further clarifies that this is a read-only query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it is for retrieving available fixes without performing an update. The phrase 'Does not submit a job' signals that this is not for applying updates, but it does not explicitly name alternatives or provide when-not-to-use guidance beyond this. The note about console_uuid coming from hmc_console_info gives a clear prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the safe read behavior is covered. The description adds valuable context: it returns a single resource dict with specific fields, and returns None when no LDAP is configured, which goes beyond the annotation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose followed by a clear return-value explanation and an Ansible equivalence note. Every sentence earns its place; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params), the presence of an output schema, and the readOnlyHint annotation, the description is complete. It covers the return value content, the None case, and the Ansible mapping, making it sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is empty with 100% coverage, so the baseline for parameter semantics is 4. The description adds no parameter details, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a clear specific verb+resource: "Get the current HMC LDAP server configuration." It distinguishes from sibling tools like hmc_configure_ldap and hmc_remove_ldap_config by focusing on retrieval, and further clarifies by describing the returned resource dict or None.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the tool's role as a read-only getter with "Get the current...", which implies usage whenever the current LDAP config is needed. It also references Ansible's hmc_user state=ldap_facts, giving existing users a familiar context. However, it does not explicitly name alternatives or exclusions, like "use hmc_configure_ldap to modify."
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses the exact command executed, the resolution process from UUID to CLI name via REST with SSH fallback, and the return format. This provides rich behavioral context that annotations alone do not convey, such as the fallback mechanism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences that front-load the purpose, then provide command details, and finally the return value. Every sentence contributes useful information without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, input semantics, execution method, and return value, which is comprehensive for a read-only getter. However, it does not mention potential error conditions or when to avoid using this tool, and it does not reference sibling tools for similar functionality. With the output schema and annotations, this is mostly complete but leaves minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions for its two parameters (schema coverage 0%). The description fully compensates by explaining that both system and partition can be provided as CLI names or UUIDs, and that UUIDs are resolved before execution. This adds essential meaning to the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get the current and pending processor compatibility modes for an LPAR.' It uses a specific verb (Get) and resource (processor compatibility modes for an LPAR), and the underlying command is specified. This distinguishes it from other HMC tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to retrieve processor compatibility modes for a specific LPAR), but it does not explicitly mention alternatives or exclusions. For example, sibling tools like 'hmc_get_proc_compat_modes' could be related, but no comparison is made. The usage context is clear but not contrasted with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool submits an asynchronous job (requiring polling) and explains wait behavior, and gives detailed repository format examples. It does not explicitly warn about potential HMC downtime or reversibility, but it provides substantial behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is multi-paragraph but tightly packed; every sentence adds information about mode, repository types, job polling, or wait behavior. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a nested repository object and 6 parameters, the description covers the key decision points: mode selection, repository structure, source of console_uuid, and asynchronous job handling. Output schema exists, so return values don't need explanation. It is comprehensive enough to let an agent invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, so the description must compensate. It does so by explaining 'kind' values, illustrating 'repository' with three concrete examples, and clarifying 'console_uuid' origin from hmc_console_info and 'wait' semantics. It does not discuss 'poll_interval' or 'timeout_seconds', but these have defaults and are less ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Submit an HMC software update or upgrade job,' a clear verb+resource statement. It further distinguishes two modes (kind='update' installs PTFs; kind='upgrade' performs a full HMC version upgrade), making it distinct from sibling tools like hmc_vios_update or hmc_update_firmware.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use 'update' vs 'upgrade' and describes repository types with concrete examples. It also instructs to poll hmc_get_job for status and mentions 'Set wait=True to block until the job reaches a terminal state,' providing clear context for asynchronous operation. However, it doesn't explicitly name alternative tools for VIOS or firmware updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals safety. The description adds behavioral detail by explaining what each policy_type value returns and specifying the per-policy dict structure ({UUID, title, link, ResourceType, Resource}), which goes beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs: one sentence states purpose, the next explains the parameter and return format. No redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameter behavior, and return shape for the default mode. The 'status' return is described only as 'activation status' without its structure, but since an output schema exists, this is a minor gap. Overall sufficient for a simple read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only an enum and default without descriptions (0% coverage). The description fully compensates by defining the two allowed values and their effects, plus the default choice and return structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List HMC password policies,' a specific verb+resource statement. It further explains the policy_type parameter that selects between list and status modes, distinguishing it from other list operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by naming the resource but does not explicitly state when to use this tool versus other list tools or alternatives like create/modify/delete password policies. No exclusionary guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses the exact command executed (lshwres), the transport method (SSH), the return structure (one dict per vNIC), and the UUID resolution process with REST fallback to SSH. This adds significant behavioral context, though it does not mention potential failure modes or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear purpose statement, then relevant technical details, return field examples, and input resolution notes. It is slightly lengthy due to the verbose command line, but every sentence contributes useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with an output schema, the description covers all critical aspects: what it lists, how to invoke it, how inputs are normalized, and what fields to expect. It also references companion tools for discovering identifiers, making it self-contained for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no parameter descriptions, but the description compensates fully: it explains that both system_name_or_uuid and lpar_name_or_uuid accept either a CLI name or a UUID, and that UUIDs are resolved to names before execution. It maps the parameters to the underlying command and points to related tools for finding valid UUID values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List vNICs (SR-IOV-backed Virtual NICs) on an LPAR via the HMC CLI,' which clearly states the verb, resource, and scope. It distinguishes itself from sibling tools like hmc_add_vnic and hmc_remove_vnic by specifying a list operation on a particular resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool to list vNICs on a specific LPAR. It also gives prerequisite guidance by pointing to hmc_systems and hmc_lpars for finding UUIDs, and explains the accepted input formats (name or UUID). It does not explicitly discuss alternatives or when-not-to-use, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as readOnlyHint=true. The description goes beyond by describing the output structure (free space in MiB, physical volumes, virtual disks) and the parameter format (PartitionName or UUID). It does not mention error conditions or performance, but read-only safety is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with front-loaded purpose. The parameter explanation and output details are each separated cleanly, with no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with one parameter and an output schema, the description covers the tool's action, input semantics, and key output attributes. It gives enough context to select and invoke the tool correctly, though it could briefly mention that it returns an empty list if no volume groups exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only lists the parameter name with no description (0% coverage). The description compensates by explaining that vios_name_or_uuid accepts either a PartitionName or UUID and points to hmc_vios for retrieval. This adds essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List Volume Groups on a VIOS,' which is a specific verb and resource. It also states what each volume group shows (free space, physical volumes, virtual disks), clarifying the tool's scope. This distinguishes it from sibling tools like hmc_create_volume_group or hmc_create_virtual_disk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear prerequisite: the parameter can be found via hmc_vios, which tells the agent how to obtain the required input. It implies the use case—inspecting volume group capacity and configured storage—but does not explicitly name alternative tools or when not to use it. This is sufficient context, though it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint, and the description adds the return behavior: list of all templates, full config dict, or None if not found. This tells the agent what to expect, which is especially valuable without an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and logically organized: first the overall action, then the two conditional behaviors in separate sentences. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool, it covers list vs single retrieval and the not-found case. The only minor gap is that the shape of the list items isn't explicitly stated (e.g., names vs summary dicts), but overall it's complete enough for use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 0%, the description carries the full burden. It precisely explains that omitting template_uuid yields a list, while providing it yields a single config or None. This fully defines the parameter's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource pairing: 'List partition templates or get one by UUID.' It distinguishes two modes and names the resource precisely. The sibling hmc_deploy_partition_template is clearly a different operation, so no confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It outlines when to omit vs provide template_uuid, which tells the agent exactly how to request a list vs a single template. It doesn't explicitly name alternatives like hmc_deploy_partition_template, but the usage context is clear for a read-only lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It states that preconditions are always validated first, explains the dry_run result format, explicitly reports partial-failure statuses ("ok", "error", "skipped"), and clearly warns that no automatic rollback occurs, directing the user to clean up manually with hmc_delete_lpar / hmc_delete_adapter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with a one-sentence summary, followed by concise behavioral details. Every sentence earns its place: no filler, clear bolded emphasis on important caveats, and no repetition of schema-provided parameter definitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 17-parameter orchestration tool with no annotations but an output schema, the description is sufficiently complete. It explains the end-to-end flow, preconditions, dry-run behavior, failure reporting, and rollback expectations. The presence of an output schema means return-value details need not be spelled out, and the cleanup guidance covers the main follow-up actions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 82%, so the schema already documents most parameters in detail. The description adds some context around dry_run=True and its result structure, and it ties the precondition checks to parameters like port_vlan_id and vg_uuid, but it does not substantially enrich parameter meaning beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: "Provision a new LPAR end-to-end" and enumerates the exact steps (create, add network adapter, add vSCSI adapter, map disk storage, power on). It clearly distinguishes itself from sibling single-step tools like hmc_create_lpar, hmc_add_network_adapter, and hmc_power_on_lpar by emphasizing the orchestrated, single-call nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes clear context for when to use the tool: when you want a full LPAR provisioning sequence in a single call, including precondition validation. It also documents the dry_run mode for checking preconditions only. However, it does not explicitly name the individual sibling tools as alternatives or state when NOT to use this tool, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds value by disclosing return structure ('list of parsed job dicts with at minimum JobID and Status') and ordering behavior ('most recent first'). It also clarifies the limit behavior. This is helpful context beyond the annotation, justifying a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loads the main action, and adds no fluff. Every sentence contributes: purpose, return format, and usage. This is a model of concise yet informative tool descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional param, read-only annotation, output schema present), the description covers purpose, usage, and return shape. It doesn't need to explain fields like JobID or Status further because they are presumably in the output schema. It is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lists only 'limit' with a default, but schema_description_coverage is 0%. The description compensates by explaining the parameter's semantics ('up to *limit* entries') directly in the first sentence, giving meaning beyond type/default. It doesn't elaborate on edge cases, but for a single optional param this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'List recent HMC jobs' with specific ordering ('most recent first') and a limit parameter, distinguishing it from sibling tools like hmc_get_job (single job) and hmc_wait_for_job (status polling). It names the resource and the verb precisely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear use case ('Useful for auditing recent HMC activity') and mentions categories (power ops, firmware updates, migrations). It does not explicitly name alternatives or when not to use, but the context from siblings and the description imply this is the list-jobs entry point. A stronger exclusion might earn 5, but this is above baseline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses that the operation 'overwrites the previous profile definition,' warns to confirm identifiers, explains the command executed, and details the UUID-to-name resolution process with fallback behavior. This adds substantial behavioral context not captured in structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but information-dense, with each sentence serving a purpose: defining the action, showing the command, stating the overwrite risk, providing a warning, and explaining resolution logic. No redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive sync operation, the description covers the operation, command, side effects, parameter handling, and output (raw command output). With good annotations and full schema coverage, this is complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover both parameters fully, but the description adds important semantic context: that names or UUIDs are accepted and that UUIDs are resolved via REST or SSH fallback. This enriches understanding beyond the schema's basic field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Sync an LPAR's running configuration back to its current profile.' It specifies the action, resource, and target, and includes the exact HMC command executed. This distinguishes it from sibling tools like hmc_backup_lpar_profiles and hmc_modify_lpar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to persist running config to a profile) and provides a warning, but it does not explicitly contrast with alternatives or state conditions when not to use it. There is no mention of sibling tools or exclusions, leaving usage context implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds meaningful behavior beyond that: it states that omitted system_name_or_uuid returns a list with UUID, SystemName, State, MTMS, IPAddress, etc.; provided returns full details dict or None; state filtering uses the HMC server-side search endpoint. This gives useful runtime context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose, then structured as clear conditional paragraphs. Every sentence provides necessary operational detail—list fields, single-item return, None case, state filtering—without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 0% parameter schema coverage, the description fully compensates by describing return types (list, dict, None), entry fields, and the state filter behavior. It is complete for a read-only lookup tool across its three modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden for both parameters. It explains system_name_or_uuid with its two modes (list vs. get by name/UUID) and state with its filter behavior when system_name_or_uuid is omitted. The only minor gap is that state values are not enumerated or formatted, but the semantics are clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'List all managed systems or get one by name or UUID.' It clearly distinguishes between list-all and get-one behavior, and the parameter-dependent modes are explicit. This differentiates it from siblings like hmc_find_system and hmc_system_summary by scoping it to systems listing/detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use context by explaining behavior for each parameter combination: omit system_name_or_uuid to list, provide it to get one, and combine state with omission to filter. It does not explicitly mention alternatives or exclusions, but the conditional usage is well specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already marks this as a safe read, and the description adds meaningful behavior: accepts either PartitionName or UUID, returns vSCSI/NPIV/virtual optical mappings, and uses the HMC server-side search endpoint for state filtering. It does not mention pagination or output shape, but adds substantial context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose sentence and then organized into conditional 'When...' paragraphs. Each sentence adds necessary parameter behavior or constraints; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the two return shapes (list of VIOS entries vs device mapping facts) and all parameter interactions. It could be more complete by specifying the fields in the VIOS entries or error conditions, but it is otherwise solid for a read-only list/detail tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully explains all three parameters: vios_name_or_uuid selects a specific VIOS, system_name_or_uuid restricts the list, and state filters by PartitionState with explicit interaction rules. This completely compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'List Virtual I/O Servers or get storage-detail mappings for one.' It clearly distinguishes two modes and the resource (VIOS), differentiating it from sibling tools like hmc_lpars or hmc_systems.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong conditional usage guidance: when vios_name_or_uuid is provided, get mappings; when omitted, list all; system_name_or_uuid restricts; state filters only when vios_name_or_uuid is omitted. It does not explicitly name alternatives but gives clear context and an exclusion rule ('state filter is ignored').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses important behaviors: it polls until terminal state, returns the final job entry, and if timeout_seconds elapses, returns the last-seen entry regardless of status, advising to check the Status field. This is valuable context that is not present in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences deliver the core purpose, return behavior, and timeout handling without repetition or filler. The most important information (what it does) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a polling tool with an output schema, the description covers the essential behavior: terminal states, return value, and timeout semantics. It provides enough context for an agent to invoke it correctly and interpret results, especially with the output schema available.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions (0% coverage), so the description must compensate. It explains timeout_seconds behavior clearly, but job_uuid and poll_interval are only implied by context and naming. The description adds some semantic value but does not fully cover all three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool polls an HMC job until a terminal state (COMPLETED / FAILED / EXCEPTION) and returns the final job entry. This distinguishes it from related siblings like hmc_get_job and hmc_recent_jobs, which are for single retrieval or listing rather than waiting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this tool is used to wait for asynchronous HMC job completion, with explicit timeout behavior. It implies when to use it (when you need to block until a job finishes) but does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well. It discloses critical behavioral traits: DLPAR/RMC requirements for running LPARs, auto-assignment of slot numbers, auto-generation of MAC addresses, and the meaning of tagged mode. This provides operating knowledge beyond what the schema reveals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized, front-loaded with the purpose, and every sentence provides functional value. It is structured as a compact paragraph with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core operation, parameter meanings, and key constraints, with an output schema presumably handling return values. The DLPAR/RMC caveat adds important operational context. The only notable omission is the virtual_switch_id parameter explanation, but overall the tool is well-understood for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining most parameters: lpar_name_or_uuid (with a pointer to hmc_lpars), port_vlan_id (with VLAN/vSwitch context), slot_number (auto-assign if omitted), tagged, and mac_address. However, virtual_switch_id is not explicitly described, leaving a gap for that optional parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add a Virtual Ethernet (client network) adapter to an LPAR,' which clearly states the action and target. It differentiates from sibling adapter-add tools (vscsi, vfc) by specifying the adapter type and referencing virtual network attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (attaching an LPAR to a virtual network) and a key conditional guideline: modifying a running LPAR is a DLPAR operation requiring active RMC. It doesn't explicitly compare against alternatives, but the scope is unambiguous enough for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the execution method (SSH command), the exact CLI call, the data source for vios_uuid, the accepted backup_type values, and the output behavior (raw CLI output). It lacks explicit side effects or permission requirements, but covers the main behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose, uses a code block for the command, and a bullet list for enum values. No wasted words; every sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a backup creation tool, the description provides the command, parameter meanings, output behavior, and follow-up step (polling list_vios_backups). Even with an output schema present, it is self-sufficient and complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description fully compensates. It explains vios_uuid (VIOS UUID from hmc_vios) and elaborates each backup_type enum value with what it backs up, including the default. This is very helpful beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a VIOS backup via the HMC CLI, using a specific command. It distinguishes from related tools like hmc_list_vios_backups (lists backups) and hmc_restore_vios (restores backups).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use (to create a backup) and prerequisite info (vios_uuid from hmc_vios). It also instructs polling hmc_list_vios_backups to confirm completion. It doesn't explicitly mention alternatives or exclusions, but the purpose is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses that a real partition is created, that it starts powered off with a default profile, that storage/network/boot must still be configured, that names must be unique across the HMC, and that a ValueError is raised on duplicates. It also explains shared vs dedicated processor behavior and unit semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into focused paragraphs: overview, parameter clarifications, state and side-effect warnings, error condition, and enum definitions. Every sentence adds value, and it remains readable despite covering many details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 18-parameter creation tool with no annotations, the description provides strong context: post-creation steps, uniqueness constraints, error behavior, and processor/memory units. It is incomplete in that it doesn't explain all parameters (e.g., uncapped, min/max/desired values) and doesn't mention whether the operation is synchronous or returns a job, which is relevant given sibling job-tracking tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 key non-obvious semantics: system_name_or_uuid format and lookup, MiB units, dedicated vs shared processor meaning, procs/vcpus interpretation, and enums for partition_type, os_type, and keylock. However, several parameters (uncapped, min/max/desired values, partition_id) are left without explicit explanation, relying on their names for meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Create a new LPAR on a managed system') and immediately distinguishes the tool from siblings like hmc_modify_lpar, hmc_delete_lpar, and hmc_power_on_lpar. It clearly scopes the action as creation of a real partition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context about when to use this tool (to create a new LPAR) and explains the resulting state (powered off, needs further config), but it does not explicitly state when not to use it or mention alternatives such as hmc_create_vios for VIOS partitions or hmc_provision_lpar for OS installation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With destructiveHint=true annotation, the description adds that the operation detaches storage/network and returns a confirmation string immediately with no job to poll. This goes beyond the annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main action, followed by a concise parameter breakdown. Every sentence adds value without fluff, making it easy for the agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the tool's purpose, parameter sourcing, valid values, and result semantics. The output schema exists and the description states the return format. No critical information is missing for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description explains each of the three parameters: lpar_name_or_uuid accepts name or UUID, adapter_type lists valid values, and adapter_uuid is obtained via hmc_list_adapters. This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes a virtual adapter from an LPAR by UUID, listing accepted adapter types. This distinguishes it from sibling add/remove tools like hmc_add_network_adapter or hmc_remove_vnic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on how to find parameters (hmc_lpars for LPAR name/UUID, hmc_list_adapters for adapter UUID) and clarifies the effect (detaches storage/network). It lacks an explicit 'use this instead of X' alternative, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe read operation. The description adds value by listing the return flags (e.g., LongTermMonitorEnabled, AggregationEnabled), which gives the agent expectations about the response beyond the annotation. It does not mention errors or permissions, but the annotation plus return-value summary are sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the primary purpose, and every sentence adds value. It avoids redundant phrasing and uses line breaks for readability. The examples are useful without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description covers the key elements: what it returns, how to specify the resource, and where to get valid identifiers. The presence of an output schema reduces the need to document exact return fields, so this is complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It gives semantic meaning for both parameters: 'category' is the resource type with examples, and 'resource_name_or_uuid' is explained as a name or UUID, with instructions on where to obtain them (from hmc_systems or hmc_lpars).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get PCM monitoring preferences for a resource' – a specific verb and resource. It clearly distinguishes itself from sibling tools like hmc_set_pcm_preferences (the setter) and metrics tools by focusing on retrieving preferences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains how to use the tool by defining both parameters with concrete examples ('ManagedSystem' or 'LogicalPartition') and referencing other tools (hmc_systems, hmc_lpars) for valid resource identifiers. It does not explicitly state when not to use it, but the context makes the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true, so the safety profile is known. The description adds behavioral details beyond that by revealing the underlying command (`lsviosbackup -id <vios_uuid>` over SSH) and the parsing of the fixed-width table into a list of dicts with keys (BackupName, Date, Type). This gives useful insight into how the tool operates and what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the main purpose. The second sentence adds execution and output details, and the third provides a prerequisite. There is no redundancy or filler, and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single parameter and an output schema already present, the description covers all necessary aspects: purpose, underlying command, output format (list of dicts with specific keys), and a pointer to obtain the required parameter. The mention of key names and the prerequisite makes it complete for this tool's scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides zero description coverage for the only parameter (vios_uuid), but the description compensates fully by defining it as 'a given VIOS UUID' and explaining how to find it ('Find vios_uuid with hmc_vios'). This is essential semantic information that is completely absent from the schema, making the description the sole source of meaning for the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List existing VIOS backups for a given VIOS UUID' which states a specific verb (List) and resource (VIOS backups), clearly distinguishing it from sibling tools like hmc_backup_vios or hmc_restore_vios. It also identifies the scope (existing backups for a specific VIOS), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating the exact operation and the prerequisite: 'Find vios_uuid with hmc_vios.' However, it does not explicitly discuss when to use this tool versus alternatives or when not to use it. The usage is clear enough in context, but without explicit exclusion or comparison, it earns a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes safety. The description adds behavioral value by specifying the output content (names, SwitchIDs, mode) and the relationship to other tools. No contradictions with 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, focused sentences. The first states the core action, and the second explains the parameter and the relevance of the output. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one parameter and an output schema, the description covers the system identifier lookup, the output fields, and the downstream use of SwitchIDs. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates: it explains that system_name_or_uuid accepts either a SystemName or UUID, and tells the user how to obtain it via hmc_systems. This adds significant meaning beyond the bare string type in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List VirtualSwitches on a managed system' with a specific verb and resource, and even notes the output fields (names, SwitchIDs, mode). This distinguishes it from sibling tools like hmc_list_virtual_networks and makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains how to provide the system identifier ('find it with hmc_systems') and why the output is useful ('SwitchID is what hmc_create_virtual_network and hmc_add_network_adapter reference'). While it doesn't explicitly mention alternatives or when not to use, this contextual guidance is sufficient for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark the tool as destructive, and the description adds that the operation performs an immediate delete with no job to poll, plus it returns a confirmation string. This is valuable behavioral context beyond the annotation, clarifying the sync nature of the operation and its return type.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized, front-loads the core action, and uses a clear list for the valid resource values. Every sentence adds value (Ansible equivalence, pre-inspection advice, return behavior) with no redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter and a simple output schema, the description fully covers what the tool does, all possible resource choices, the destructive and immediate nature, the return behavior, and a recommended prerequisite step. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for the only parameter 'resource', but the description fully compensates by listing all valid values and their meanings. This gives complete semantic coverage that the schema lacks, directly enabling correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb–resource pair ('Remove a component of the HMC LDAP server configuration') and enumerates each removable component, making the tool's scope unmistakable. It also distinguishes the tool from siblings like hmc_get_ldap_config and hmc_configure_ldap by focusing solely on removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives actionable advice to inspect the current state via hmc_get_ldap_config before calling, which clarifies a key workflow step. It does not explicitly state when to prefer an alternative like hmc_configure_ldap, but the removal vs. configure distinction is implied by the wording and examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds behavioral context beyond that: it explains the two modes (list vs. detail), the fields returned (capacity, free space, logical units vs. physical volumes, logical units), and the None return for not found. This is useful but doesn't cover error conditions or pagination, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence summary followed by two conditional paragraphs. Every sentence adds necessary information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter, the description covers the main behavior, return shapes, and not-found case. Given the absence of an output schema, it adequately explains what the agent can expect. No critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden for the single parameter ssp_uuid. It fully explains the semantics: omitting yields a list, providing yields a detail dict or None. This is clear and complete, adding rich meaning beyond the raw schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List Shared Storage Pools or get one by UUID.' It names the specific resource (Shared Storage Pools) and distinguishes between list and get-by-ID behavior, differentiating it from sibling tools like hmc_list_memory_pools or hmc_list_volume_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear conditional usage: omit ssp_uuid to list all pools, or provide it to get one pool. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for an agent to select this tool when dealing with shared storage pools. Lacks explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already indicating a safe read operation, the description adds valuable behavior details: returns None if a user is not found, ignores 'user_type' when 'name' is supplied, and describes the return structure including the flattened HmcUser fields. These go beyond the annotation and enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence summary, followed by clear conditional behavior and return format. Every sentence adds necessary information without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains the return format in enough detail. It covers both usage modes, parameter semantics, and the read-only nature of the operation, making it complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining both parameters: 'name' (optional, fetches a single user) and 'user_type' (filters the list, with enum values 'local', 'kerberos', 'all', and default 'all'). It also clarifies the interaction between parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'List HMC user accounts or get one by username.' It clearly distinguishes the two modes (list all vs. get by name) and focuses on user accounts, setting it apart from sibling tools that manage other HMC resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use each mode: when 'name' is provided, it fetches a single user; when omitted, it lists all users with optional filtering by 'user_type.' It does not explicitly mention alternatives (e.g., other user-management tools), but the scope is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation declares destructiveHint=true, but the description adds crucial behavioral details beyond that: it is 'permanently removes the account — irreversible', returns a confirmation string, and operates synchronously ('no job to poll'). This goes beyond what the annotation alone conveys, providing rich context about the operation's effects and return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main action in the first sentence, followed by two concise additional sentences covering irreversibility, pre-check, and return behavior. Every sentence earns its place with no redundant or fluff content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool with an output schema, the description covers all essential aspects: what it does, irreversibility, prerequisite verification, and synchronous vs. async behavior. It is complete and self-sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates by identifying the parameter as 'username' and recommending verification via hmc_users(name=...). This adds semantic meaning beyond the bare string type in the schema, though it doesn't detail constraints like case sensitivity or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'Delete an HMC user account by username.' This is a specific verb+resource combination that clearly distinguishes it from sibling tools like hmc_create_user, hmc_modify_user, and hmc_users. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by instructing to 'Confirm the username with hmc_users(name=...)' before calling and notes the operation is immediate with no job to poll. This implies when it is appropriate (deleting a user after verification) and sets expectations, though it doesn't explicitly list exclusions or alternate tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses the exact SSH command, the raw output format (including the empty-line case), and the UUID resolution logic with REST/SSH fallback. This gives substantial operational detail about how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each serving a distinct purpose: a one-line summary, the exact command and output, the REST limitation rationale, and input resolution behavior. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers purpose, execution mechanism, return value format, and input possibilities. With an output schema present and only two simple string parameters, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions, but the description explains that both parameters accept CLI name or UUID, and that UUIDs are resolved before execution. This adds critical meaning beyond the bare parameter names and compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Get the description field of an LPAR via the HMC CLI.' It uniquely distinguishes this tool from siblings like hmc_set_lpar_description (write vs read) and hmc_get_lpar_msp (different field) by stating the exact field and mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use this tool by noting that 'This field is not available via the HMC REST API,' implying SSH/CLI is the necessary route. It doesn't explicitly name alternatives or exclusions, but the context is strong enough for a qualified agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses meaningful behavior: it runs a specific HMC CLI command over SSH, returns a dict per pool with named fields, and handles UUID resolution with a REST-first/SSH-fallback strategy. This adds substantial transparency about how the tool works and what the agent can expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise: the first sentence gives the core purpose, and the following two sentences add operational detail (command, return fields, UUID resolution) without fluff. Each sentence earns its place and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the readOnly annotation, the presence of an output schema, and only one parameter, the description is complete: it states the action, the underlying command, the output format, and the parameter semantics. The agent has enough information to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only a string parameter name with no description (0% schema coverage). The description compensates by explaining that the parameter is a system CLI name or UUID and detailing the resolution process. It does not specify exact formats or constraints, but it gives enough semantic meaning for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'List shared memory pools on a managed system via the HMC CLI'. It also names the exact HMC command executed ('lshwres -r mempool -m <system_name>'), making the tool's function unmistakable and distinguishing it from sibling tools like hmc_shared_storage_pools or generic hmc_list_resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context: it explains that the system can be identified by CLI name or UUID, and how UUIDs are resolved. It does not explicitly name alternatives or state when not to use this tool, but the context is sufficient for an agent to select it for shared memory pool listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the destructiveHint annotation. It details the pre-flight check (fetches pool list, verifies existence, checks LPAR assignments), the exact command executed, the UUID-to-CLI-name resolution with fallback, the immediate return (no job polling), and the error raise conditions. This is extensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is multi-paragraph but well-structured: purpose, preconditions, command, resolution, warning/returns, and errors. Every sentence earns its place given the destructive nature and need for safety. It's slightly longer than strictly necessary but not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is comprehensive for a two-parameter destructive tool: it explains what it does, when it fails, what it returns, and how it resolves input. The output schema exists and the description covers the return value sufficiently. No major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates. It explains that system_name_or_uuid can be a CLI name or UUID (with resolution behavior) and that pool_name must refer to an existing pool with no assigned LPARs. This adds crucial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Remove a shared memory pool from a managed system via the HMC CLI.' This distinguishes it from siblings like hmc_list_memory_pools and other management tools. The verb-resource pair is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong context: it explains the preconditions (pool exists, no LPARs assigned), warns about permanence, and notes when the command will not execute. However, it does not explicitly name alternative tools for listing pools or explicitly state when-not-to-use scenarios beyond the safety checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds valuable context: a WARNING that this modifies the LPAR configuration, a requirement to confirm all three parameters, and a note that the operation is immediate with no job to poll. It also discloses the internal UUID-to-name resolution process (REST with SSH fallback), which is not captured by 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a one-sentence purpose, a command reference block, a short paragraph on identifier resolution, and a concise warning/return note. Every sentence earns its place; the length is justified by the destructive nature and the need to clarify prerequisites. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, the description covers all necessary context: what it does, how it runs (SSH command), identifier handling, prerequisite (vnic_id from list), warning, and return behavior (HMC CLI output, no job polling). The presence of an output schema is noted, and the description appropriately summarizes the return value without duplicating schema details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only parameter names and types, with 0% description coverage. The tool description compensates by explaining that system_name_or_uuid and lpar_name_or_uuid can be CLI names or UUIDs (with conversion logic) and that vnic_id is the numeric ID from hmc_list_vnics. This is meaningful beyond the schema, though it does not delve into formatting or constraints for each parameter in exhaustive detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Remove a vNIC from an LPAR via the HMC CLI.' This clearly states the action and distinguishes it from sibling tools like hmc_add_vnic or hmc_list_vnics. The resource is unambiguous (vNIC from an LPAR) and the method (HMC CLI) is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: it states that vnic_id is 'the numeric ID as reported by hmc_list_vnics', implying a prerequisite to list first. It also explains how system and partition identifiers may be given (CLI name or UUID). However, it does not explicitly name alternatives or exclusions (e.g., when not to use this vs. hmc_delete_adapter), so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant context beyond the destructiveHint annotation: it explicitly warns that restoring overwrites the current LPAR profile configuration, clarifies that file_path is on the HMC filesystem, and details the UUID-to-name resolution fallback mechanism. This fully discloses the destructive impact and important runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by implementation details, an important file path note, and a destructive warning. Every sentence contributes necessary information, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers all essential aspects: the exact command executed, the raw output, the file path location, UUID resolution, and the destructive overwrite warning. With an output schema and destructiveHint annotation already present, this is a complete and self-sufficient description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters (100% coverage). The description adds extra value by clarifying that file_path must already exist on the HMC host and that system_name_or_uuid can be a UUID or CLI name with a documented resolution process, exceeding what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool restores LPAR profiles from a backup file via the HMC CLI, using a specific verb and resource. It distinguishes itself from siblings like backup and sync by explicitly naming the restore operation and the underlying command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for restoring profiles from backups and emphasizes the prerequisite that the file must already exist on the HMC filesystem. It does not explicitly name alternative tools or exclusion conditions, but the usage context is clear and unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It clearly warns that arbitrary commands are executed and reveals authentication details (HMC_USER/HMC_PASSWORD or HMC_SSH_KEY_FILE). While it mentions returning output, it does not specify exit codes or stderr handling, but the reference link and 'return its output' are sufficient for an escape-hatch tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise one-sentence purpose, a warning, when-to-use guidance, authentication notes, and a reference link. Every sentence earns its place with no filler. The formatting uses paragraphs and a warning banner effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic command execution tool, the description covers all necessary context: purpose, usage restrictions, authentication, and a reference for HMC CLI commands. The output schema exists, so return values are presumably defined there. No annotations exist, but the description compensates with sufficient behavioral and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'cmd' with 0% description coverage, so the description must clarify it. The description explicitly says the tool executes an HMC CLI command, giving meaning to 'cmd' as the command string. It doesn't provide examples or syntax details, but the single parameter is self-explanatory and the description adds the crucial context that it's an HMC CLI command.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Execute an arbitrary HMC CLI command over SSH and return its output.' It uses a specific verb (execute) and resource (HMC CLI command), and explicitly distinguishes itself from dedicated tools by labeling it an 'operator escape-hatch' for operations without a dedicated MCP tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Use only for HMC CLI operations that have no dedicated MCP tool.' It also frames the tool as an 'operator escape-hatch' and warns about arbitrary command execution, making it clear this is not the default option but a fallback.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden. It discloses that the tool executes a chsyscfg command over SSH, that it modifies LPAR configuration, and warns the user to confirm parameters. It also details the UUID-to-name resolution fallback behavior, which is valuable beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by a command example, REST limitation, GUI context, UUID resolution, and a warning. Every sentence earns its place; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and an output schema, the description covers the operation, the exact command executed, the fallback behavior, and a safety warning. It is sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 that system_name_or_uuid and lpar_name_or_uuid may be either CLI names or UUIDs and that UUIDs are resolved. It also clarifies the purpose of the description field. While it does not provide format constraints, it adds meaningful semantics for all three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Set the description field of an LPAR via the HMC CLI.' This clearly distinguishes the tool from siblings like get_lpar_description and modify_lpar by stating exactly what it changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides contextual guidance, notably that this field is not settable via the REST API, implying when to use this tool over other APIs. It lacks an explicit 'when not to use' or direct alternative tool name, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While the annotation declares readOnlyHint=true, the description adds substantial behavioral detail beyond that: it specifies the exact lssyscfg command, the return value mapping (True for '1', False for '0'), and the UUID resolution process via REST with an SSH fallback. This gives the agent full transparency into what happens when the tool is invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose, followed by the command and key behavior in just three sentences. The use of a code block for the exact command is efficient and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple but includes a non-trivial UUID resolution process; the description covers this thoroughly. It also explains the return values (though an output schema exists, the description still provides clarity). The context provided is complete for the agent to select and invoke the tool correctly without further documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully compensates by explaining that both the system and partition may be given by CLI name or UUID, and that UUIDs are resolved to CLI names via REST (fallback SSH). This adds meaning beyond the bare parameter names and is essential for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Get the MSP (Migratable Service Partition) flag of an LPAR via the HMC CLI,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like hmc_set_lpar_msp. It also explains the exact command run and the boolean return mapping, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (to retrieve the MSP flag) and how it behaves (via SSH, with UUID resolution). It does not explicitly exclude alternatives or mention the setter counterpart, but for a simple read-only getter, the context is sufficient and no exclusions are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint annotation by detailing the exact HMC command executed, the UUID resolution process with fallback, and the output structure. It also specifies the pci_class filter values and their PCI class codes, providing transparent behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear opening sentence, followed by command details, output description, and filter documentation. Each section adds necessary information without redundancy, making it concise despite its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 params, output schema exists), the description covers the purpose, command, output fields, parameter semantics, and resolution behavior. It is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only lists parameter names without descriptions. The description compensates by explaining that system_name_or_uuid can be a CLI name or UUID and how it is resolved, and by fully documenting pci_class values including defaults and the meaning of each filter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List physical I/O slots on a managed system via the HMC CLI,' clearly identifying the action (list) and resource (physical I/O slots). It also specifies the underlying command and output format, distinguishing it from sibling tools like hmc_list_adapters or hmc_list_resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by explaining the system parameter (CLI name or UUID) and the pci_class filter options with their meanings. However, it does not explicitly mention alternative tools or when not to use this tool, so it lacks exclusions beyond the clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description reveals the underlying HMC CLI command (lshwres), the five returned fields, and the name/UUID resolution logic including REST-first and SSH fallback. This gives the agent a thorough understanding of execution behavior and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each carrying substantive information: the purpose, the exact command, the output fields, and the name-resolution behavior. It is front-loaded with the core action and avoids any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters and an output schema, the description provides all necessary operational context: the command run, the output structure, input flexibility, and related discovery tools. Nothing essential is omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero schema description coverage, the description fully compensates by explaining that both system_name_or_uuid and lpar_name_or_uuid accept CLI names or UUIDs, and that lpar_name_or_uuid is optional and restricts results. It also directs users to hmc_systems and hmc_lpars for finding UUIDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'List Shared Ethernet Adapter (SEA) virtual Ethernet ports via the HMC CLI' with a specific verb, resource, and scope. It also names the exact command and output fields, making it unambiguous and distinct from sibling tools like hmc_list_adapters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: pass lpar_name_or_uuid to restrict results, and use hmc_systems/hmc_lpars to find UUIDs. However, it does not explicitly compare with alternative adapter-listing tools (e.g., hmc_list_adapters) to explain when to choose this one over those, so it falls slightly short of an explicit 'when-not' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses return types per mode (str|None, dict|None, list[dict]), explains endpoint selection (cheap quick-property vs full fetch), and states that the state filter is ignored under certain conditions. It also documents the ValueError raised when state_only is used without lpar_name_or_uuid, providing rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description starts with a one-line summary and then uses a well-organized numbered list for the resolution priority. Each rule is necessary, direct, and free of redundant or filler content, making it easy to scan and apply.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description covers all parameters, all six resolution cases, return types, error conditions, and endpoint optimization guidance. It is comprehensive for a list/get tool and leaves no significant ambiguity about how to invoke it for various needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully compensates by explaining each parameter's role: lpar_name_or_uuid accepts PartitionName or UUID, name requires exact match, system_name_or_uuid accepts SystemName or UUID, state matches PartitionState, and state_only is a boolean that requires lpar_name_or_uuid. It also clarifies precedence and ignored parameters, giving complete semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List logical partitions (LPARs) or get/find one', which clearly identifies the verb and resource. The numbered resolution priority distinguishes it from sibling tools like hmc_lpar_summary (which provides summaries) and hmc_get_lpar_description (which gets only the description), making the tool's scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a detailed resolution priority with six cases, explaining which arguments to use for different outcomes, and explicitly notes that state_only uses a cheaper endpoint and that the state filter is ignored when lpar_name_or_uuid or system_name_or_uuid is supplied. However, it does not explicitly name alternative tools for when not to use this one, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although annotations already declare destructiveHint=true, the description adds critical context: it explicitly states that restoring overwrites the current VIOS configuration and advises confirming inputs. It also discloses that the command runs via SSH and returns raw HMC CLI output, going well beyond the annotation's minimal signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a purpose statement, the underlying command, parameter explanations, a warning, and return behavior. Every sentence serves a purpose, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive restore operation, the description covers all essential aspects: purpose, command execution, parameter sourcing, destructive warning, and return type. Even though an output schema exists, the description still notes raw CLI output. There are no significant gaps given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully compensates by explaining both parameters and their provenance: vios_uuid from hmc_vios and backup_name from hmc_list_vios_backups. It also includes the exact CLI command template, making parameter semantics clear and actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Restore' and the resource 'VIOS from a named backup via the HMC CLI', making the purpose immediately obvious. It distinguishes itself from related sibling tools like hmc_backup_vios and hmc_list_vios_backups by explicitly framing the operation as a restore.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on how to use the tool, specifying that vios_uuid must come from hmc_vios and backup_name from hmc_list_vios_backups. It also warns about overwriting configuration, implying use is appropriate only when restore is intended. However, it does not explicitly state when not to use it or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description reveals that the tool composes data from three specific HMC endpoints, accepts either a SystemName (exact match) or UUID, and raises ValueError on missing systems. It also details the return shape, adding substantial behavioral context beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a lead summary, a numbered breakdown of endpoints, a clear input line, a bulleted list of return fields, and an error note. Every sentence adds value and the length is appropriate for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all essential aspects: underlying API composition, input requirements, output fields, and error behavior. Even though an output schema exists, the explicit return-field list is helpful and not redundant. It is fully complete for a read-only summary tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a bare string parameter with no description. The description compensates fully by specifying 'Accepts either a SystemName (exact match) or a UUID,' clarifying accepted formats and exact-match semantics for the sole parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'One-call managed system summary' and enumerates specific data (state, MTMS, firmware, LPAR counts, free resources, VIOS count), making the purpose unmistakable. It distinguishes itself from sibling tools like hmc_systems or hmc_lpars by emphasizing the composite nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'One-call' phrasing clearly implies using this tool when a consolidated system overview is needed, and the list of fields signals its scope. However, it does not explicitly name alternative tools or state when NOT to use it, stopping 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds substantial context: the operation is irreversible, removes the partition and its profiles, refuses to run unless the state is 'not activated', and raises HMCError with HTTP 409 for that condition. It also explains the immediate return behavior, which is not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is multi-paragraph yet every sentence contributes value: preconditions, verification, irreversibility, return behavior, parameter format, and error condition. It is front-loaded with the core purpose and organized into clear sections (parameter, raises) without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and preconditions, the description covers all key aspects: what it does, when it can be called, how to verify the target, what it returns, and when it errors. The presence of an output schema covers return structure, so the description's mention of a confirmation string is complementary and not overdone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes the parameter only as a required string with 0% description coverage. The description compensates by explaining that lpar_name_or_uuid accepts either a PartitionName or a UUID, giving semantic meaning beyond the schema. While it doesn't detail formats or validation rules, this is sufficient for a single simple identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Delete (destroy)') and clearly identifies the resource (an LPAR) and the identifier method (by name or UUID). This sets it apart from sibling delete tools like hmc_delete_user and hmc_delete_vios.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the precondition that the partition must be powered off, and names the exact tools to use for that (hmc_power_off_lpar and hmc_lpars to confirm state). It also advises confirming the target with hmc_lpars before calling and clarifies that no job polling is needed, helping the agent choose this over job-based tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses permanence ('irreversible'), return format ('confirmation string'), and execution model ('immediate delete — no job to poll'). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the action, the risk/reversibility, and the return/behavior. Front-loaded with the primary purpose; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one parameter, destructive annotation, and an output schema, the description covers the essential context: what it does, how to prepare, what to expect in response, and why confirmation is needed. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one self-explanatory parameter (policy_name), but schema coverage is 0%. The description clarifies that the parameter should be verified against the list of policies, adding meaning beyond the schema. It doesn't specify exact name format, but the name is clear enough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action ('Delete an HMC password policy'), the resource ('password policy'), and the identifying attribute ('by name'). It clearly distinguishes from sibling tools like create/modify/list password policy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit pre-call guidance: 'Confirm the policy_name with hmc_list_password_policies before calling.' Also notes the operation is immediate (no job to poll), setting expectations for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description reveals that deletion is permanent and irreversible, that the tool refuses to delete if state is not 'not activated', and that it returns a confirmation string with no job to poll. It also documents the HMCError raised on HTTP 409.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every sentence contributes essential information: purpose, preconditions, mutation behavior, return type, and error handling. It is well-organized and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive and conditional nature of the operation, the description fully covers prerequisites, behavior, return value, and exceptions. Since an output schema exists, the lack of detailed return-field explanation is acceptable. The description is complete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates by identifying the parameter as a UUID and pointing to hmc_vios for confirmation. It doesn't provide format examples or a structured parameter definition, but for a single self-explanatory parameter this is adequate and adds practical context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete (destroy) a VIOS partition by UUID', which is a specific verb+resource+identifier. It clearly distinguishes from sibling tools like hmc_delete_lpar, hmc_delete_user, and hmc_delete_virtual_network by focusing on VIOS partitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the precondition that the VIOS must be powered off, referencing hmc_power_off_vios and confirmation via hmc_lpars. It also instructs to confirm the UUID with hmc_vios, and notes the state requirement ('not activated'), giving clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![hmc-mcp MCP server](https://glama.ai/mcp/servers/randomparity/hmc-mcp/badges/card.svg)](https://glama.ai/mcp/servers/randomparity/hmc-mcp)

Score Badge

Copy to your README.md:

[![hmc-mcp MCP server](https://glama.ai/mcp/servers/randomparity/hmc-mcp/badges/score.svg)](https://glama.ai/mcp/servers/randomparity/hmc-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/randomparity/hmc-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server