list_hosts

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing behavioral beyond that (no auth requirements, no pagination/truncation behavior when more hosts match), so it merely matches the annotation baseline.

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?

Front-loaded one-line summary followed by a scoped Args list; no filler sentences. The format is slightly verbose in listing parameters that are also present in the schema, but each line adds meaning the schema lacks.

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?

An output schema exists, so return values need not be re-explained, and both parameters are covered. Annotations handle the safety profile. Only minor gaps remain, such as what happens when results exceed max_results or exceed the 200 ceiling.

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 0%, so the description carries the full load and does so reasonably well: it gives the search query syntax with three examples, states that an empty value lists everything, and documents the 1-200 range and default 50 for max_results. Only missing detail is the exact search field grammar beyond the examples.

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?

States a specific verb ('List') and resource ('KVM hosts') and even enumerates the fields returned (status, cluster, CPU, memory, running VM count). Siblings list_vms and get_vm operate on a clearly different resource, so the agent can route without ambiguity, though the description never names them explicitly.

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

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

The Args block explains how to use `search` (with three concrete query examples and 'leave empty to list all hosts'), which is real usage guidance for the parameter. However, there is no when-to-use/when-not guidance relative to list_vms or any other tool, so context is only implied.

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