Recommend guest placement

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description does add that every node is scored and that rejections come back with reasons, which is useful behavioral context, but it omits how exclude_nodes and required-storage filters affect the result set.

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 sentences, front-loaded with the ranking criteria and followed by what the output contains. Nothing is padded, though the second sentence is somewhat thin given how much it has to carry.

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 rich annotations, full schema coverage and an output schema, the description supplies enough for an agent to call it correctly. The remaining gap is the advisory-only nature of the operation, which matters but is partly signaled by the name 'recommend'.

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 coverage is 100% and every parameter carries its own description, so the schema does the heavy lifting. The description's mention of memory headroom, CPU load and over-commit loosely maps to cores/memory_gib but adds no syntax or constraint detail beyond the schema.

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 first sentence names a specific verb (rank), the resource (nodes), and the exact decision it serves: placing a new VM/container by memory headroom, CPU load and vCPU over-commit. That scoping distinguishes it in practice from compare_nodes and plan_node_evacuation, though it never names a sibling 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?

Usage is only implied by 'for a new VM/container' — the description never says when to prefer this over list_nodes/compare_nodes, nor does it state that the result is advisory and that the tool does not actually create the guest. An agent must infer that boundary.

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