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

Annotations already establish readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description goes beyond them by explaining data provenance (queries every backup storage including Proxmox Backup Server directly, so results reflect actual volumes rather than scheduled intent) and by disclosing a real coverage limitation in the task-derived failures. It does not mention cost/latency of scanning all storages, which is the one behavioral trait an agent might still want.

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: the first sentence states exactly what is found, before any caveats. The remaining sentences each contribute a distinct fact (data provenance, parameter tuning rule, task-history limitation) with no restatement of the title or name.

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 an output schema present, return-shape details are correctly omitted, and the description covers provenance, the key limitation, and parameter intent. The only gap for a cluster-wide audit tool is any hint about scale/latency when many nodes and storages are scanned.

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%, so baseline is a 3. The description adds genuine meaning beyond the schema's terse 'Backups older than this are stale' by telling the agent how to derive a value from its own backup schedule. The `node` parameter is left entirely to the schema, keeping it at 4 rather than 5.

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 the specific verb+resource (audit of backups) and enumerates the three distinct findings it reports: missing/stale backups, unscheduled guests, and failed jobs. The second sentence adds a differentiating scope claim ('reads backup volumes directly from every backup storage ... not what the schedule promises') that separates it from schedule-based or task-list-based siblings like recent_task_failures.

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?

It gives concrete usage guidance for tuning max_age_hours ('~170 for weekly backups') and discloses a boundary condition: failed tasks come from the recent task list, so only recent history is covered. What's missing is explicit routing to alternatives (e.g. when to prefer recent_task_failures or storage_health), but the context for when this tool is the right call is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: each health check is emitted as a finding with operator guidance, telling the agent the output is diagnostic and actionable rather than a raw status dump. It says nothing about cost, timeouts, or auth, keeping it short of 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.

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

Two short sentences, front-loaded with the resource inventory and immediately followed by the use case. Every clause carries information; there is no filler or repetition of the title.

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 parameters, full annotation coverage, and an output schema that handles return values, the description only needs to convey scope and intent — both are present. The one missing piece is sibling differentiation against storage_health and cluster_health, which would complete the picture for an agent choosing among health tools.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is no parameter surface that needs explaining. Nothing in the description contradicts or complicates the empty 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?

States a specific verb (analyse) and resource (Ceph) and enumerates exactly what is inspected: health checks, OSD up/in counts, PG states, monitor quorum, capacity. That is well beyond a restated name. It does not, however, distinguish itself from overlapping siblings such as storage_health and cluster_health, which an agent must disambiguate on its own.

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?

Gives an explicit trigger condition — use when asking "why is Ceph degraded/warning?" — which maps a real user intent to this tool. No exclusions or named alternatives are provided, so the agent gets clear positive guidance but no routing rule against storage_health/cluster_health.

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

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description adds behavior beyond that: findings are sorted worst-first and each carries a concrete recommendation, which tells the agent what the response looks like and how to act on it. No cost or latency/scope limitations are mentioned.

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 check list and immediately followed by the routing cue. No filler and nothing buried.

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?

Zero parameters, rich annotations, and an output schema all carry the structural burden, so the description only needed to state scope and result shape. It does both, including ordering and the presence of recommendations, which is sufficient for an agent to invoke it confidently.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly makes no parameter claims.

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?

Specific verb (check) plus an enumerated resource set: quorum, node availability, CPU/memory pressure, storage fill, HA. An agent knows exactly what the tool inspects. It stops short of distinguishing itself from siblings like ceph_health and storage_health, which overlap on 'storage fill levels', so the boundary is left implicit.

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?

'Start here for any "is something wrong with the cluster?" question' gives clear entry-point guidance and situational context. It does not name when to prefer ceph_health or storage_health instead, so the alternative-routing half of the guideline is missing.

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

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

The annotations already establish that this is a safe, read-only, idempotent operation. The description adds useful behavioral context by naming the live metrics compared and the diagnostic conditions it flags, such as I/O-bound nodes, swapping, overload, version drift and memory imbalance.

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

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

The description is two compact sentences. The core comparison is front-loaded, followed by the diagnostic purpose and the specific conditions it flags, with no wasted text.

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

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

Given the simple one-parameter interface, full schema coverage, complete annotations, and an output schema, the description supplies everything needed for an agent to understand the tool's purpose and usage. Return-value details and the default node behavior are covered by structured fields.

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%, and the single `nodes` parameter is already documented as defaulting to all online nodes. The description does not add syntax, formatting, or selection guidance beyond the schema, so the baseline of 3 applies.

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 states a specific verb and resource: comparing live CPU, I/O wait, load, memory, swap and versions across nodes. It also explains the diagnostic framing, making it clearly distinct from sibling tools like list_nodes or cluster_health.

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?

