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

Annotations declare destructiveHint=true and readOnlyHint=false, but the description adds materially: the tool hits arbitrary paths (so any verb, including DELETE, is possible) and is disabled unless an environment flag is set. Not stating error behavior or what the raw response looks like 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.

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

Two short sentences, the gating requirement placed immediately after the purpose. No filler, 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?

For a fully generic escape hatch with no parameter documentation and a schema-coverage of zero, the description is not enough to call it correctly — the shape of 'path' and the data/params split are critical and undocumented. The existence of an output schema excuses it from explaining return values, but not from explaining inputs.

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% across four parameters, so the description carries the full burden and provides essentially nothing: it never explains that 'path' is a PVE API route, that 'method' selects the verb, or how 'data' (body) differs from 'params' (query). An agent must guess at the calling convention.

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 concrete action (call) and resource (arbitrary PVE API path) and labels itself an 'escape hatch', which separates it from the 20+ focused siblings like pve_vm_power and pve_update_vm. It stops short of saying what kinds of operations belong here, but the intent is unmistakable.

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 'escape hatch' framing implies this is a fallback for cases the dedicated tools don't cover, and the PVE_ALLOW_RAW_API=true prerequisite is a real gating condition. However, no alternative tool is named and no explicit when-not guidance is given, leaving the agent to infer the 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 non-read-only, non-destructive, closed-world, so the safety profile is partly covered. The description adds the genuinely useful confirm=true prerequisite, but says nothing about the resulting VM state, linked vs. full clone semantics, or that wait/timeout control polling — notable gaps for a provisioning mutation.

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 action and ending with the hard precondition. No waste, but brevity here edges into under-specification rather than purely efficient writing.

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 11 parameters at zero schema coverage and no output-schema explanation needed, the description should at minimum explain the clone mode and targeting parameters. As written an agent could call it, but would likely mis-set full/kind/target_storage.

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% across 11 parameters, so the description carries the full burden — yet it only clarifies confirm. Key decision parameters (full, kind, target_node, target_storage, wait, timeout) are left completely unexplained.

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 (clone) and resource (VM/container or template) plus the output (new VMID), which is enough to distinguish it from siblings like pve_update_vm or pve_delete_vm. The purpose is clear, though it does not differentiate from a hypothetical create tool.

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 only guidance is the confirmation precondition (confirm=true). There is no statement of when to use clone vs. creating a fresh VM, whether the source must be a template or stopped guest, or any exclusion — the agent must infer all of that.

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 and openWorldHint=false, so the safety profile is covered. The description adds the scope of the summary (nodes, quorum, guest states), but says nothing about whether values are aggregated live, cached, or how stale they may be — relevant for a health check whose whole value is freshness.

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 verb and the three things returned all appear immediately. Nothing is repeated from the annotations or schema.

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, the description needn't explain return structure, and with no parameters there are no argument semantics to cover. Only the freshness/aggregation behavior of the health data is left unaddressed, a minor gap for an otherwise self-contained read-only overview 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?

The tool takes zero parameters, so there is nothing to disambiguate and no schema burden to compensate for. The description correctly implies the call is argument-free, matching 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?

The description names a specific verb ("Summarise") and resource ("cluster health") and enumerates the payload: nodes, quorum, and guest counts by state. It is unambiguous what the tool returns, though it does not explicitly contrast itself with sibling list tools like pve_list_nodes or pve_list_vms.

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?

No explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. Usage is only implied by the word "Summarise" versus the granular list/get siblings, leaving the agent to infer that this is the high-level overview entry point.

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 destructiveHint=false and readOnlyHint=false, so the safety profile is covered structurally. The description adds the meaningful detail that a confirm=true flag is required, but says nothing about whether the snapshot is synchronous, how wait/timeout behave, or that snapshots consume storage — a notable gap for a 9-parameter mutation.

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. It is efficient, though the terseness contributes to the documented gaps rather than balancing them.

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 9 parameters, zero schema descriptions, and no output schema referenced in prose, the description is far too thin to call this tool correctly without reading the schema. The required-confirm note is the only behavioral aid provided.

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 must compensate, and it only covers confirm. Nothing explains vmstate (memory capture), wait, timeout, kind (qemu vs lxc), node, or description, even though these materially change behavior.

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 ("Create a snapshot of a VM/container"), which is unambiguous. It does not explicitly distinguish itself from sibling operations like pve_rollback_snapshot or pve_delete_snapshot, so it stops short of a 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?

