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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds a useful behavioral detail — omitting node falls back to the configured default — but says nothing about return format or pagination behavior for a listing 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?

The purpose is front-loaded in the first sentence and the Args block is terse per-item. Slightly verbose in repeating the frame, but every line contributes meaning.

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

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

With no output schema and only a readOnlyHint annotation, the description should ideally sketch what a listing returns, and it does not. It fully covers inputs, but leaves the return shape and filtering/response semantics unstated.

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 and does so well, documenting all four args: storage (storage id), vmid (optional guest filter), target (Proxmox target from config), and node (with the default-fallback rule). Format details are still thin, but each parameter's meaning is clear.

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

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

States a specific verb (List) and resource (backup archives) with explicit scope (on a storage, optionally filtered by vmid). The [READ] tag and the storage/vmid scope make it easy to distinguish from vm_backup (creation) and backup_restore.

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 the read/list use case and the optional vmid filter, but it never names alternatives or states when to prefer this over backup_restore or storage_content, both of which appear in the sibling list and also surface storage/backup data.

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, but the description goes well beyond them: overwrite is irreversible with no undo, dry_run runs the same existing-VM guard so refused previews predict refused restores, a delete is recorded as the safe inverse for free-vmid restores, and the call returns a task UPID (i.e. it is asynchronous and must be polled).

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-loads the two facts an agent most needs ([WRITE], HIGH RISK) before the risk body and the Args block, and every sentence carries distinct information (risk, preview mode, safe inverse, confirmation). No filler or restatement of the 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?

For a 7-parameter destructive mutation with no output schema, it supplies the return type (task UPID) and the destructive/preview mechanics thoroughly. It stops short of stating required Proxmox permissions or how to resolve the node/target pair if a caller has multiple targets configured, which would make it airtight.

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 and does so: every one of the 7 parameters is explained, including non-obvious semantics such as force being destructive-overwrite, dry_run invoking the real guard, archive cross-referenced to backup_list, node defaulting to the configured node, and target coming from config.

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 (restore), resource (QEMU VM), and source (backup archive), plus a [WRITE] tag and 'Returns task UPID' that immediately classify the operation as an async mutation. It is clearly separable from siblings like vm_backup and backup_list, which produce or enumerate archives rather than consume 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?

Explicitly covers when-not (overwrite requires force and has no undo), routing to a sibling ('see backup_list' for archive ids), preview workflow ('Pass dry_run=True to preview'), and an operational rule ('Confirm with the user before calling'), including the safety-inverse behaviour when restoring into a free vmid.

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 declare readOnlyHint=true, so the safety profile is covered. The description adds the 'cluster-wide' scope, which is useful context not in the annotations. It does not mention return format, permissions, or rate limits; with annotations covering the safety profile, a 3 is appropriate.

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 lines with no waste, and the critical constraint ('cluster-wide') is front-loaded. Every token earns its place.

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 one-parameter read-only status tool with an annotation covering safety, the description is essentially complete: it states what is read and the scope. It could mention what the result contains, but no output schema exists and the purpose is narrow enough that an agent has what it needs.

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 schema provides minimal documentation for the 'target' parameter beyond its type and default. The description says 'Proxmox target name from config', which adds some meaning, but does not explain accepted values, format, or behavior when omitted. Given one optional parameter, this is adequate but not rich.

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 clearly states a specific verb+resource: reading cluster-wide firewall options, with a parenthetical narrowing the scope to 'notably whether it is enabled'. This distinguishes it from the sibling vm_firewall_rules_list which covers per-VM rules rather than cluster-wide 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?

'[READ]' signals this is a read-only tool and the scope 'cluster-wide firewall options' gives clear context for when to use it, but there is no explicit mention of alternatives or exclusions. An agent can infer usage well, but the description does not name sibling tools or state 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, so the safety profile is covered; the description's '[READ]' tag is largely redundant with that. It adds the useful 'single-call cluster-wide' framing, but says nothing about return shape, pagination, or auth needs, leaving the added value modest.

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-loads the '[READ]' tag and purpose, then the routing guidance, then a compact Args block. Every line earns its place; only minor redundancy in restating the read-only nature keeps it from being maximally tight.

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 read-only inventory tool with no output schema, the description adequately conveys what is returned (aggregate VMs, nodes, storage) and how to scope it. It could say more about the response fields, but nothing essential for correct invocation is missing.

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%, so the description must carry parameter meaning, and it does: it supplies the accepted filter values ('vm', 'node', 'storage') that the schema omits and explains 'target' as the Proxmox target name from config. This meaningfully compensates for the empty schema descriptions.

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: an aggregate cluster-wide inventory of VMs, nodes, and storage. It explicitly distinguishes itself from siblings by positioning vm_get and node_status as the drill-down tools, so an agent can route correctly without opening either 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?

Gives clear usage context ('enumerate everything before drilling into vm_get / node_status') and names the alternatives it precedes. It lacks an explicit when-not-to-use clause, but the routing intent is unambiguous.

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, so safety is covered. The description goes beyond that by explaining how to interpret the result — the 'quorate' field in the type=cluster row signals whether quorum exists — which is genuinely useful since no output schema exists to carry it. It omits auth/pagination context, so not 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?

Front-loaded with a [READ] tag and the core purpose in the first sentence, followed by the one output field that matters. The Args block is slightly mechanical but not wasteful; nothing reads as 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?

For a read-only single-param tool with no output schema, the description covers purpose, the key return field, and the parameter's origin. The main gap is routing guidance relative to the many status-like siblings, but the operational essentials are present.

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%, so the description must compensate; it does minimally by defining 'target' as the Proxmox target name from config, which the schema does not say. It does not explain behavior when target is omitted (default null), leaving the main ambiguity of this single optional param unresolved.

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+resource ('Return cluster membership + quorum status'), which is concrete and distinct from a bare restatement. It doesn't explicitly contrast with near-siblings like ha_status or cluster_resources, so the agent must infer the boundary, but the scope is clear enough.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as ha_status, cluster_resources, or node_status, which overlap heavily with this tool's domain. Usage is only weakly implied by the read tag and resource 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?

readOnlyHint=true already declares the safety profile, so "[READ]" is largely redundant. The description does add the return-field set, but says nothing about pagination, result size, or failure behavior (e.g., unreachable target). With annotations covering safety, this is adequate but thin.

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 verb+resource on line one, followed by a compact Args block with no filler. Every sentence earns its place.

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?

No output schema exists, but the description compensates by listing the returned fields. For a zero-required-parameter read-only list tool this is nearly complete; only return volume/pagination behavior is unaddressed.

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 load — and it does, explaining both optional parameters and their default/fallback semantics (target from config, node default or all nodes). It stops short of giving node name syntax or format examples.

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

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