It gives a clear use case: answering "why is node X slower than node Y?" and lists the conditions it flags. It does not explicitly name when not to use it or which sibling tool to choose instead, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context: the data is 'live' (real-time, not cached) and secrets are redacted in the output, which an agent needs to know before relaying results.

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?

One sentence, front-loaded with the scope ('one guest') and ending with the most decision-relevant caveat (secrets redacted). Nothing is padded.

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 no explanation, and annotations carry the safety profile. The description covers scope and redaction, leaving only minor gaps such as behavior for a nonexistent or stopped guest.

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?

There is a single required parameter, vmid, with 100% schema description coverage, so the schema already explains it as a VM or container id. The description adds no further syntax or format detail, which is the baseline expectation when the schema does the work.

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 states a specific verb and resource: show one guest's live status plus its full configuration. The singular 'one guest' implicitly separates it from list_guests, but the sibling is never named, so the differentiation is left to inference.

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: 'one guest' signals a single-item lookup rather than the enumeration that list_guests performs. There is no explicit statement of when to reach for this versus the sibling, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds that the tool returns both task state and a log tail, but does not mention log truncation behavior, permissions, or response limitations beyond what the schema and output schema provide.

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

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

The description is a single, front-loaded sentence with no filler. It efficiently communicates the core return content.

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 descriptions, and an output schema, the description is mostly complete for a simple read-only diagnostic tool. It could still mention task completion or failure semantics, but the structured metadata carries most of the needed context.

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 schema already documents node, upid, and log_lines in detail. The description adds no additional parameter semantics, which is acceptable given full schema coverage but does not exceed the baseline.

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 uses a specific verb and resource: it returns the state of a Proxmox task plus the tail of its log. It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools such as recent_task_failures.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. It implies usage from the name and description, but does not state prerequisites, exclusions, or sibling comparisons.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds that results carry resource usage, tags and HA state, but says nothing about pagination, result size on large clusters, or cost of a cluster-wide scan.

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?

A single front-loaded sentence with no filler. The purpose and returned content are stated in the first clause.

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 and an output schema, the description needn't explain returns or safety, and it does mention returned fields. However, for a 5-filter list tool it omits the existence of filtering entirely, which is the main thing an agent needs in order to call it well.

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 every filter is documented in the schema itself. The description adds no parameter semantics beyond the schema, which sets the baseline at 3.

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 and resource ('List VMs and containers') and scopes it to 'across the cluster', which separates it from get_guest (single guest) and list_nodes (nodes). It does not explicitly name any sibling, so it falls just short of 5.

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

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

The description gives no when-to-use guidance or alternatives. Critically, it never mentions that the tool supports filtering by tag, node, status, guest_type, or templates, so an agent has to open the schema to learn the tool's main usage pattern.

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

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 covered elsewhere. The description adds useful context by disclosing what data the response carries (status, CPU, memory utilisation), though it says nothing about pagination or scale limits on large clusters.

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?

A single front-loaded sentence with no filler. The resource and returned fields are packed into one clause, so an agent can read it in one pass.

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 explained, and rich annotations cover the safety semantics. For a zero-parameter read tool, the description supplies everything an agent needs 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.

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

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline for zero-param tools applies. The description correctly implies an unfiltered full-list call rather than suggesting any filtering options.

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 and resource ('List all cluster nodes') plus the fields returned (status, CPU, memory utilisation), which tells an agent exactly what it gets. It does not differentiate against siblings such as compare_nodes or node_maintenance_status, so the boundary between this and related node tools is left implicit.

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 implied by the scope phrase 'all cluster nodes' — an agent can infer this is the broad inventory call. However, there is no explicit when-to-use/when-not guidance and no mention of the sibling compare_nodes or node_maintenance_status as alternatives for narrower questions.

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

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

Annotations already declare this a safe, idempotent read, so the description correctly avoids repeating that. It adds real context beyond the annotations: the reboot criterion (installed kernel newer than running one) and, importantly, the data-freshness caveat that results reflect apt's last daily refresh — critical for interpreting staleness. It does not, however, state what the certificate expiry window or package set boundaries actually enumerate in output.

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?

Three short paragraphs, front-loaded with the primary purpose, then the reboot heuristic, then scope/freshness caveats. Every sentence carries distinct information with no redundancy.

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 structure needn't be explained. The description covers what is checked, the reboot logic, package coverage, and the staleness limitation — everything needed to interpret results correctly for a one-parameter read-only tool.

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

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