It surfaces one important precondition ("Requires confirm=true"), which tells an agent it must set a flag before invoking. However, it offers no guidance on when to prefer this over pve_rollback_snapshot or how it relates to pve_list_snapshots, leaving selection largely to inference from the name.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description earns credit for adding two non-annotation facts: the deletion is irreversible and a confirm flag must be passed. It stops short of describing what happens to dependent state, whether the operation blocks, or what the wait/timeout flags change.

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, no filler, with the irreversibility warning and the mandatory confirm flag front-loaded where the agent will see them first. Nothing is wasted and nothing important trails.

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 described, and the destructive nature plus the confirm requirement are covered. However, with 7 parameters at 0% schema coverage, the description leaves too much unspecified to be considered complete for a destructive mutation tool — notably the node/kind selectors and the wait/timeout blocking behaviour.

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% across 7 parameters, so the description must carry the burden and it only explains one of them (confirm=true). The semantics of node, kind, wait and timeout — the parameters an agent is most likely to get wrong — are left entirely unexplained by both schema and description.

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 pairs a specific verb ('Delete') with a specific resource ('a snapshot'), which cleanly separates it from siblings like pve_create_snapshot, pve_rollback_snapshot and pve_list_snapshots without needing to name them. An agent can pick this tool from the list on the strength of the first three words.

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 parenthetical '(irreversible)' and the 'Requires confirm=true' clause imply this is a destructive operation that demands deliberate invocation, but the description never states when to choose delete over rollback, nor any exclusions or preconditions such as snapshot existence or node selection. Usage is inferable from the verb rather than guided.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally; the description adds "Permanently" (irreversibility) and the confirm=true gate, which is real value. However it says nothing about the destructive optional flags (purge, destroy_unreferenced_disks) or what wait/timeout do, so an agent cannot reason about the scope of what gets deleted.

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 destructive nature lands first and the required flag follows. Slightly over-lean for a tool with 8 parameters, but nothing is wasted.

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 described. But for a destructive, 8-parameter tool with zero schema descriptions, the description leaves too much unexplained — notably which optional parameters broaden the deletion and what wait/timeout imply.

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% across 8 parameters, so the description carries full burden, yet it explains only confirm=true. Data-destroying options like purge and destroy_unreferenced_disks, plus kind/node defaults, are left entirely undocumented.

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 ("Permanently destroy a VM/container") that clearly separates it from read-oriented siblings like pve_get_vm and from non-destructive siblings like pve_update_vm. It stops short of naming an alternative, but 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.

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

"Requires confirm=true" is a precondition, not guidance on when to choose this tool over alternatives such as pve_update_vm or pve_vm_power (stop vs destroy). No when-to-use or when-not-to-use context is 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 and openWorldHint=false, so safety is covered. The description adds only that status and config are returned; it does not discuss permissions, error behavior, or what 'config' includes.

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 short sentence, front-loaded with the action and resource, with no filler. It is arguably too terse for four undocumented parameters, but the sentence itself is efficient.

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?

