hcloud_list_isos

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds almost nothing beyond that — it says 'Returns all available ISO objects' without disclosing pagination behavior (auto_paginate defaults to true with a soft cap, per_page capped at 50) or that the 'all' result set is actually filterable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, front-loaded sentences with no filler. The second sentence is nearly redundant with the first, which keeps it just short of a 5, but the definition is not bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description could reasonably state the return shape or pagination merge behavior, and it could point to hcloud_get_iso as the single-object alternative. The rich schema compensates enough that an agent can call the tool correctly, so this is barely adequate rather than deficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the six parameters (name, architecture, page, per_page, auto_paginate, include_architecture_wildcard) are fully documented in the schema. The description adds no parameter meaning; if anything, 'all available' slightly undersells the name and architecture filters, but it does not conflict with them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('List ISOs') and restates it as returning ISO objects, so an agent immediately knows the operation. It does not distinguish itself from the sibling hcloud_get_iso or mention that name/architecture filtering is supported, but the list/get distinction is inferable from the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this versus hcloud_get_iso for a single ISO or hcloud_list_images for a related resource. No prerequisites, exclusions, or alternative routes are stated.

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