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

Without annotations, the description fully carries the burden and discloses side effects: creates backup archive, stop mode shuts guest down. It explains that backups may outlast the task wait window and how to follow up with pve_task_status, along with return JSON structure.

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

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

The description is front-loaded with the main action and includes necessary details without fluff. However, it could be more structured (e.g., bullet points for parameters) for easier scanning.

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 tool's complexity (multiple parameters, side effects, long-running tasks), the description covers the key aspects. It explains return JSON fields even without the output schema shown, but could mention potential errors or prerequisites.

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%, but the description adds meaning for all parameters: vmid, node, storage, mode (with options), compress (default and valid values), and notes (template variables). This compensates fully.

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 it creates a vzdump backup of a VM or container, specifying the resource (QEMU VMs and LXC containers) and operation. It distinguishes from sibling tools like pve_backup_restore and pve_snapshot_create.

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 provides context for when to use the tool (creating backups) and mentions mode options, but does not explicitly state when not to use it or alternatives. It does offer guidance on handling long-running backups via task status tracking.

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 beyond the destructiveHint annotation by detailing conditions for destructiveness: overwriting requires force=true and confirm=true, restoring to new vmid is safe. Also discloses waiting behavior with PVE_MCP_TASK_WAIT and return JSON structure, providing comprehensive behavioral context.

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

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

Well-structured, front-loaded with the main action, and each sentence adds unique value without redundancy. Appropriate length for the tool's complexity, using paragraphs and formatting effectively.

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 tool's complexity (6 params, destructive behavior, optional follow-up), the description covers prerequisites, conditions, timeout handling, and return format. Output schema exists (implied), but description already summarizes return fields, ensuring the agent can use it correctly without additional documentation.

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 adds meaning for key parameters: explains 'archive' as volid, 'node' as required due to auto-resolution, 'storage' for override, and discusses force/confirm in context. However, node and vmid are not explicitly described beyond being required, and other params like confirm are only implied.

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 the tool's action: 'Restore a backup archive to a VM/CT id.' It specifies the types of archives (vzdump/PBS), guest inference from name, and distinguishes itself from sibling tools like pve_backup_create and pve_vm_clone by focusing on restoration from backups.

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 explicit when-to-use guidance: applies to specific archive types, node requirement explained, and differentiates between restoring to new vs existing vmid. It also mentions the need for force/confirm when overwriting, and suggests alternative follow-up with pve_task_status for long-running tasks.

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 readOnlyHint annotation, description adds return format (JSON list), field details (quorate, node count, online, ip, nodeid), and source endpoint, providing rich behavioral context without contradiction.

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

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

Extremely concise: two sentences plus source line, with clear formatting and no redundant words, every part adds value.

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 no parameters, with output schema present and readOnlyHint provided, description covers scope, return structure, and source, making it fully complete for an agent to understand the 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?

No parameters exist, so schema coverage is 100%; description adds no parameter info but baseline for zero-param tools is 4, and it sufficiently explains the tool's output.

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?

Description clearly states the tool retrieves cluster and node health, including quorum, and specifies it works for whole cluster or single unclustered node, distinguishing it from sibling tools like pve_node_status which likely target individual nodes.

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 clear context on when to use (get health and quorum) and applicability (cluster or single node), but lacks explicit guidance on when not to use or specific alternatives.

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?

Description adds substantial behavioral detail beyond readOnlyHint: lists applicable guest types (VM/CT), explains aggregation logic (scans all backup-capable storages), and specifies return format with field names and ordering.

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?

Well-structured with clear focus on purpose and behavior. Could be slightly more concise but front-loaded with essential 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?

Thoroughly covers all aspects: what the tool does, how it works, return fields, filtering options. Complete for a tool with only 2 optional parameters.

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 description explains purpose of both parameters (vmid filters to one guest, storage filters to one storage). Adds meaning beyond 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?

Clearly states 'List backup archives across storages' with optional filtering. Distinguishes from siblings like pve_storage_content by describing itself as a convenience wrapper that scans all backup-capable storages.

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?