States a specific verb and resource ("List LXC containers") and enumerates the returned fields (name, vmid, status, cpu, mem), which distinguishes it from sibling vm_list (VMs, not containers). It does not explicitly name the alternative, but the resource 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?

The Args section gives real per-parameter guidance (omit target to use the config default; omit node for the configured default / all nodes), which is usable context. However, there is no guidance on when to choose this tool over vm_list or other list tools, so usage is only implied.

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 destructive/non-idempotent writes, lowering the bar. The description adds real context beyond them: the return value (task UPID) and the dry_run preview option that lets the agent dry-run before mutating.

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 with the [WRITE] tag, action, return value, and inverse before the preview note and args. Every line earns its place 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?

Covers the mutation, return value, preview mechanism, and every parameter despite no output schema or schema descriptions. Adequate for correct invocation; only the UPID's downstream consumption and node/target interaction are 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?

With 0% schema coverage, the description must carry the load and mostly does: vmid (numeric id, points to ct_list), dry_run (preview), target (config name), node (omit to auto-locate). All four params get meaning, though formats remain loose.

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+resource ('Start an LXC container') and disambiguates from the VM sibling by scoping to LXC. It also names the inverse operation (ct_stop) and states the return value (task UPID), so an agent can place it precisely among siblings.

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 operational context: the inverse relationship to ct_stop and the dry_run=True preview path. It doesn't explicitly contrast with vm_start or state when-not to use, so it stops short of full alternative 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?

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description discloses that the operation is async and returns a task UPID, and that dry_run allows previewing. It omits whether the stop is forced/immediate versus graceful, which matters for a destructive container operation.

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 with the marker, purpose, return value, and inverse before the Args block. The Args block largely restates the schema and repeats dry_run (already covered in the lead), which is minor redundancy for a 4-parameter tool with no schema descriptions.

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 4-parameter schema, no output schema, and available annotations, the description covers the operation, its async return, and each argument's meaning. The remaining gap is the forced-vs-graceful semantics of a stop, which an agent would want before running a destructive action.

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%, but the description documents all four parameters: vmid points to ct_list for discovery, node notes it may be omitted to auto-locate, target is a named config target, and dry_run is explained. Only 'target' remains somewhat vague as a config-defined label.

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 ('Stop an LXC container'), front-loads a [WRITE] marker, and explicitly names the opposing operation ('Inverse: ct_start'). An agent can distinguish this from vm_stop/ct_start 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?

Points to ct_start as the inverse and explains the dry_run preview path, which tells the agent when a safe rehearsal is available. It does not, however, contrast hard-stop semantics against a graceful shutdown sibling or state preconditions such as the container needing to be running.

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?

With readOnlyHint=true already covering the safety profile, the description adds real behavioral context: it sources from the /cluster/resources guest view, covers both qemu and lxc, orders findings worst-first, and emits a separate stopped-guest list with measured numbers and remediation. It stops short of stating pagination or result limits, but the output shape is well disclosed.

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 with the purpose sentence, then the mechanism, then the arg. The 'Args:' block is slightly formal for one parameter but every sentence carries information; no 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?