Output schema and read-only annotations carry the return-shape and safety burden, but with 0% schema description coverage the description should compensate for parameter meaning and does not. It is minimally adequate for a simple getter but leaves real gaps around node/vmid/kind and include_config.

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%, yet the description does not define vmid, node, kind, or include_config. At best 'VM or container' hints at the kind enum and 'and config' hints at include_config, leaving required identifiers and defaults unexplained.

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 verb 'Get' and resource 'status (and config) of a VM or container' are specific and actionable. It does not explicitly distinguish this from pve_list_vms or pve_node_status, so sibling differentiation is absent.

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 implies use when you have a specific VM/container and need its current status, but it names no alternatives or when-not conditions. There is no guidance on choosing between this, pve_list_vms, or pve_node_status.

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 and openWorldHint=false, so the safety profile is covered. The description usefully adds that the data originates from the QEMU guest agent, but omits what happens when the agent is absent or not running — a common failure mode for this class of tool.

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 well-formed sentence with zero filler and the key concept front-loaded. It is efficient, though its brevity leaves the definition thin overall.

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. However, for a tool whose whole value depends on guest-agent availability, the missing prerequisites and undocumented parameters leave meaningful gaps for an agent deciding whether the call will succeed.

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 neither parameter is documented structurally, and the description does not compensate. It says nothing about 'vmid' (required) or 'node' (optional, nullable) — for instance whether node can be omitted or how it is resolved.

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 ('Read') and resource ('network interfaces reported by the QEMU guest agent'), making the tool's scope immediately clear. It does not explicitly name a sibling to distinguish from, though the contrast with pve_guest_agent_osinfo is implicit in 'network interfaces'.

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 use this tool versus alternatives, nor any prerequisites such as the VM needing to be running with the QEMU guest agent installed. The agent must infer all usage conditions from the tool name alone.

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 and openWorldHint=false, so the safety profile is covered. The description usefully adds the data source (the guest agent, not Proxmox's own config), which hints at the dependency, but says nothing about behavior when the agent is absent or the VM is stopped.

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. It is lean, though the brevity leaves key operational details unstated.

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 needn't be explained, and the read-only annotations cover safety. However, for a tool that depends on guest-agent availability and has an undocumented optional 'node' parameter, the description omits enough that an agent could call it incorrectly.

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% for two parameters, so the description carries the full burden and adds nothing: neither 'vmid' nor the optional 'node' (which defaults to null, leaving resolution ambiguous) is mentioned. An agent must guess how the node is determined when omitted.

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: 'Read OS information' from the QEMU guest agent. This clearly distinguishes it from the sibling pve_guest_agent_network, though the description never explicitly names that sibling or contrast.

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 name and the phrase 'reported by the QEMU guest agent', but the description never states the prerequisite (guest agent installed and running in the VM) or when to prefer this over pve_get_vm for OS details. No exclusions or alternatives 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 and openWorldHint=false, so the safety profile is covered. The description adds the useful conditional that `node` is required for node-scoped storages, but says nothing about permissions, error conditions, or what the listing contains (output schema covers returns).

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 sentence with no filler, and the key conditional constraint is packed inline rather than buried. Slight under-specification rather than verbosity, which is the better failure mode here.

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 needn't be described, and with only two parameters the surface area is small. Still, an agent must guess at `storage` identifier format and at which node/storage combinations are valid, which the description could have closed cheaply.

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 must compensate. It meaningfully explains `node` as conditional on node-scoped storage, but leaves `storage` (the only required parameter) entirely unclarified — no format, ID vs name, or scoping hint.

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 ISO images available on a storage"), which is a distinct operation from sibling list tools like pve_list_storage or pve_list_templates. It doesn't explicitly name a sibling to contrast with, so the differentiation is implicit rather than stated.

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 parenthetical conveys a conditional usage rule — supply `node` when the storage is node-scoped — which is real guidance. However, there is no statement of when to prefer this tool over pve_list_storage or pve_list_templates, and no mention of prerequisites such as storage needing to be ISO-capable.

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 and openWorldHint=false, so the safety profile is clear. The description adds that CPU, memory, disk, and uptime are included, but since an output schema exists, this is useful context rather than essential 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.

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

The description is a single front-loaded sentence with no wasted words. It states the operation and the returned node metrics immediately.

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 zero-parameter read-only list tool with an output schema, the description is largely complete: it states what is listed and which metrics are included. The main minor gap is lack of explicit sibling disambiguation.

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 has zero parameters and an empty input schema, so there is no parameter semantics to explain. Baseline 4 applies because the schema coverage is complete and no additional parameter guidance is needed.

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 ('List') and resource ('cluster nodes') and names the metrics returned. It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools such as pve_node_status or pve_cluster_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 description implies usage for enumerating cluster nodes, but it gives no explicit guidance about when to use this tool versus pve_node_status or pve_cluster_status. No preconditions or exclusions are stated.

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 and openWorldHint=false, so the description's only job is to add context beyond that, and it adds none: no note on ordering, whether running-state snapshots ('current') are included, or what an empty result means. For a read-only tool a 3 baseline is achievable, but this description contributes nothing behavioral.

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 zero filler. It is appropriately terse for a simple read tool, though the terseness shades into under-specification given the undocumented parameters.

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 needn't be explained, but with 0% schema description coverage the description should carry the parameter burden and doesn't. An agent cannot tell from the definition whether 'node' is needed for cluster setups or what 'kind' defaults to when omitted.

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% for all three parameters, so the description must compensate and does not: it never mentions vmid (required), node (optional but practically needed to locate the guest on a cluster), or kind ('qemu' vs 'lxc'). The kind enum's meaning and the node/vmid relationship are left entirely to inference.

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?

Clear specific verb+resource ('List snapshots') scoped to 'a VM or container', which distinguishes it from the write-side siblings pve_create_snapshot, pve_delete_snapshot and pve_rollback_snapshot by name alone. It doesn't explicitly state how it relates to those siblings or to pve_get_vm, so it stops short of full differentiation.

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?

No when-to-use or when-not-to-use guidance; the agent has to infer that this is the read counterpart of the create/delete/rollback tools. Nothing is said about prerequisites (permissions, whether the VM must be stopped, whether node must match the VM's host).

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 and openWorldHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact — capacity usage is only included when node is supplied — but says nothing about behavior on an invalid node (error vs. empty) or about scope when node is omitted.

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 wasted words; the primary purpose comes first and the conditional detail second. It is efficient, though given the empty schema descriptions it could afford one more short clause without becoming verbose.

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-value structure needn't be described, and the read-only annotation covers the mutation question. For a one-optional-parameter list tool the description is nearly sufficient, with only the omission behavior and node format left implicit.

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 0% and the lone node parameter has no description at all, so the sentence "when node is known, include capacity usage on that node" is the only thing explaining what the parameter actually changes. It stops short of specifying accepted node formats (name vs. ID), which keeps it off a 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?

"List storage definitions" is a specific verb+resource, and the storage domain is clearly distinct from siblings such as pve_list_nodes, pve_list_isos and pve_list_vms. It doesn't explicitly contrast itself with any sibling, so it lands just below the top band.

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 clause "when node is known" implies a usage condition for the optional parameter, but there is no guidance on when to omit it, what happens if node is omitted, or which alternative to reach for when storage isn't the target. Usage is implied rather than stated.

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 this as a safe, non-open-world read, so the safety bar is covered. The description adds almost nothing beyond them: 'recent' is undefined (what window? is there one?), and there is no mention of default limit, ordering, or whether results are truncated. For a task-listing tool where recency and pagination behavior are the core semantics, that is a real gap.

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 compact sentence with no filler, and scope is front-loaded before the filter qualifier. It is efficient, though its brevity contributes to the semantic gaps elsewhere.

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 described, but the description omits the recency window and limit behavior that determine what actually comes back. For a listing tool with zero schema parameter documentation, the definition leaves an agent guessing about result scope.

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 all three parameters (node, vmid, limit) rely entirely on their bare names. The description hints that 'guest' maps to vmid and mentions node, which is a small compensation, but the default limit of 20 and the meaning of node scoping are never explained.

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 (List) plus resource (cluster/node tasks) and a scoping qualifier ('recent', 'optionally filtered by guest'). It implicitly contrasts with pve_task_status for a single task, but never names the sibling explicitly, so a reader still has to infer the boundary.

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?

'Optionally filtered by guest' implies when the vmid filter applies, but there is no guidance on when to choose this over pve_task_status or pve_wait_task, and no stated conditions or exclusions. Usage is implied rather than directed.

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 and openWorldHint=false, so the safety profile is covered. The description adds nothing further: no mention of what 'templates' excludes (e.g., non-template VMs), no scope semantics for the node filter, no pagination or result-size behavior. For a listing operation the description carries almost no behavioral context of its own.

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 short, front-loaded sentence with zero waste. It is efficient, though the brevity is partly the source of the missing semantics rather than deliberate compression.

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 and annotations cover the read-only nature, so return shape and safety need not be restated. However, the undocumented node parameter and the absence of any scope or filtering semantics leave an agent guessing about how to call 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?

Schema description coverage is 0% and the single optional 'node' parameter is completely undocumented in both schema and description. The description never explains whether passing node scopes the listing to one node or whether omitting it aggregates cluster-wide — a meaningful semantic gap the description should have filled.

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 (list templates) and adds the 'for cloning' qualifier, which hints at its relationship to pve_clone_vm and distinguishes it from pve_list_vms. It does not explicitly name a sibling, so it stops short of a 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?

"Available for cloning" implies the use case (find a clone source before calling pve_clone_vm), but the description never states when to prefer this over pve_list_vms or whether a node must be specified. Usage is inferred rather than stated.

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 and openWorldHint=false, so the safety profile is covered. The description adds useful scope by saying results span the cluster and can be filtered, but it does not provide further behavioral details such as output size or pagination.

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 wasted words. It efficiently states the core action and the optional filtering capability.

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?

The tool is a simple read operation, annotations cover safety, and an output schema exists. However, the description is incomplete for the optional filtering behavior and does not help an agent choose between this tool and related list or get 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?

Schema description coverage is 0%, so the description must carry the burden of explaining the four optional parameters. It only says 'optionally filtered' and does not mention kind, node, status, or include_templates, leaving their semantics to the bare schema property names.

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: list VMs and LXC containers in the cluster. It is clear what the tool does, though it does not explicitly distinguish itself from siblings such as pve_list_templates or pve_get_vm.

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 phrase 'optionally filtered' implies that filters exist, but the description gives no guidance on when to use this tool versus alternatives like pve_list_templates or pve_get_vm. It also does not explain which filters are available.

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 and openWorldHint=false, so safety is covered. The description adds nothing beyond that: it doesn't say what happens when 'node' is omitted (the schema defaults it to null, which is genuinely ambiguous — all nodes? local node?), nor how expensive the storage lookup is. For a nullable default parameter this ambiguity matters.

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. It is efficient, though the brevity comes at the cost of the parameter clarification noted above.

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 described. However, with two undocumented parameters (one nullable with a default) and no sibling differentiation, the definition stops short of what an agent needs 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?

Schema description coverage is 0%, so the description carries the full burden. It only loosely gestures at both params ('one node', 'optionally with its storage usage') without resolving the key question of what a null/omitted node means, or that include_storage defaults to true.

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: 'Show detailed status for one node.' The optional storage clause signals scope. It is distinguishable from pve_list_nodes (enumeration) and pve_cluster_status (cluster-wide), but never names those siblings 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: 'detailed status for one node' suggests this is the drill-down after listing nodes. There is no explicit when-to-use/when-not, and no mention of how it relates to pve_cluster_status or pve_list_storage.

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 destructiveHint=true and readOnlyHint=false, so the description's 'discarding later changes' mostly restates that. The genuine addition is the confirm=true gating requirement, which the schema does not express (confirm defaults to false). It says nothing about what happens to the guest's power state or whether the operation is interruptible.

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 destructive consequence front-loaded and the precondition second. Nothing is wasted and the ordering matches how an agent should reason about the call.

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 are covered, but for a 7-parameter destructive mutation with zero schema descriptions, the definition omits the semantics of most parameters and any note on guest state, required permissions, or whether the rollback can be undone.

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 0% across 7 parameters, so the description must compensate, yet it only mentions confirm. The meanings of wait, timeout, node, and kind — including the qemu/lxc enum — are left entirely undocumented.

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+resource ('roll a guest back to a snapshot') plus the consequence ('discarding later changes'), which separates it from create_snapshot and delete_snapshot. It doesn't name a sibling explicitly, but the destructive framing makes the distinction inferable.

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 'requires confirm=true' line gives a concrete precondition for invocation, but there is no guidance on when to prefer rollback over delete_snapshot plus create_snapshot, nor any exclusion such as running-VM behavior.

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 and openWorldHint=false, so safety is covered. The description adds useful content about what is returned (running/stopped, exit status, optional log tail) but says nothing about whether the task must exist, how long logs are retained, or what happens for an unknown upid.

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 core purpose comes first and the optional log behavior follows. It is arguably too terse rather than too long, which is not a conciseness penalty.

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 spelled out, and the read-only annotation covers safety. However, with four parameters at 0% schema coverage and no parameter explanation in the description, an agent still lacks enough to call this 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?

Schema description coverage is 0%, so the description must compensate and it largely does not: it hints at the log options ('optionally its log tail') but never explains the upid format, the node parameter, or what log_limit controls. Half the parameters remain opaque.

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 ('Show a task's status') plus the returned fields (running/stopped, exit status, log tail). It is clearly distinct from list-oriented siblings like pve_list_tasks, though it never names or contrasts those siblings 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?

No guidance on when to use this versus pve_list_tasks (discovery) or pve_wait_task (blocking until completion). The agent must infer the selection criteria from the tool names alone.

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 the non-read-only, non-destructive profile, so the description must add beyond that — and it does surface the confirm=true safety gate, which the schema does not explain. But it says nothing about whether changes apply live or need a reboot, what happens when confirm is omitted, or that the `delete` parameter removes keys, which for a config mutation tool is meaningful missing context.

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 compact sentences with the core action front-loaded and the hard precondition second. No filler, no restating 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 6 undocumented parameters, a nested free-form settings object, and no annotation coverage of mutation semantics, this description is too thin. The output schema relieves it of explaining return values, but the `delete` parameter and the node/kind targeting options remain entirely opaque to an agent.

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% across 6 parameters, so the description must compensate and largely does not. It clarifies the `settings` object via an example and explains `confirm`, but leaves `vmid`, `node`, `kind`, and especially `delete` (an array of key names) completely unexplained in both schema and description.

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 ("Update guest configuration keys") and gives a concrete example of the settings shape. It clearly implies a mutation of VM config rather than power state or deletion, which distinguishes it from pve_vm_power and pve_delete_vm, 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?

"Requires confirm=true" is a concrete precondition for invocation, which is genuinely useful. However, there is no guidance on when to use this tool versus pve_vm_power, pve_clone_vm, or pve_api_request, and no mention of 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered, and the output schema covers the return shape. The description adds that the call is a connectivity probe against 'the connected host,' but says nothing about what happens when the host is unreachable (error vs. degraded response).

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 the resource named first and the usage hint trailing. Nothing redundant, nothing to trim.

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 zero-parameter, read-only, output-schema-backed tool, the description covers purpose and scope adequately. The only meaningful omission is failure behavior on an unreachable host, which matters precisely because the tool is framed as a connectivity check.

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 schema and description are consistent in that no input is expected.

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: 'Return the Proxmox VE version of the connected host.' That is unambiguous and clearly distinct from every sibling (none of which reports a version), though it never explicitly contrasts itself with them.

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 parenthetical '(connectivity check)' hints at when to reach for it, implying a lightweight health probe before heavier calls. There is no explicit when-not guidance or named alternative (e.g. pve_cluster_status) for broader cluster health checks.

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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the mutation/no-network profile is covered. The description adds a real prerequisite (confirm=true) beyond the structured fields, but omits the crucial behavioral distinction between 'stop' (hard) and 'shutdown' (graceful), and says nothing about whether wait/timeout block. The listing of 'stop' alongside destructiveHint=false is a mild tension worth surfacing but not a direct contradiction.

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 operation and followed by the one hard precondition. Every clause earns its place with no padding.

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, but for a 7-parameter destructive-capable power tool with zero schema documentation, the description does too little: no node/kind resolution behavior, no wait/timeout semantics, and no indication that suspend/resume require a running/QEMU guest respectively.

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% across 7 parameters, so the description must carry the load. It enumerates the 6 action enum values (duplicating the schema) and mentions confirm, but leaves kind, node, vmid, wait and timeout entirely unexplained — including whether node/kind are auto-resolved when omitted, which materially affects correct invocation.

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 ('Change') plus resource ('guest power state') with the full action set enumerated in parentheses, so an agent immediately knows this is the VM/LXC power-control tool. It is clearly distinct from siblings like pve_update_vm or pve_delete_vm, though it never names a sibling to contrast against.

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 implies usage (power-state transitions) and adds one hard prerequisite, 'Requires confirm=true', which is genuinely actionable. However, it gives no guidance on when to choose this over pve_update_vm or pve_get_vm, and no warning about which actions are disruptive or irreversible.

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 and openWorldHint=false, so the safety profile is covered. The description usefully discloses that the call blocks until completion and yields an exit status, but says nothing about the timeout behavior (default 120), what happens on timeout, or whether failures are surfaced as errors.

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 zero filler; the blocking behavior and the returned value are stated up front.

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 the blocking semantics are stated. However, the meaning of timeout, what node does, and what happens when the wait exceeds the timeout are all missing for a call an agent may block on.

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% and the description mentions no parameter at all. The required 'upid' identifier, the optional 'node' scoping, and the 'timeout' default of 120 seconds are undocumented in both places, so the description fails to compensate for the coverage gap.

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 ('Wait for a task') plus the outcome ('return its exit status'), which clearly separates it from pve_task_status (a non-blocking poll) and pve_list_tasks without naming them. It does not explicitly name the sibling it replaces, so it stops short of a 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?

There is no explicit statement of when to call this versus pve_task_status, nor any guidance about when not to block (e.g. interactive polling, long-running tasks). The only usage cue is implicit in the word 'wait'.

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