Describes when to use (cross-storage listing, filterable by vmid/storage). Does not explicitly exclude alternatives but implies usage context. Sibling tools provide further differentiation.

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 set readOnlyHint: true, so the description's additional details (return format, units, source endpoint) add value beyond the annotation. It explains CPU as a 0..1 fraction, memory/disk bytes with human-readable companions, and uptime in seconds with _human version.

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

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

The description is four sentences long, front-loading the primary purpose in the first sentence. Subsequent sentences provide essential details without redundancy, making it concise and well-structured.

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

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

With no parameters and an existing output schema, the description complements the schema by explaining the meaning of specific fields (cpu, mem, disk, uptime) and their units. This is complete for a zero-parameter list tool with no behavioral caveats needed.

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

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

There are no parameters (0 params), so schema coverage is 100%. The description does not need to add parameter information; the baseline of 4 is appropriate given no params exist.

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 'List all nodes with CPU, memory, disk usage and online status,' providing a specific verb and resource with detailed field enumeration. It distinguishes from sibling tools like pve_node_status or pve_cluster_status by emphasizing all nodes and the specific metrics.

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 notes 'Applies to: every node in the cluster,' which clarifies the scope. It does not explicitly state when not to use or name alternatives, but the context is clear and suitable for a zero-parameter tool with straightforward functionality.

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. Description adds that PVE includes a synthetic 'current' entry, parent links form a tree, and returns a JSON list with specific fields. No contradiction. Helpfully details return format and source endpoint.

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?

Four sentences: purpose, applicability, return format, source. Every sentence adds value. No fluff. Well-structured.

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 output schema present, description covers parameters and return fields. Given simplicity, no 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 coverage is 0%. Description explains vmid locates the VM, node is optional and auto-resolved, adding meaning beyond the schema. No further details on formats, but sufficient.

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 'List snapshots of one VM or container.' It uses a specific verb (list) and resource (snapshots of one VM/container), and distinguishes from sibling tools like pve_snapshot_create, pve_snapshot_delete, etc.

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?

Description states it applies to a single VM/CT located by vmid, with node optional and auto-resolved. It mentions the synthetic 'current' entry and parent links, providing context. No explicit when-not-to-use or alternatives, but it's 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 indicate readOnlyHint=true, and the description confirms a read operation. It adds value by detailing output fields (total/used/avail with human-readable companions), which goes beyond annotations. No contradictions.

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

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

Three sentences with no filler: first sentence states purpose, second explains node parameter with API paths, third describes output format. Front-loaded and 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?

Given the simple nature of the tool (list storages with one optional parameter) and the presence of an output schema, the description covers all necessary aspects: purpose, parameter behavior, and output format.

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

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

The schema description coverage is 0%, but the description fully explains the single parameter 'node', specifying its effect on the API endpoint and the scope of results. This compensates completely for the lack of schema documentation.

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?