No output schema exists, but the description compensates by describing the return shape (worst-first findings, stopped-guest list, per-finding measurement and remediation). For a single-optional-parameter read tool this is close to complete; only volume/format specifics are missing.

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 burden, and it does: 'target' is defined as a Proxmox target name from config, with the omit-to-use-default behavior made explicit (consistent with the schema's null default). It is a single optional parameter, so little more 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?

States a specific verb and resource ('Scan VMs and containers') plus exactly what it looks for: stopped guests, memory saturation, disks near full. This is clearly distinguishable from sibling list/status tools like vm_list or cluster_resources.

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 '[READ]' marker and the diagnostic framing imply when to reach for it, but no explicit alternatives are named — notably node_pressure_rca, which covers the analogous node-level scan and is never referenced. Usage is inferable 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?

The readOnlyHint annotation already establishes this is a safe read. The description adds one genuinely useful behavioral fact: the result is empty when HA is not configured, which helps the agent interpret an empty response. It does not disclose permissions, return fields, or rate limits, so it adds only modest context beyond annotations.

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 definition is short and front-loaded, leading with the read tag and resource scope before the args block. Nothing is redundant or padded, though the '[READ]' tag partially duplicates the readOnlyHint annotation.

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 simple one-parameter list tool with no output schema, the description is adequate but thin. It explains the empty-result case but omits what fields an HA resource record contains and how the optional target affects scope, leaving gaps an agent might care about.

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 for the single 'target' parameter. It states 'target: Proxmox target name from config', which clarifies the value comes from configuration, but adds no format, syntax, or default guidance (the schema default is null). Marginal value over the bare 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 states a specific verb+resource: listing HA-managed resources (VMs/CTs). The '[READ]' tag reinforces read semantics, and the parenthetical narrows scope to HA-managed guests, which distinguishes it from broader siblings like cluster_resources or vm_list. It does not name those siblings explicitly, so it falls 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 when-to-use or when-not-to-use guidance, and no alternatives are named despite relevant siblings like ha_status and cluster_resources. The note that the result is 'empty when HA is not configured' hints at applicability but is not framed as a selection condition.

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 cover the safety profile with readOnlyHint=true, and the description adds real substance on top: the exact return keys, the semantics of 'configured', and an explicit warning about misreading quorum/master/lrm rows. It omits only secondary traits such as permissions or pagination, which are unlikely to matter for a read.

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 with the [READ] tag, purpose, and return shape, then the caveat, then args. Efficient overall, though the middle paragraph is dense and slightly over-explains the quorum/lrm edge case.

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

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

With no output schema, the description takes on the burden of documenting the return value and does so, including the subtle distinction between a non-empty entries list and real HA management. Remaining gaps are minor, such as default-target behavior when 'target' is 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 coverage is 0% and the schema itself carries no description for 'target'. The description compensates by explaining that it is the 'Proxmox target name from config', which is exactly the missing meaning an agent needs to supply a valid value.

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 [READ] tag plus 'Current HA status entries, or a not-configured signal' gives a specific verb and resource, and the return shape is stated up front. It does not, however, distinguish itself from the sibling ha_resource_list, leaving the agent to guess which HA view is which.

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 a strong interpretive guideline ('Do NOT infer HA is set up from a non-empty entries list'), which shapes how to read results. But it names no alternative tool and states no condition for choosing this over ha_resource_list, so usage is only implied.

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 readOnlyHint=true annotation already establishes that this is a safe read. The description's '[READ]' tag merely restates that annotation, and it adds no other behavioral context such as whether the returned ID is reserved/claimed, whether repeated calls return the same value, or any rate limits. Only the endpoint reference adds marginal value.

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?

Very short and front-loaded: purpose first, endpoint and arg second. Nothing is padded, though the '[READ]' prefix and the 'Args:' block are somewhat boilerplate for a single optional parameter.

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 one-optional-parameter read tool with no output schema, the description is minimally adequate: it conveys purpose and the parameter's meaning. It omits how the returned VMID is meant to be consumed and the behavior of the optional target, leaving modest gaps.

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 parameter meaning, and it does partially by explaining 'target: Proxmox target name from config.' However it does not clarify the format, whether it is optional (schema default is null), or what happens when omitted, so the compensation is incomplete.

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 ('Return a free VMID for a new guest') and even cites the backing endpoint (/cluster/nextid). It is unambiguous what the tool produces, though it does not name a sibling for differentiation (which is arguably unnecessary here since no sibling does the same thing).

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 guidance on when to call this versus alternatives, nor any stated prerequisite (e.g. 'call before vm_clone or guest creation'). The usage is only implied by 'for a new guest'. No when-not conditions 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?

readOnlyHint=true already declares this is a safe read, so the '[READ]' tag adds nothing new. The description does add value by naming the returned fields (status, cpu load, memory), but omits pagination, scoping, or auth/connection context for the target.

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 with the operation, then a compact Args block. No wasted sentences. The '[READ]' prefix is slightly redundant against the readOnlyHint annotation but costs little.

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 single-optional-param read-only list tool with no output schema, this covers purpose, contents, and the one parameter adequately. The remaining gap is sibling disambiguation, which is minor given the small surface.

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%, so the description must carry the parameter. It does: 'target: Proxmox target name from config; omit to use the default' explains both the meaning of the value and the default behavior, which the bare schema (string|null, default null) does not.

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 Proxmox cluster nodes') and adds the payload contents (status, cpu load, memory), so the agent knows what comes back. However it does not distinguish itself from the closely-named sibling node_status, leaving ambiguity about which to pick.

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, when-not-to-use, or alternative guidance. With siblings like node_status and cluster_status in the list, some routing hint was warranted, but none is provided.

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?

readOnlyHint already covers safety, and the description adds real behavioral context beyond it: the data source (/cluster/resources node view), the specific thresholds (85% CPU, 90% memory, 85% disk), the worst-first ordering, and that every finding cites a measured percentage plus a concrete action. This is richer than the annotation alone, though it stops short of describing the exact output shape.

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 with the [READ] tag and the one-line purpose, then supporting detail, then args. Every sentence contributes (action, source, thresholds, ordering, output content). No 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 no output schema, the description must convey the return shape, and it does reasonably well: it returns nodes ranked by pressure, each with a measured percentage and a suggested action. Minor gaps remain around exact field format and behavior on an all-healthy cluster, but nothing essential to correct invocation is missing.

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 single parameter, and it does: 'target' is defined as a Proxmox target name from config, with the null-omission behavior explained ('omit to use the default'). This meaningfully compensates for 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 (Rank) plus resource (cluster nodes) and the exact dimensions (CPU / memory / root-fs pressure). The explicit thresholds and 'worst-first' ranking distinguish it from generic siblings like node_status, node_list, and cluster_resources. An agent can tell what it produces 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 diagnostic intent (flagging over-threshold nodes) implies when it is useful, and it is clearly an RCA tool alongside guest_health_rca. However, it never states when to prefer it over node_status or cluster_resources, nor any exclusions or prerequisites. Usage is inferable but not 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?

The '[READ]' marker duplicates the readOnlyHint=true annotation rather than adding to it. It does add useful scope context by naming the four metric families returned, but says nothing about permissions, targets/fallback behavior, or freshness of the data, which is below the bar for a richer 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?

Front-loaded with the read-only marker and the payload summary, then a compact Args block. No filler, though the bracketed tag is slightly redundant with the annotation.

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

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

With no output schema, the metric list in the description is the agent's only preview of the response, and it covers the essentials. Missing details such as units, value interpretation (e.g. load thresholds), or behavior when target is omitted keep it from being fully complete.

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 is the only source of parameter meaning. It explains 'node' (name, obtained via node_list) and 'target' (Proxmox target from config), giving the agent enough to supply both correctly, though it does not clarify the default/optional nature of target.

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 ('Detailed status for one node') and enumerates the returned metrics (cpu, load average, memory, uptime), so the agent knows exactly what it gets. It does not explicitly contrast with siblings like cluster_status or node_list, but the single-node scope 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?

Provides a pointer to node_list for discovering valid node names, which implies the intended call-order (list first, then status). It never says when NOT to use it or how it relates to cluster_status/node_pressure_rca, so usage is only implied.

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 the '[READ]' prefix merely duplicates that. The description does add the return payload shape (poolid + comment), but says nothing about pagination, empty states, or target resolution behavior.

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 terse lines with the core purpose front-loaded and no filler. The '[READ]' tag is redundant with annotations and the Args block is spartan, 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?

For a simple read-only list tool with annotations covering the safety profile and no output schema, the description covers purpose, return fields, and the single parameter's meaning. Adequate, though it could note the relationship to pool_members.

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 schema documents only 'target' as a nullable string with no semantics. The description partially compensates with 'Proxmox target name from config', clarifying where the value originates, but gives no format examples or default 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?

States a specific verb+resource ('List resource pools') and even names the returned fields (poolid + comment), which implicitly separates it from the sibling pool_members. It does not, however, explicitly say it is not pool_members, so sibling 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?

The description gives no when-to-use guidance and never mentions the closely related pool_members tool. The only hint is the '[READ]' tag, which is a read-only marker rather than usage direction.

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?

readOnlyHint=true already establishes the safety profile, and the '[READ]' prefix merely restates it. The description does add value by naming what is returned (VMs, CTs, storage), but says nothing about permissions, pagination, or empty-pool behavior.

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 is front-loaded in the first line and the Args block is terse and scannable. Every line earns its place, though the arg list partially duplicates the 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?

For a simple read-only list tool with no output schema, the description covers the purpose, both parameters, and the shape of the returned members. Nothing essential for correct invocation is missing.

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%, so the description carries the burden and largely succeeds: poolid is explained with a pointer to pool_list, and target is described as a Proxmox target name from config. The target explanation is slightly vague about valid values but conveys its origin.

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 the members of a pool') and scopes the return contents (VMs, CTs, storage), which separates it from pool_list, which enumerates pools rather than members. The differentiation is implied via the cross-reference rather than stated 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?

There is no when-to-use or when-not-to-use guidance and no alternatives named. The only pointer is 'see pool_list' for resolving the poolid, which aids parameter lookup rather than tool selection.

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 the '[READ]' prefix only echoes that. The description does add the useful context that results are scoped to a single storage pool and can be filtered by content type, but it says nothing about pagination or return shape. With annotations carrying the safety profile, a 3 is appropriate.

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 purpose sentence followed by a clean per-argument breakdown; every line maps to a real parameter. The 'Args:' block is slightly mechanical but wastes no words.

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 read-only list tool with no output schema, the description covers purpose, all four parameters, and the default-node behavior. It leaves the return format unstated, but with no output schema that gap is minor for a listing operation.

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%, so the description must carry parameter meaning, and it does: storage is tied to storage_list, node explains the default-node omission behavior, target points to config, and content supplies the actual filter values ('iso', 'images', 'backup', 'vztmpl') that the schema lacks (0 enums). Only the absence of an explicit required/optional marker for storage holds it below 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?

States a specific verb ('List') and resource ('volumes on a storage pool'), and parenthetically enumerates what those volumes are (ISOs, disk images, backups, templates). The reference to storage_list makes it distinguishable from the sibling that lists the pools themselves.

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 '[READ]' marker and 'see storage_list' pointer hint at scope, but there is no explicit statement of when to use this vs alternatives or when not to. Usage is implied by the read-only listing framing 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?

The readOnlyHint=true annotation already establishes the safety profile, and the [READ] prefix is redundant with it. The description adds useful value by enumerating the returned fields, but discloses nothing about permissions, target resolution failures, or the shape/size of 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?

Front-loaded with purpose and return fields, followed by a compact two-entry args block; every line earns its place. Slightly mechanical in structure but nothing extraneous.

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 two-optional-parameter read-only list tool with no output schema, the description covers purpose, return fields, and both parameters' default behavior. Only pagination/result-size behavior is left unaddressed, which is minor here.

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%, so the description carries the burden and does it well: it explains that target comes from config and may be omitted for the default, and that node falls back to the target's configured default node. That default-resolution chain is meaningful semantics not present anywhere in 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?

States a specific verb and resource ("List storage pools on a node") and even names the returned fields (id, type, total/used/avail bytes), so the agent knows exactly what it gets. It does not explicitly distinguish itself from the sibling storage_content, which is a close neighbor, so it falls 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?

Usage is only implied: the [READ] tag and "List storage pools" make the intent obvious, and the args section explains default fallback behavior. However, there is no explicit when-to-use versus storage_content or guidance on when listing pools is the right call.

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 provide readOnlyHint=true, so the safety profile is covered, and the description adds genuinely new behavior: the exact return payload shape, the truncation flag semantics, and the node-omission fallback that parses the node from the UPID. It stops short of describing pagination mechanics, auth requirements, or error behavior for an invalid UPID, which keeps it below 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?

The [READ] marker and purpose lead the description, followed by return shape and then args, so it is well front-loaded. Sentences are tight overall, though the truncation warning is slightly verbose relative to the rest and the Args block partly restates schema titles.

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?

There is no output schema, so the description carries the full burden of describing the response, and it does so precisely with the lines/returned/limit/truncated fields. Combined with annotations covering read-only safety and all four parameters being explained, an agent has everything needed to call and interpret this 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 0%, so the description must carry all parameter meaning and does document all four args. It adds real value beyond the bare names: 'target' is explained as coming from config and 'node' notes that omitting it parses the value from the UPID, plus the limit default of 200 in the schema is referenced. The per-arg notes are terse, so format expectations for upid/limit are only minimally clarified.

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 ('Fetch the log lines of an async task') plus the identifier scope (by its UPID). This clearly separates it from sibling task_status, which reports task state rather than log output, so an agent can pick between them without opening a 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?

Gives real operational guidance for truncated results ('raise limit or narrow the query rather than assuming you have the whole log'), which tells the agent how to interpret and react to output. However, it never states when to use this tool versus task_status or any other sibling, and offers no prerequisites or exclusions, leaving tool selection to inference.

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?

Annotation already declares readOnlyHint=true, and the description is consistent with that. It adds the non-obvious default that the node is parsed from the UPID when omitted, but says nothing about what polling returns (running/stopped/exit status), whether it blocks or errors on 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?

Front-loaded with a [READ] marker and a one-line purpose before usage and args. Slight redundancy: the node-from-UPID rule appears both in the prose and in the Args list.

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?

There is no output schema, so the description is the only place an agent could learn what a poll yields (completion state, exit status, log reference). The guidance on calling the tool is complete, but the return-value picture is not.

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%, so the description must carry the load, and its Args block documents all three parameters beyond the bare types: upid's provenance, target as a config name, and node's optionality plus derivation rule.

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 (poll) plus resource (Proxmox async task) and concrete task examples (clone/migrate/backup), scoped by the UPID identifier. It does not explicitly distinguish itself from the sibling task_log, which likely also takes a UPID, so it falls short of full sibling 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?

States clearly when to use it: after a write that returned a task UPID, to check completion, and explicitly warns against re-issuing the operation. No alternative tool (e.g. task_log) is named, so the routing is clear but not exhaustive.

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, idempotentHint=false and readOnlyHint=false, but the description adds real value beyond them: the inverse executes through its own governed tool with its own risk tier recorded on the audit row, dry_run previews without executing, and a token is single-use (consistent with idempotentHint=false). It does not describe error behavior if the token is already consumed, but the added context is substantial.

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-loads the write/risk tag and the core action, then adds only the constraints that matter (single-use token, dry_run preview). The Args block repeats schema field names but is justified given 0% schema description coverage; wording is tight with no 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?

For a mutation tool with no output schema, it covers the essentials: risk tagging, audit behavior of the inverse, dry-run path, and single-use tokens. Missing is any guidance on failure modes (expired/consumed token) or what a successful result reports, but the core operational picture is complete.

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 parameter burden, and it documents all three: undo_id (source: undo_list or _undo_id from a write result), dry_run (preview semantics), and target (passed through when the inverse accepts one). The target explanation is slightly soft about what values are valid, preventing 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?

States a specific verb and resource ('Apply a recorded undo by dispatching its inverse tool') and the mechanism, which cleanly separates it from the sibling undo_list that only enumerates undo tokens. An agent can tell exactly what this tool does 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?

Explains where undo_id comes from ('from undo_list (or an _undo_id in a write result)') and when to use dry_run for a preview, which is clear contextual guidance. It stops short of stating when *not* to apply an undo (e.g. token already consumed, which is only implied by 'A token can only be applied once').

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 only supply readOnlyHint=true; the description goes well beyond that by disclosing the return shape, that truncation is *measured* via an extra-row fetch, and that effectVerified=false means the reversed change is only PROBABLE, with a caution to check live state and not over-report. This is meaningful operational context the annotations cannot carry.

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 with purpose and the sibling handoff, then structured paragraphs for return value and the effectVerified caveat. Every sentence carries information, though the emphasis on truncation being 'measured, not guessed from a length coincidence' is slightly verbose for the value it adds.

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

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

With no output schema present, the description supplies the return JSON shape, the meaning of every field an agent must act on (returned, limit, truncated, effectVerified), and the follow-up behavior for truncation. Nothing needed to call or interpret it correctly is missing.

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 no param has an enum, so the description must compensate, and it does fully: limit is documented as default 50 / capped at 500, and target is documented as ignored with the reason (host-local undo state, kept for CLI uniformity).

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 recorded, not-yet-applied undo tokens') plus ordering ('most recent first'). The [READ] tag and the reference to undo_apply make it clearly distinguishable from the sibling that actually applies tokens.

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?

Explicitly routes the agent: 'Use the undoId with undo_apply.' and tells it to re-run with a higher limit when truncated rather than reporting a partial list as complete. It lacks an explicit 'when not to use this' condition, so it falls just short of a 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=true, so the safety profile is covered; the description adds genuine behavioral value by disclosing that an absent or non-running agent returns responsive=False with an explanation rather than raising an error. It does not mention timeouts or any auth/prerequisite needs, 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?

Front-loaded [READ] tag, then purpose, then the non-obvious error-handling behavior, then Args. Every sentence carries information and there is 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?

With no output schema, the description takes on return-value explanation and does cover the failure shape (responsive=False with explanation). It stops short of describing the success shape (responsive=True payload, other fields returned) and timeout semantics, which would fully close the gap.

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 does: vmid (numeric Proxmox VM id), target (Proxmox target name from config), and node with a meaningful default behavior ('omit to auto-locate the VM'). Minor gap: no format/constraint details for target or vmid ranges.

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 (ping), a specific resource (the VM's QEMU guest agent), and the exact intent (check it is installed and responsive). No sibling in the list covers guest-agent probing, so an agent can distinguish it immediately.

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 purpose implies when it is useful (verifying the agent before guest-level operations), and the note about non-running agents returning responsive=False hints at expected usage. However, it names no explicit when-to-use trigger or alternative tool for related checks (e.g. guest_health_rca), leaving routing to inference.

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=false, idempotentHint=false, destructiveHint=true, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses the async task model ('Returns task UPID', pointing the agent at task_status) and the downtime implications of each mode ('snapshot' = no downtime). It stops short of stating whether the guest must be running or what happens on failure.

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 with the operation summary, followed by a compact Args list. Given 0% schema coverage the parameter list is earned rather than padding. The [WRITE] tag is mildly redundant with the destructive annotation but serves as a fast scan cue.

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 5-parameter destructive async write, the description covers purpose, all parameters, mode trade-offs, and the return value (task UPID), with annotations handling safety. With no output schema, the 'Returns task UPID' line is the essential return-value disclosure. Preconditions and failure behavior are the remaining gap.

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 parameter burden and does so well: it defines vmid, storage (with a capability constraint and cross-reference), describes mode's three values including semantics/default, and explains node's auto-locate behavior and target. This meaningfully exceeds the bare schema titles.

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: 'Create a vzdump backup of a VM/CT to a storage.' This is readily distinguishable from sibling tools like vm_snapshot_create (snapshot vs vzdump backup), backup_restore (restore vs create), and backup_list. The [WRITE] tag immediately frames the operation class.

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 the verb 'backup'. The description routes the agent to storage_list / storage_content for finding a valid storage, which is helpful, but it gives no explicit when-to-use/when-not guidance versus alternatives such as vm_snapshot_create, and no statement of preconditions (guest state, free storage space).

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, idempotentHint=false, destructiveHint=true, and the description reinforces the write nature and adds behavior beyond them: async execution, UPID return, explicit instruction not to re-issue, a preview path, and the inverse operation. This is meaningful context an agent needs for safe invocation.

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-loads the write tag, action, return value, and inverse in the first line, then async/preview guidance, then an Args list. Every sentence adds 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?

For a six-parameter mutation tool with no output schema, the description covers the return value (task UPID), the async workflow, preview capability, and every parameter. Nothing an agent needs to invoke it correctly is missing.

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, and it documents all six parameters: vmid as source, newid as unused target id, name as optional, dry_run preview, target from config, and node with the useful 'omit to auto-locate' semantics. This fully compensates for the empty schema descriptions.

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 ('Clone a VM to a new vmid') and adds scope details (returns task UPID, inverse is vm_delete(newid)) that distinguish it from siblings like vm_migrate or vm_snapshot_create. An agent can identify the operation and its counterpart 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?

Gives concrete operational guidance: poll completion with task_status rather than re-issuing, and use dry_run=True to preview. It names the follow-up tool (task_status) and inverse (vm_delete). It stops short of explicit when-not-to-use guidance against sibling tools, but the context 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 readOnlyHint=true, so the '[READ]' tag is largely redundant. The description does add that node is optional and the VM is auto-located when omitted, plus that vmid/target come from Proxmox config, which is modestly useful beyond the annotations, but it says nothing about failure behavior for an unknown vmid.

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 with the operation tag and a one-line purpose, followed by a compact Args block. The per-parameter restatement is justified given the schema has zero descriptions, so there is little waste.

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 read-only 3-parameter tool with no output schema, the description covers the purpose and every parameter adequately. The absence of output-schema documentation is not a gap since readOnlyHint and the field list convey the shape of the result.

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 and documents all three parameters: vmid as the numeric Proxmox VM id, target as the Proxmox target name from config, and node with its omit-to-auto-locate behavior. 'target' remains somewhat vague, but each parameter gets meaningful context beyond the bare schema types.

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 a VM's config') and enumerates the returned fields (cores, memory, ostype, boot order), which lets an agent know exactly what data comes back. It does not, however, distinguish itself from the sibling vm_get, leaving some ambiguity about which to pick.

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, no conditions for choosing it over vm_get or other VM tools, and no exclusions. The only usage-adjacent note ('omit to auto-locate the VM') is really a parameter default, not 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 destructiveHint=true and readOnlyHint=false, but the description adds material context beyond them: irreversibility, absence of an undo token, the audit trail location (~/.proxmox-aiops/audit.db), the confirmation requirement, and the dry-run escape hatch. This is exactly the behavioral detail a mutation tool needs.

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-loads the [WRITE] marker and the irreversible warning before any parameter detail, then lists args compactly. Every sentence carries unique 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?

For a destructive delete with no output schema, the description is complete: it covers safety warnings, confirmation protocol, audit behavior, preview mode, and all four parameters. Nothing an agent needs to invoke this safely is missing.

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 and does so for all four parameters: vmid ('numeric Proxmox VM id'), dry_run ('preview without destroying'), target ('Proxmox target name from config'), and node ('omit to auto-locate the VM'). The auto-location behavior for node is genuinely non-obvious detail not present in 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?

States a specific verb (destroy) and resource (VM), with the [WRITE] tag and 'Permanently' scoping it clearly against reversible siblings like vm_stop, vm_shutdown, and vm_reboot. An agent can distinguish this from every other vm_* tool without opening a 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?

Gives clear operational context: 'Confirm with the user before calling' and 'Pass dry_run=True to preview.' The 'IRREVERSIBLE — no undo token' note implicitly contrasts with the undo_* siblings. However, it never explicitly names the reversible alternatives (vm_stop, vm_shutdown) that an agent should prefer, so it falls short of the explicit when-not guidance a 5 requires.

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 readOnlyHint annotation already establishes the safe-read profile, and the '[READ]' prefix merely restates it. The description does add one behavioral detail beyond annotations: omitting 'node' triggers auto-location of the VM. It says nothing about pagination, result ordering, or behavior when the VM has no rules.

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 one-line purpose statement followed by a compact Args block, with the key fact (what is listed) front-loaded. The 'Args:' boilerplate is slightly formulaic but each line adds real information and there is no 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?

For a read-only three-parameter tool with no output schema, the description covers purpose, parameter meaning, and the optional-node behavior. It omits any indication of the return shape (rule fields, empty-result behavior), which is the main remaining gap.

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 burden, and it does explain all three parameters: vmid as a numeric Proxmox VM id, target as a target name from config, and node with its omit-to-auto-locate default. It falls short of defining valid target values or expected formats, but it compensates well for the empty schema docs.

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 gives a specific verb and resource (list firewall rules) scoped to a VM, which implicitly separates it from cluster-wide tooling such as cluster_firewall_status. It does not explicitly name or compare against 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?

The [READ] tag and the resource name imply this is the inspection tool for VM-level firewall rules, but there is no explicit when-to-use or when-not-to-use guidance, and no mention of the cluster-level firewall alternative. The 'omit to auto-locate' note is a usage hint for one parameter rather than selection 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?

The annotations already declare readOnlyHint=true, so the '[READ]' prefix adds nothing. The description does contribute one genuinely useful behavioral detail: omitting 'node' triggers auto-location across nodes. It says nothing about what 'status detail' contains or how failures surface, which matters since there is no output schema.

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 front-loaded purpose sentence followed by a compact args list — every line earns its place. The '[READ]' tag is redundant with the readOnlyHint annotation and could be dropped, but the overall structure 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?

For a three-parameter read tool with no output schema, the definition should describe what 'status detail' actually returns; instead the return content is left entirely vague. Parameters and read semantics are covered, but the missing return-shape information leaves a real gap.

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 parameter burden and largely succeeds: vmid is defined as a numeric Proxmox VM id with a pointer to vm_list, target is tied to the config, and node's omission semantics are explained. 'target' remains somewhat abstract ('Proxmox target name from config'), keeping it short of 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?

The description names a specific verb and resource ('Return current status detail for a single VM by vmid') and the word 'single' implicitly separates it from the list-oriented siblings such as vm_list and ct_list. It does not explicitly contrast itself with vm_config, which also targets one VM, so the differentiation is clear but not complete.

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 supplies one real usage cue — omit 'node' to auto-locate the VM across nodes — and points to vm_list for finding a vmid. However, it never states when to prefer this over vm_config or cluster_resources, so the when-to-use guidance 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 declare readOnlyHint=true, and the '[READ]' tag is largely redundant with that. However, the description adds real behavioral context: the scan scope falls back from a named node to the configured default to all cluster nodes, and it names the fields returned, which matters since there is no output schema.

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-loads the core purpose, then scoping rules, then the sibling alternative, then per-argument notes. Every sentence carries information; no 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 no output schema it usefully lists returned fields, and it covers both optional parameters and their defaults. It stops short of mentioning result size, pagination, or ordering behavior across cluster nodes.

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%, so the description carries the full burden, and it does document both parameters (target = config target name, node = node name with fallback semantics). The node explanation ('configured node / all nodes') is slightly ambiguous about which applies when, keeping it short of 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?

States a specific verb ('List') and resource ('QEMU VMs') and previews the returned fields (name, vmid, status, cpu, mem). It also implicitly separates itself from container listing via 'QEMU' and from per-VM detail via the vm_get pointer.

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?

Explicitly routes single-VM full-status needs to vm_get, and explains the scoping choices (given node, configured default node, or all cluster nodes). It lacks guidance on when to prefer this over other list-style siblings such as cluster_resources or ct_list.

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 readOnlyHint annotation already declares the safety profile, and the '[READ]' prefix merely restates it. The description does add one piece of behavior beyond the annotation: the shape of the return ('name + description'), which matters since there is no output schema. It says nothing about error behavior when the VM or snapshots are absent, so it stays at a baseline-plus level.

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

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

Front-loaded one-line summary followed by a compact Args block; every line maps to a parameter or the output shape. The '[READ]' tag is mildly redundant with the annotation but costs almost nothing.

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 simple read-only list tool with no output schema, the description covers purpose, all three parameters (including the optional auto-locate behavior), and the returned fields. Only edge behavior (VM not found, empty snapshot list) is unaddressed.

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 and does document all three parameters in the Args block. The node entry adds genuinely useful semantics ('omit to auto-locate the VM') that the bare `default: null` schema cannot convey; vmid and target descriptions are terse but adequate.

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 snapshots for a VM') and adds the scope of the result ('name + description'), so the agent knows exactly what comes back. It does not, however, distinguish itself from the sibling snapshot tools (vm_snapshot_create, vm_snapshot_delete, vm_snapshot_rollback), which is the only thing keeping it from 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?

No statement of when to use this tool versus the snapshot siblings or vm_get/vm_config, and no prerequisites or exclusions. An agent must infer that this is the read-only counterpart to the create/delete/rollback tools purely 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 destructive=true and idempotent=false, so the safety profile is covered. The description adds value beyond that: the asynchronous execution model, the UPID return, the ability to dry-run, and the existence of a reversing operation. It doesn't cover permission requirements or the state of the source node after migration.

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 with the [WRITE] tag, verb, and return, followed by the async caveat, then a compact Args block. Every sentence carries information, and the most decision-relevant facts appear first.

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 destructive, async mutation tool with no output schema and 0% schema description coverage, the description is complete: it explains the return (UPID), how to track completion, how to preview safely, and every parameter. Nothing an agent needs to call it correctly is missing.

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%, so the description carries the full burden and does so completely — it documents all six parameters, including non-obvious semantics like online=True meaning live migration, node being optional with auto-location, and target coming from config. This meaningfully exceeds the bare 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 and resource ('Migrate a VM to another node'), names the return value ('Returns task UPID'), and notes the inverse operation ('migrate back'). An agent can immediately tell this apart from clone/move_disk siblings because the resource scope (whole VM to another node) is explicit.

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 concrete operational guidance: the tool is asynchronous and completion should be polled via task_status, and dry_run=True previews without migrating. It stops short of naming when NOT to use it or which conditions favor alternatives, but the polling and preview guidance is clear and actionable.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real context beyond that: the operation is asynchronous and returns a task UPID, and it conditionally records a reverse move as an undo token when source storage is known — useful recovery information an agent cannot get from the annotations.

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 with the write marker, purpose, return value, and async flag before any detail, which is good structure. Minor redundancy: dry_run is explained both in the prose paragraph and again in the Args list, costing a sentence that could have carried other 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 7-parameter destructive, async mutation with no output schema, the description covers the essentials: what it does, that it is async with a UPID, the undo-token behavior, and every parameter's meaning. It stops short of stating permissions, whether the VM must be powered off, or how the task result should be polled.

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 parameter burden, and it documents all seven parameters with meaningful semantics — notably 'delete: Remove the source copy after the move completes' and 'node: omit to auto-locate the VM'. It also gives a concrete disk-key example ('scsi0'); only 'target' remains vaguely defined ('Proxmox target name from config').

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?

Opens with a specific verb+resource+scope: '[WRITE] Move a VM disk to another storage', which is unambiguous and separable from siblings like vm_migrate (whole VM) and vm_resize_disk (size change). It also states the return value ('Returns task UPID') and the async nature in the first line.

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 one concrete usage condition ('Pass dry_run=True to read the disk's current placement and preview the move') and notes the undo token is only recorded when the source storage is known. However, it never states when to choose this over vm_migrate or vm_resize_disk, nor any preconditions (e.g. VM must be stopped, storage must be shared).

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=false, idempotentHint=false and destructiveHint=true, so the safety profile is covered. The description adds genuinely new context beyond the annotations: it flags that no undo token is produced and that a reboot has no inverse, which is meaningful given the undo_list/undo_apply siblings in this toolset.

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 with the '[WRITE]' marker and the core action, followed by a one-line warning and a compact Args block. Every element earns its place with no 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?

For a 3-param mutation tool with no output schema, the definition covers action, safety caveat, and all parameters. The only gap is return behavior (e.g., whether a task id/UPID is returned for polling via task_status), which would help since no output schema exists.

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 argument semantics. It documents all three params: vmid as a 'Numeric Proxmox VM id', target as a 'Proxmox target name from config', and node with the operational cue 'omit to auto-locate the VM' — the latter adds behavior the bare nullable schema does not convey.

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 ('Reboot a VM') and adds a meaningful qualifier ('graceful') that distinguishes it from the hard-stop siblings vm_stop/vm_shutdown. It does not explicitly name those siblings, so an agent must still infer reboot vs. stop/start 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?

The description says what the tool does but gives no when-to-use guidance: it never states when to prefer a reboot over vm_shutdown followed by vm_start, nor any prerequisites such as the VM being running. The '[WRITE]' tag and 'graceful' hint at context but stop short of 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 destructiveHint=true and idempotentHint=false, but the description adds non-obvious behavior: prior values are captured so a reverse reconfigure is recorded as the undo token. That undo/reversibility context is genuinely valuable for a destructive mutation and goes beyond the structured hints. It doesn't mention whether a running VM must be restarted for changes to take effect, which is a remaining 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?

Front-loaded with the [WRITE] tag and the core action, followed by constraints and a clean Args block. Every sentence carries information, though the phrasing is slightly verbose in places.

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 mutation tool with no output schema and 0% schema coverage, the description supplies the parameter contract, the destructive/atomic behavior, and the dry_run escape hatch. It omits whether a reboot is needed for the change to take effect, which an agent would otherwise have to discover.

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 full load, and it documents every parameter: vmid, cores, memory (with MiB units), dry_run, target, node. It also explains the omit-to-leave-unchanged convention and node auto-locate behavior. 'target' is only described as 'from config', which is the one thin spot.

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 ('Change a VM's cores and/or memory (MiB)') and tags the operation as a write, which cleanly separates it from disk-related siblings like vm_resize_disk and vm_move_disk. An agent can identify the tool 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?

Gives a real precondition ('Provide at least one of cores / memory') and a concrete read/preview path ('Pass dry_run=True to read the current cores/memory and preview the change'). It does not explicitly name an alternative sibling or state when not to use it, so it falls just 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 destructiveHint=true and idempotentHint=false, but the description adds the crucial operational facts: growth is irreversible with 'No undo token', and dry_run provides a preview path. This tells the agent exactly what is at risk and how to mitigate it, well beyond the structured hints.

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-loads the write tag and the grow-only/irreversibility warning before the Args block, so the highest-risk facts land first. The Args list is terse and each entry adds real information rather than restating the parameter 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?

For a destructive, non-idempotent mutation with no output schema, the description covers the essential risk surface (irreversibility, dry_run) and every parameter. It omits prerequisites such as required VM power state or permission scope, which would round it out, but nothing critical is missing.

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 and does: it documents all six parameters, gives concrete disk-key examples ('scsi0', 'virtio0', 'sata0'), specifies the size format ('+<N>G' increment or larger absolute size), and explains that node may be omitted to auto-locate. This fully compensates for 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 and resource ('Grow a VM disk') and immediately narrows scope with 'GROW-ONLY — shrink requests are refused.' An agent can distinguish this from disk-adjacent siblings like vm_move_disk or vm_reconfigure 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?

Gives clear operational context: grow-only semantics, refusal of shrink requests, and 'Pass dry_run=True to preview' for safe exploration. It stops short of naming alternatives (e.g., vm_reconfigure) or stating prerequisites like VM power state, so it is clear context without explicit alternative 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 declare a destructive write (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the safety profile is covered. The description adds genuinely useful context beyond that: the shutdown is graceful/ACPI rather than a hard power-off, and dry_run provides a no-op preview. It doesn't mention timeout behavior or what happens to unsaved data, but for a mutated state this is solid added value.

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 with the write marker, operation, and sibling contrast in the first line; the Args block is terse. Minor redundancy in restating parameter names, but every line earns its place.

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 destructive four-parameter mutation with no output schema, the description covers write intent, graceful-vs-hard semantics, preview capability, and all arguments. It leaves only timeout/guest-dependency edge cases unstated.

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 and does: vmid is the numeric Proxmox id, dry_run previews, target comes from config, and node can be omitted to auto-locate the VM. That last point is behavioral meaning the schema does not convey.

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 (graceful ACPI shutdown of a VM) and immediately distinguishes it from the sibling vm_stop by naming the hard alternative and the inverse vm_start. An agent can route between vm_shutdown, vm_stop, and vm_start 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?

Explicitly contrasts with the hard vm_stop and points to vm_start as the inverse, which gives a clear condition for selection. It also recommends dry_run=True for preview. It stops short of stating when-not to use it (e.g., only for ACPI-capable guests), so it's clear but not fully exhaustive.

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=false, destructiveHint=true, idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: a dry_run preview mode, the uniqueness constraint on name (which clarifies the non-idempotent behavior), and node auto-location when omitted. It does not mention return/async behavior or snapshot storage cost.

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 purpose, inverse, and preview hint, followed by a compact args list. The args block is justified by 0% schema description coverage, though 'name must be unique' slightly duplicates the uniqueness statement in the behavioral framing.

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 write tool with no output schema and a 5-param surface, the description covers identity, parameters, safety framing, and a preview path. It omits what the call returns or whether it is synchronous, which is the main remaining gap.

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 and does so for all five parameters: vmid (numeric Proxmox VM id), name (unique per VM), dry_run (preview only), target (from config), node (omit to auto-locate). It supplies semantics the bare schema types cannot convey.

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 ('Create a named snapshot of a VM') and immediately names the inverse tool vm_snapshot_delete, which cleanly separates it from the destructive and rollback siblings. The [WRITE] tag further front-loads the operation class.

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 operational context: the inverse operation is named and the dry_run preview path is called out. It does not, however, say when to prefer this over vm_snapshot_rollback or any prerequisite state (e.g. VM running/stopped), so it stops short of full alternative 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 carry destructiveHint=true and idempotentHint=false, so the safety profile is known. The description goes beyond them by spelling out the consequence ('destroys a rollback point — no undo') and by disclosing a dry_run preview mode, which is not represented in the annotations.

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-loads the operation class, then the critical consequence, then the preview escape hatch, then a compact Args block. No sentence is padding, and the most decision-relevant information comes first.

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 destructive 5-parameter tool with no output schema, the description covers destination, consequence, preview, and every argument, so an agent can call it correctly. It stops short of noting any return value or follow-up verification, but with no output schema declared that is a minor omission.

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 does: all five parameters are explained with behavior, not just types (name points to vm_snapshot_list, node may be omitted for auto-location, target comes from config, dry_run previews). Only vmid's explanation ('Numeric Proxmox VM id') is largely restating the schema type.

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 precise verb+resource (delete a named snapshot from a VM) with a clear scope modifier ([WRITE], 'no undo'). An agent can distinguish it immediately from vm_snapshot_create, vm_snapshot_rollback, and vm_list_snapshots among the listed siblings.

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 actionable usage context: it cross-references vm_snapshot_list for discovering the snapshot name and offers dry_run=True as a preview path. It does not, however, contrast itself with the sibling operation vm_snapshot_rollback (the other destructive snapshot verb), so the routing guidance is clear but not exhaustive.

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?

Goes well beyond the destructiveHint=true annotation by disclosing that the action is IRREVERSIBLE, that there is no undo token, that the discarded state cannot be recovered, that user confirmation is required, and that dry_run provides a preview. This is exactly the extra context an agent needs before a destructive call.

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-loads the operation type and the irreversibility warning before anything else, then uses a compact Args block. Every sentence earns its place with no 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?

For a destructive mutation with no output schema, the description supplies the safety-critical facts (irreversibility, no recovery, confirmation, dry_run) plus all parameter meanings, so nothing essential is missing.

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?

With 0% schema description coverage, the description carries the burden and does document all five parameters, including the non-obvious ones ('node: omit to auto-locate the VM', 'target: Proxmox target name from config'). It lacks format/enum detail but adds real meaning beyond the bare 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 and resource ('Roll a VM back to a snapshot') with a [WRITE] tag, clearly distinguishing it from siblings like vm_snapshot_create, vm_snapshot_delete, and backup_restore. An agent can identify the operation 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?

Explicitly tells the agent to 'Confirm with the user' and to 'Pass dry_run=True to preview', and routes to vm_list_snapshots for obtaining snapshot names. It does not, however, compare against alternatives such as backup_restore, so it stops short of full when/when-not 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 readOnlyHint=false, idempotentHint=false, and destructiveHint=true, so the safety profile is covered. The description adds genuine value by disclosing that it returns a Proxmox task UPID, signaling an asynchronous operation the caller must poll via task_status — context not derivable from the annotations.

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 with the action, tag, and return value in one sentence, followed by a compact args list. The 'Inverse: vm_stop' clause is mildly extraneous but earns its place as a routing hint; no filler otherwise.

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

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

With no output schema, the description correctly surfaces the return value (UPID), and all three parameters are explained. For a simple start operation this is close to complete, with only precondition/auth details 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 description coverage is 0%, so the description must compensate, and it does: vmid, target, and node are each given meaning, including the useful behavioral note that omitting node auto-locates the VM. It stops short of documenting types or constraints, but substantially fills 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+resource ('Start a VM'), tags the write semantics with [WRITE], and names its inverse (vm_stop). This lets an agent separate it from vm_stop, vm_shutdown, vm_reboot, and the container sibling ct_start without opening a 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 'Inverse: vm_stop' relation implies the complementary operation, and the [WRITE] tag hints at state-changing intent. However, it never states when to prefer this over vm_shutdown/vm_reboot, nor any precondition (e.g. VM must be stopped), leaving usage largely inferred.

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 destructiveHint=true but the description adds the concrete consequence an agent needs: the guest filesystem may be left dirty, this is an immediate power-off, actions are audited to ~/.proxmox-aiops/audit.db, and dry_run=True previews. That is exactly the behavioral detail annotations cannot carry.

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 one-line summary is front-loaded with the [WRITE] marker, version scope, and return value, followed by a compact risk/audit note and a short Args block. No sentence is filler, and the Args block is justified by the 0% schema coverage.

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 destructive mutation tool with no output schema and no schema descriptions, the definition covers the critical ground: side effects, return value (task UPID), audit behavior, dry-run safety, and every parameter. An agent has everything required to 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?

Schema description coverage is 0%, so the description must carry the burden, and it does document all four parameters including defaults ('dry_run: If True, preview without stopping', 'node: ... omit to auto-locate the VM'). The entries are terse and 'target: Proxmox target name from config' is somewhat opaque, but coverage is complete.

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 ('Hard-stop (power off) a VM'), tags it as [WRITE], and explicitly separates it from the graceful path by noting it is 'not a graceful guest shutdown'. Naming vm_start as the inverse, alongside vm_shutdown in the sibling list, lets an agent place it precisely.

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 clear usage context: immediate power-off versus graceful shutdown, and points to the inverse operation vm_start. It stops short of explicitly naming vm_shutdown as the alternative to prefer when a clean guest shutdown is wanted, so the routing decision is implied rather than spelled out.

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