Schema description coverage is 100% and the single optional 'node' parameter is already documented as 'Only this node. Default: all.' The description adds nothing about the parameter, so baseline 3 applies — the schema does all the work.

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 and three concrete resources (pending updates, needed reboots, expiring certificates) scoped to Proxmox nodes. None of the siblings (list_nodes, storage_health, ceph_health, backup_audit) overlap with this maintenance-oriented check, so an agent can route correctly without opening the schema.

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 usage situation is implied — check this for update/reboot/certificate posture — and the node parameter default of 'all' is noted. However, there is no explicit when-to-use or when-not-use guidance and no pointer to a sibling for related concerns, so the agent must infer scope.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but 'Executes nothing' independently confirms the returned command sequence is advisory and will not be applied, which is the single most important fact for an agent about to act on the output. The enumeration of hazards it detects and the mention of Ceph 'noout' and HA maintenance mode add genuine behavioral context; it does not, however, say how it reports infeasible evacuations or whether the plan is safe to run verbatim.

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

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

The purpose and the safety-critical 'Executes nothing' both land early, and the middle sentence carries the detection/assignment detail in one dense clause rather than prose. No filler sentences; every line contributes routing or behavioral information.

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?

For a three-parameter planning tool with full schema coverage, complete annotations, and an output schema (so return shape needn't be described), the description covers detection, assignment, and non-execution. The remaining gap is edge behavior — what the plan looks like when no valid target exists — which is non-trivial for a tool whose whole job is feasibility planning.

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 node, memory_limit, and exclude_targets are already documented in the schema, establishing the baseline of 3. The description lends implicit meaning — 'overloading others' gestures at the memory_limit threshold — but adds no syntax, units, or interaction detail (e.g., how exclude_targets interacts with HA failover targets) 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?

Specific verb and resource: 'Plan how to empty a node for maintenance,' with the two failure modes it guards against (breaking HA, overloading others). It then enumerates exactly what the tool inspects (passthrough devices, bind mounts, local disks, locks, HA guests) and what it emits (target + migration mode + exact command sequence), which clearly separates it from siblings like recommend_placement or node_maintenance_status.

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 maintenance-drain context makes the intended moment of use unambiguous, and 'without breaking HA or overloading others' states the constraint the caller can tune. It stops short of naming alternatives or exclusions — e.g., when to prefer recommend_placement for pure placement questions or node_maintenance_status for reading current state — so the agent must infer routing.

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

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

Annotations already establish read-only/idempotent safety, so the description's real contribution is the non-obvious data-completeness caveat: results derive from a cluster-wide list Proxmox keeps short, so very old failures may be missing regardless of the requested window. That materially changes how an agent should interpret empty or thin results and cannot be inferred from the 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.

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

Two short sentences with the core purpose front-loaded and the caveat following. Every clause earns its place; nothing is redundant with the schema or annotations.

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 no explanation, and the three parameters are fully documented in the schema. Purpose, incident-triage positioning, and the retention caveat are all covered, leaving nothing an agent needs to call this correctly.

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%, so the baseline is 3 — the hours/limit/task_type meanings are already documented. The description adds value by warning that the `hours` window may not be honored for very old failures, which reframes how that parameter should be trusted, pushing it above baseline.

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 and resource ("List tasks that failed recently") plus a distinct output shape ("grouped by type"). An agent can immediately separate this from get_task_status (single task) and cluster_health (overall health) without opening any schema.

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?

"Good first stop after an incident" gives clear situational guidance for when to reach for this tool. It stops short of naming alternatives or exclusion cases (e.g. when to prefer get_task_status for a specific task), so it lands at 4 rather than 5.

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

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.

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine substance by listing exactly what is checked (pool state, data errors, scrub age, SMART, SSD wear, bad sectors), which tells the agent what a clean result actually certifies.

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

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

The purpose sentence is front-loaded and the checklist and usage clause follow in a logical order. The coverage list is long but each item is a distinct diagnostic signal rather than filler.

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 an output schema, full annotation coverage and a single well-documented parameter, the description carries what it needs to. The only gap is not relating itself to ceph_health for non-ZFS storage, which matters in a cluster with both.

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% with a single optional 'node' parameter already documented as 'Only this node. Default: all.' The description adds no scoping detail beyond the schema, so the baseline 3 applies.

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?

Names a specific verb and resource ('Check ZFS pools and physical disks') and enumerates the concrete signals it inspects. Naming ZFS implicitly separates it from the ceph_health sibling, though the description never says so outright.

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?

Gives clear triggering contexts: 'whether the storage underneath the guests is healthy' and 'before maintenance on a node.' It stops short of explicit exclusions or pointing at ceph_health for non-ZFS storage, so the agent must infer the split.

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