Description clearly states 'List storages with usage figures' and explains the difference between node-specific and cluster-wide views, effectively distinguishing from sibling tools like pve_storage_content.

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 describes when to use the node parameter (node's view) versus when to omit it (cluster-wide view), providing clear context for usage. However, it does not explicitly mention when not to use this tool or suggest alternatives.

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 description adds significant behavioral context beyond the readOnlyHint annotation: it specifies the order (newest first), aggregation behavior, and the exact fields returned (upid, type, id, user, status, starttime/endtime). No contradictions with 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 description is concise (3 sentences) and front-loads the core purpose. Every sentence adds value without unnecessary fluff.

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 presence of an output schema, the description provides enough context: it lists the return fields and explains behavior for all parameters. It is complete for a read-only listing 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 coverage is 0%, so the description fully compensates by explaining each parameter: node filters by node, limit caps entries, errors_only filters to failed tasks. This adds meaning beyond the schema property names.

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

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

The description clearly states 'List recent tasks, newest first' and specifies it applies to task history. It differentiates from sibling tools like pve_task_status by describing aggregation across nodes and the specific resource (task history).

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 explains when to use the node parameter (to filter by node) and the roles of limit and errors_only. However, it does not explicitly mention when not to use this tool or suggest alternatives for specific tasks.

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=true, and the description adds the source API endpoint and details about the return format (JSON list with fields and _human variants). It goes beyond annotations by explaining what the output contains, which helps the agent understand the 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 description is very concise: one sentence for purpose, then a brief list of applicability and filters, then return format. It is front-loaded with the core action and uses structured formatting (bullets) for clarity. No wasted 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?

With an output schema present, the description explains the return format sufficiently, including key fields and human-readable variants. It does not mention pagination or limits, but for a typical list tool this is adequate. The source endpoint is also noted, adding completeness.

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%, but the description lists all three parameters (node, type, status) and explains their possible values (e.g., type can be 'qemu' or 'lxc'). This adds essential meaning beyond the raw schema, which only has type definitions.

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 'List QEMU VMs and LXC containers across the cluster.' The verb 'List' and the resource (VMs and containers) are specific. It distinguishes from siblings like pve_vm_status (single VM status) and pve_cluster_status (cluster-wide info).

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?

Describes the tool as listing both VMs and CTs with optional filters (node, type, status). While it doesn't explicitly say when not to use or name alternatives, the context from sibling tools implies this is for broad listing with optional filtering. It provides clear context for use.

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 provide readOnlyHint=true, indicating a safe read operation. The description adds value by detailing the return structure (uptime, loadavg, cpu, memory, etc.) and the source API endpoint, giving the agent a clear picture of what to expect beyond the annotation's safety implication.

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

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

The description is well-structured with bullet-like formatting and front-loaded purpose. It includes a sentence about the source, which adds transparency but slightly increases length. Overall, every sentence serves a purpose and the description is concise enough for an agent to parse quickly.

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 tool's simplicity (single parameter) and presence of an output schema, the description is comprehensive. It details the return fields with examples, covers the parameter usage, and mentions the source. No gaps remain for an agent to make correct decisions.

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

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

Schema description coverage is 0%, so the description must compensate. It provides context that the node is identified by its name and gives an example ('pve1'), which adds meaning beyond the parameter name alone. However, it does not explain the format or constraints (e.g., valid node names), so the contribution is modest. Baseline for 0% coverage is 3.

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

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

The description clearly states it provides detailed status of a single node, specifying the exact fields (load, kernel, PVE version, memory). It distinguishes from sibling tools like pve_list_nodes (which lists nodes) and pve_cluster_status (cluster-level) by explicitly noting it applies to one node identified by name.

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 states it applies to one node identified by name (e.g., pve1), which implies when to use it. While it doesn't explicitly say when not to use alternatives, the context is clear: use for individual node status. Sibling tools cover different scopes (cluster, list, etc.), so the guidance is adequate.

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?

No annotations exist, so the description fully discloses behavior: side effects (disk space growth), timeout behavior (waits up to PVE_MCP_TASK_WAIT seconds), return format (JSON with task details), and the underlying REST API endpoint. This is comprehensive.

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

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

The description is four sentences, each with a distinct purpose: purpose, applicability, side effects and return, and API source. No fluff, information is front-loaded and well organized.

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

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

With an output schema (not shown) and no annotations, the description covers the return format, side effects, and parameter semantics for all but one parameter. It is thorough for a creation tool, though it could mention that snapshots are incremental or discuss retention briefly.

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 adds meaning for 4 of 5 parameters: vmid (locates VM/container), node (optional, auto-resolved), name (snapshot identifier), vmstate (RAM state for QEMU only). It does not explain the 'description' parameter, but the coverage is strong.

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 starts with 'Create a snapshot of a VM or container', a specific verb and resource. It further clarifies applicability to QEMU VMs and LXC containers, distinguishing it from sibling tools like pve_backup_create or pve_snapshot_delete.

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 specifies the tool applies to VMs and containers located by vmid, with node optional and auto-resolved. It also notes that vmstate=true is only for QEMU, providing guidance on when to use that parameter. While it does not explicitly contrast with alternative tools, 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?

Beyond the destructiveHint annotation, the description details side effects (frees disk space, guest unaffected), permanence (no rollback), wait behavior, and return fields. This fully informs the agent about the tool's 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 description is concise, front-loaded with purpose and destructiveness, followed by details and source. Every sentence adds value 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?

Given the presence of an output schema (implied by return JSON description), the tool is fully specified: all parameters explained, side effects covered, waiting behavior noted. No gaps remain for an agent to guess.

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?

Despite 0% schema description coverage, the description explains all 4 parameters: name (snapshot to delete), vmid (integer), node (optional auto-resolved), and confirm (must be true). It adds critical context that the schema lacks.

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 the action ('Delete a snapshot of a VM or container') and the resource (snapshot). It distinguishes from sibling tools like pve_snapshot_create and pve_snapshot_rollback by focusing on deletion, making the purpose 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 description provides explicit usage constraints: requires confirm=true, applies to QEMU VMs and LXC containers, node is optional and auto-resolved. It does not explicitly say when not to use it, but the context is clear enough for an agent to decide.

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 destructiveHint annotation, the description details behavioral traits: discards all changes irreversibly, stops running guests unless RAM state included, waits up to PVE_MCP_TASK_WAIT seconds, and returns a specific JSON structure. This fully informs the agent of consequences.

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

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

The description is well-structured with a front-loaded destructive warning, clear sections for applicability, requirements, side effects, and return value. Every sentence adds value without 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?

Given the complexity of a destructive rollback, the description covers purpose, prerequisites, side effects, behavior during execution, and return format. The presence of an output schema further reduces the need to describe return values, making it 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?

The input schema has 0% description coverage. The description compensates by explaining that vmid locates the VM/container, node is optional and auto-resolved, and confirm=true is required for destructive action. It does not detail name, but its role is evident from context.

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 the tool's purpose: 'Roll a VM or container back to a snapshot.' It specifies the resources (QEMU VMs and LXC containers) and distinguishes it from sibling tools like pve_snapshot_create and pve_snapshot_delete by focusing on the rollback action.

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 explains requirements (confirm=true, destructive), side effects, and that it is irreversible. It does not explicitly compare with alternatives, but among siblings there is no other rollback tool, so the guidance is sufficient for correct use.

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. The description adds value by detailing return fields (volid, size, format, vmid, ctime) and the filtering parameter (content types). No contradictions with 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?

Four sentences, front-loaded with the main action. Each sentence adds value: purpose, scope, optional filter, output structure, and source. No redundant or vague phrases.

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 existence of an output schema (not shown), the description still summarizes return values well. It covers scope, filtering, and output format. Could mention prerequisites (e.g., storage existence) but not critical for a read-only list 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 has 0% description coverage, but the description explains the 'content' parameter with specific values (iso, backup, vztmpl, images) and implies the roles of 'node' and 'storage' via context ('on a node', 'on a storage'). Partial but effective compensation.

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 the verb 'List' and the resource 'contents of a storage on a node'. It distinguishes from sibling tools by specifying scope (one storage on one node) and optional content type filtering, differentiating it from pve_list_storage etc.

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 specifies the context: listing contents of a single storage on a single node with optional filtering. While it doesn't explicitly mention when not to use or list alternatives, the scope is clear and directly informs decision-making.

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 readOnlyHint annotation, the description details the returned fields (status, exitstatus, type, id, user, starttime) and the inclusion of log_tail on failure. This adds valuable behavioral context.

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

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

The description is concise, well-structured, and front-loaded with the core purpose. Every sentence adds value without unnecessary verbosity.

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 tool has an output schema and the description covers return fields, parameter details, and failure behavior, the description is complete for its purpose.

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 compensates by explaining that upid is required and node is optional, and that node can be parsed from the UPID if omitted. This adds meaning beyond the raw 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 clearly states the tool gets the status of a single task, identified by upid, and mentions it attaches the log tail on failure. This is specific and distinguishes it from sibling tools like pve_list_tasks.

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 explicitly says 'Applies to: any PVE task' and explains that node is optional and parsed from UPID. This provides clear usage context and when to use this tool.

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?

Discloses side effects: creates a stopped guest, asynchronous task behavior, and return structure. No annotations exist, so the description fully shoulders the burden of behavioral transparency.

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?

Well-structured with paragraphs and bullet points. Every sentence adds value, no fluff. Front-loaded with main action.

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 all aspects: operation, parameters, side effects, async handling, and return fields. Despite presence of an output schema, the description still provides necessary context.

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

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

Adds meaning beyond schema for key parameters: newid must be unused, full makes independent copy, storage sets target for full clone, target_node requires shared storage. Missing explanation for 'name' and 'node', but overall compensates for 0% schema coverage.

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?

Clearly states 'Clone a VM or container to a new vmid.' Uses specific verb and resource, and distinguishes from sibling tools like migration or backup.

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 explains when to use full vs linked clones, requirements (template for linked, full for non-template), and options like storage and target_node. Provides clear context for appropriate usage.

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 annotation already declares readOnlyHint=true, and the description adds value by detailing that the tool returns the complete config object with specific fields (cores, memory, disk entries, etc.) and that the node is auto-resolved. It does not disclose any side effects beyond reading, which is consistent with the annotation.

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

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

The description is concise, using one paragraph with a clear structure: main purpose, then details on location, return content, and source. Every sentence adds information without redundancy, though the source URL could be omitted as it's an implementation detail.

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 presence of an output schema (not shown) and simple input parameters, the description covers the essential aspects: what the tool does, how it identifies the VM, and what it returns. It omits error scenarios and prerequisites, but for a read-only config retrieval, this is sufficient.

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

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

The input schema has no descriptions for the two parameters, but the description explains both: vmid is the identifier, and node is optional and auto-resolved. This adds meaning beyond the schema's type/title information. While not exhaustive, it adequately covers the parameters.

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 it returns the full configuration of one VM or container, identifying the resource by vmid. The verb 'Full configuration' and the mention of returned fields specify the purpose. However, it does not explicitly differentiate from siblings like pve_vm_set_config (write) or pve_vm_status, leaving room for ambiguity.

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 provides no guidance on when to use this tool versus alternatives such as pve_vm_set_config for modification or pve_vm_status for status. There is no mention of prerequisites or context where this tool is preferred, leaving the agent to infer usage from the readOnlyHint annotation.

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 destructiveHint annotation, the description elaborates on permanent destruction, irreversibility, side effects, and task waiting behavior. No contradictions with 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?

Well-structured with clear sections and front-loaded purpose. Slightly verbose but every sentence adds value.

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 prerequisites, parameters, side effects, blocking behavior, return value, and source endpoint. Complete for a destructive tool with output schema.

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?

Adds meaning to all four parameters: explains vmid identification, node auto-resolution, confirm requirement, and purge effects. Schema has no parameter descriptions, so the description fully compensates.

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 the tool deletes a VM or container permanently, using specific verbs and resources. It is distinctly different from sibling tools like pve_vm_clone or pve_vm_power.

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 explicit prerequisites (guest must be stopped), required parameter (confirm=true), and additional option (purge). However, it does not explicitly mention alternative tools for non-destructive removal.

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 no annotations, the description fully discloses side effects (moves guest, brief downtime for CT), the waiting behavior (up to PVE_MCP_TASK_WAIT seconds), and the return JSON structure with exitstatus, failure details, and status running with upid. This is comprehensive.

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

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

The description is comprehensive but somewhat lengthy. It front-loads the main purpose and each sentence adds value. Slightly more conciseness could improve, but it remains well-structured and informative.

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

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

The tool has 4 parameters, 2 required, and an output schema (implied by context). The description covers migration behavior, parameter details, side effects, and return values. It provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 0%, so the description must compensate. It explains vmid, target_node, and online, but does not explicitly describe the 'node' parameter (only mentions it is optional and auto-resolved). The description adds meaning to most parameters but lacks explicit detail for one, resulting in partial compensation.

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 the action (Migrate) and the resource (VM or container). It distinguishes between QEMU VMs and LXC containers, and specifies the behavior for each. No sibling tool performs migration, so differentiation is not needed.

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 explains when to use online=true for live migration (running QEMU VM) and when it maps to restart migration (LXC containers). It also notes that the source node is optional and auto-resolved. It does not explicitly state when not to use the tool, 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?

With no annotations provided, the description carries full burden and excels: it discloses side effects (changes guest power state), waiting behavior (up to PVE_MCP_TASK_WAIT seconds), return format (JSON with vmid/node/type/action and task details), and the source endpoint. It also explains the difference between shutdown (clean) and stop (hard power-off), which is critical behavioral information.

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

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

The description is appropriately sized, front-loaded with the main purpose, and structured into logical sections. Every sentence adds necessary value (purpose, applicability, actions, side effects, return format, source). No fluff or 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 power state change tool with 4 parameters and an output schema, the description is complete: it covers input semantics, behavior (side effects, waiting), output format, and even source endpoint. Error cases are implied via 'failure + log_tail'. The tool's complexity is adequately addressed.

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

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

The schema has 0% description coverage, so the description fully compensates. It explains that node is optional and auto-resolved, vmid identifies the guest, action is an enum with specific meanings (including QEMU-only restrictions), and timeout applies to shutdown/reboot. This adds significant semantics 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?

The description explicitly states 'Change the power state of a VM or container' and specifies the applicable resource types (QEMU VMs and LXC containers) and the actions (start, shutdown, stop, reboot, suspend, resume). This clearly differentiates it from sibling tools like pve_vm_status or pve_vm_config.

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 provides explicit guidance on when to use each action: prefer shutdown over stop, suspend/resume are QEMU-only, containers use shutdown/stop/start. It does not explicitly compare to sibling tools but given the sibling set, this tool is the only one for power state changes. The guidelines are 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?

No annotations provided, so description carries full burden. It discloses side effects (disk enlargement, filesystem separate growth), waiting behavior, and return format. No contradictions.

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?

Well-structured with a one-line summary followed by details. All sentences add value, though slightly lengthy. Could be slightly more concise.

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 presence of output schema and four parameters, description is complete: covers side effects, usage constraints, return fields, and source endpoint. No 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%, but description compensates fully: explains vmid, disk (with examples), size (relative/absolute, units, grow-only constraint), and node (optional, auto-resolved). Adds significant meaning beyond 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 clearly states it grows a disk of a VM or container, specifies applicable types (QEMU VMs and LXC containers), and explains the key parameters. It distinguishes itself from sibling tools by focusing specifically on disk resizing.

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 clear usage context (grow only, with relative or absolute size) and mentions that filesystem must be grown separately. Could be more explicit about when to use this vs. other configuration tools, but still good.

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 no annotations, the description fully discloses behavior: it updates guest config, notes that most changes require restart, explains hotplug vs pending, mentions task waiting and source endpoints. This is comprehensive and transparent.

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

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

The description is well-structured with clear sections, front-loaded purpose, and no unnecessary words. Every sentence adds value, making it efficient and easy to parse.

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 complexity (nested config object, async/sync behavior, side effects), the description covers all key aspects: input parameters, behavior, output schema, task handling, and endpoints. It is complete for an agent to invoke 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%, but the description adds meaning by explaining 'config' is a dict of PVE config keys with examples, and notes 'node' is optional and auto-resolved. 'vmid' lacks additional semantic detail but is straightforward.

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 it changes configuration options of a VM or container, specifies the resource type (QEMU VMs and LXC containers), and distinguishes from siblings like pve_vm_config which is for reading. It uses a specific verb 'change' and identifies the resource 'configuration'.

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 when to use (to change config) and explains side effects and the need for restart, which helps decide if this tool is appropriate. However, it does not explicitly compare to alternatives like pve_vm_config or pve_vm_resize_disk, leaving room for ambiguity.

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=true, and the description reinforces this by describing a read operation. It details the returned data (status, cpu/memory, network/disk I/O, uptime, guest agent) and includes the source endpoint. This adds significant 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 description is concise (~4 sentences) with no fluff. It front-loads the purpose, then specifies scope, required parameter, optional parameter, and return data. Every sentence adds value.

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 status tool, the description covers all essential aspects: target, parameters, and return content. An output schema exists but is not provided; however, the description already enumerates key fields, so it is complete enough.

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 full burden. It explains that vmid identifies the VM/CT and node is optional and auto-resolved. This provides meaningful guidance for both parameters, compensating for the lack of 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?

The description clearly states 'Live runtime status of one VM or container.' It specifies the resource (single VM/CT) and the action (get status). Among siblings, this tool uniquely provides live status, distinguishing it from config, power, or backup tools.

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 provides explicit context: 'Applies to a single VM or CT, located by vmid (node optional and auto-resolved).' This tells the agent when to use it and that node can be omitted. It doesn't explicitly list when not to use, but the purpose is self-evident given the sibling set.

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