pve-mcp

pve_destroy_guest

Delete a VM or container and its disks; the guest must be stopped, and explicit confirmation is required to proceed.

Instructions

Delete a VM or container and its disks. It must be stopped. Needs confirm=true.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "vmid": "<vmid>"
    },
    "name": "pve_destroy_guest"
  }
}

Input Schema

Name	Required	Description	Default
`vmid`	Yes
`purge`	No
`confirm`	No
`timeout`	No
`destroy_unreferenced_disks`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 10, 2026

TDQS

A3.9/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does disclose the two most consequential traits: the operation is destructive of disks as well as the guest, and it is gated behind a stopped state plus an explicit confirm flag. It still does not state that the action is irreversible, what error is returned if the guest is running, or what permissions are required.

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

Conciseness5/5

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

Three short sentences with no filler, ordered so the destructive action and its scope come first, followed by the two invocation requirements. Every sentence earns its place.

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

Completeness3/5

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

For a destructive, unannotated, 5-parameter tool with no output schema, the core invocation path is covered but important gaps remain: purge and timeout behavior, the meaning of the two disk-related booleans defaulting to true, and failure behavior when the guest is running. Adequate but not complete for this risk level.

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

Parameters3/5

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

Schema description coverage is 0% across 5 parameters, so the description must compensate. It explains confirm (must be true) and implies disk destruction, but purge, timeout, and destroy_unreferenced_disks semantics are left entirely undocumented, so compensation is only partial.

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

Purpose4/5

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

States a specific verb and resource plus the destruction scope: 'Delete a VM or container and its disks.' An agent can distinguish this from pve_create_guest or pve_clone by the verb alone. It does not explicitly name a sibling it supersedes or overlaps with, so it stops 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.

Usage Guidelines4/5

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

Gives two concrete preconditions: the guest 'must be stopped' and the call 'needs confirm=true'. That is real operational context an agent needs before invoking. It omits what to do when the guest is running (e.g., power it off first via a sibling) and any when-not-to-use guidance.

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