A
licenseA
qualityB
maintenanceMCP server for managing Proxmox VE clusters — provision VMs and containers, manage snapshots and
backups, execute commands, browse storage, and monitor resources through natural language
34
16
MIT
proxmox-mcp
by m3m0ng
Allows AI agents to read and operate a Proxmox VE homelab: view cluster status, manage VM/container power state, and provision new guests, with a safe, no-delete design.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@proxmox-mcpwhat VMs and containers are currently running?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
proxmox-mcp
A Python MCP server for Proxmox VE. It lets AI coding agents (Claude Code, Claude Desktop, Cursor, or any MCP-compatible client) see and operate your Proxmox homelab through natural language — read cluster status, power guests on and off, and provision new VMs/containers — but never delete anything. Deletion stays a human-only action, by design.
Ask your agent "what's running on my Proxmox?", "spin up a Debian container for a test", or "reboot the docker VM" — and it just works, safely.
Table of contents
Related MCP server: mcp-server-proxmox
What is this?
The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools. This project is an MCP server: a small program your AI client launches, which then talks to your Proxmox host's REST API on the agent's behalf.
The design goal is safe delegation: give an agent enough power to be useful (observe, operate, deploy) while making destructive actions structurally impossible. There is no "delete VM" tool here, and a runtime guard blocks any destructive API call even if one were added by mistake.
How it works
┌──────────────────┐ stdio ┌──────────────────┐ HTTPS ┌──────────────────┐
│ AI client │ ─────────► │ proxmox-mcp │ ─────────► │ Proxmox VE │
│ (Claude Code, │ │ (this server) │ API token │ (your homelab) │
│ Cursor, …) │ ◄───────── │ │ ◄───────── │ │
└──────────────────┘ tools └──────────────────┘ JSON └──────────────────┘Runs on your machine (wherever the AI client runs), not on the Proxmox box.
Communicates with the client over stdio, and with Proxmox over HTTPS using an API token (no passwords, easy to revoke).
Tolerates the self-signed certificate a default Proxmox install ships with.
Capabilities
~29 tools across three always-on tiers, plus an optional fourth:
Tier A — read / status (14, strictly read-only)
list_nodes · node_status · cluster_resources · list_vms ·
list_containers · vm_status · container_status · vm_config ·
container_config · list_storage · list_templates · next_vmid ·
get_task_status · list_tasks
Tier B — lifecycle (8, reversible power state)
start_vm · stop_vm · shutdown_vm · reboot_vm ·
start_container · stop_container · shutdown_container · reboot_container
Tier C — provision (7, additive: create / clone / configure)
create_container · create_vm · clone_vm · clone_container ·
set_vm_config · set_container_config · allocate_vmid
Tier D′ — in-guest exec (2, opt-in, off by default)
exec_in_container · exec_in_vm — run commands inside a guest (e.g.
apt-get update, install/start an app). Disabled unless you explicitly turn it
on; see Optional: in-guest command execution.
Never present: delete / destroy
There is no tool to delete, destroy, remove, purge, roll back, shrink, wipe, or erase anything. That is intentional — see below.
The no-delete guarantee
Deletion is human-only by design. This matters because Proxmox RBAC cannot
separate "create" from "delete": the VM.Allocate privilege required to create
a guest also permits destroying one at the API level. There is no role you can
grant that means "create but not delete."
So the guarantee is enforced inside this server, in two independent layers:
No destructive tools exist.
build_server()runsassert_no_destructive_tools()at startup and refuses to start if a tool name matching a destructive verb is ever registered.A runtime guard wraps the client. The proxmoxer API object is wrapped in a
SafeProxmoxproxy that raisesPermissionErrorthe instant any.deleteis touched, anywhere in a call chain.
To cut off access entirely, revoke the API token in Proxmox.
Quick start
1. Set up Proxmox (one-time)
Create a dedicated user, a least-privilege role, an ACL assignment, and an API
token. The fastest path is the pveum CLI on your Proxmox host:
# 1. a dedicated user
pveum user add agent@pve
# 2. a least-privilege role (read + power + provision; NO admin)
pveum role add AgentRole -privs "VM.Audit Sys.Audit Datastore.Audit VM.PowerMgmt VM.Allocate VM.Config.Disk VM.Config.CPU VM.Config.Memory VM.Config.Network VM.Config.Options VM.Clone Datastore.AllocateSpace SDN.Use"
# 3. grant the role (use a pool path instead of / to limit blast radius)
pveum acl modify / -user agent@pve -role AgentRole
# 4. create the API token — prints the secret ONCE; copy it
pveum user token add agent@pve mcp --privsep 0Note on
SDN.Use: it is required on Proxmox VE 8.x/9.x to attach a guest to any bridge, including the defaultvmbr0(the API checks/sdn/zones/localnetwork/<bridge>). Without it, create/clone fails with403 Forbidden: Permission check failed (... SDN.Use).
Prefer the web UI? Datacenter → Permissions → Users (add agent@pve) →
Roles (create AgentRole with the privileges above) → Add → User
Permission (path /, user agent@pve, role AgentRole) → API Tokens
(add token mcp, uncheck Privilege Separation, copy the secret).
2. Install
pip install -e .This installs the package and a proxmox-mcp console script. You can also launch
it with python -m proxmox_mcp. Requires Python 3.11+.
3. Configure
All settings come from environment variables. There are two ways to supply them:
Deployment: set them in your MCP client's
envblock (see step 4).Local dev / testing: copy
.env.exampleto.envand fill in real values..envis git-ignored — never commit real credentials. Anything set in the actual process environment (e.g. the client'senvblock) overrides.env.
Variable | Required | Default | Notes |
| ✅ | — | Hostname/IP, e.g. |
| ✅ | — | e.g. |
| ✅ | — | e.g. |
| ✅ | — | the token secret copied during setup |
|
|
| |
|
| Proxmox API port |
(In-guest exec adds more variables — see that section.)
4. Register with your MCP client
.mcp.json (Claude Code project config, Cursor, etc.):
{
"mcpServers": {
"proxmox": {
"command": "proxmox-mcp",
"env": {
"PROXMOX_HOST": "proxmox.lan",
"PROXMOX_USER": "agent@pve",
"PROXMOX_TOKEN_NAME": "mcp",
"PROXMOX_TOKEN_VALUE": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"PROXMOX_VERIFY_SSL": "false"
}
}
}
}(No console script? Use "command": "python", "args": ["-m", "proxmox_mcp"].)
claude mcp add (Claude Code CLI):
claude mcp add proxmox \
--env PROXMOX_HOST=proxmox.lan \
--env PROXMOX_USER=agent@pve \
--env PROXMOX_TOKEN_NAME=mcp \
--env PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--env PROXMOX_VERIFY_SSL=false \
-- proxmox-mcpRestart the client, then ask it "list my Proxmox nodes" to confirm.
Optional: in-guest command execution
To let an agent run commands inside a guest (the second half of "deploy an
application" — e.g. apt-get update, install and start a service), enable the
Tier D′ exec tools. They are off by default.
Exec works by SSHing to the Proxmox host and running pct exec (LXC) or
qm guest exec (VM, requires the QEMU guest agent). Every argument is
shlex-quoted so it cannot break out into the host shell, and there is no raw
host-shell tool — only guest-scoped execution.
⚠️ Security: this is a real privilege grant. An agent with exec enabled can run arbitrary commands as root inside any guest, reachable via the SSH credential you configure. Only enable it if you trust the agent with that, and prefer a dedicated SSH key with access limited to what you need.
Set these additional variables:
Variable | Required for exec | Default | Notes |
| ✅ ( |
| Master switch; registers the exec tools |
|
| Host to SSH into (defaults to the PVE host) | |
|
| SSH port | |
|
| SSH user (must be able to run | |
| — | Path to a private key (preferred) | |
| — | Used only if no key file is given |
Example env additions:
"PROXMOX_ENABLE_EXEC": "true",
"PROXMOX_SSH_USER": "root",
"PROXMOX_SSH_KEY_FILE": "/home/you/.ssh/proxmox_agent"With exec enabled the server exposes 31 tools (29 baseline + 2 exec).
Usage examples
Once registered, you talk to your agent in plain language; it picks the tools.
You say… | Tools the agent uses |
"What's running on my Proxmox?" |
|
"How much RAM is free on node pve?" |
|
"Reboot the docker VM (id 102)." |
|
"Create a Debian 12 container, 2 cores, 2 GB, on vmbr0." |
|
"Clone template 9000 into a new VM and start it." |
|
"Install nginx in container 250." (exec enabled) |
|
"Delete that test VM." | ❌ refused — deletion is human-only |
Testing
The test suite is fully offline — proxmoxer and paramiko are mocked, so no env vars and no network are needed:
python -m pytest -qA live smoke test against a real Proxmox is not part of the offline suite; it just needs the env vars set so the server can connect.
Security model
Auth: API token only (no passwords); scope it with a least-privilege role and, ideally, a pool-scoped ACL. Revoke instantly with
pveum user token remove agent@pve mcp.No deletes: enforced in-server (no destructive tools + runtime guard), because Proxmox RBAC cannot express "create but not delete."
Secrets: live in env vars or a git-ignored
.env; never in source or argv.Exec is opt-in and, when on, scoped to guest commands via
pct/qmwith shell-safe quoting — no arbitrary host shell.
Roadmap
✅ Tier A/B/C (read, lifecycle, provision) — no-delete guaranteed
✅ Task status visibility (
get_task_status,list_tasks)✅ Optional synchronous waits on create/clone provisioning tools
✅ Tier D′ in-guest exec (opt-in)
⏳ cloud-init provisioning helpers for VMs
⏳ file push/pull into guests for app deployment
Built with proxmoxer and the official MCP Python SDK.
Available Tools
29 toolsallocate_vmidA
Get the next free cluster-wide VM/container id to use before a create.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Get the next free' implies a non-destructive read operation, but it lacks details on whether the ID is reserved, possible error states, or authentication requirements.
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?
A single sentence that fronts the purpose and usage context with no wasted words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no params and no output schema, the description adequately explains what it does and when to use it. However, it could improve by clarifying the return value format (e.g., an integer ID).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema coverage is 100% trivially. The description adds value by explaining 'cluster-wide' and 'free', clarifying the scope beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('next free cluster-wide VM/container id'), clearly stating the tool's purpose and distinguishing it from siblings like 'next_vmid' which may lack the 'free' and 'cluster-wide' qualifiers.
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?
The description explicitly says 'to use before a create', providing a clear usage context. While it doesn't mention when not to use or alternatives, it is sufficient for a simple allocation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
clone_containerC
Clone an LXC container; returns a UPID, or final task status when wait=True.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | ||
| node | Yes | ||
| wait | No | ||
| extra | Yes | ||
| newid | Yes | ||
| target | No | ||
| storage | No | ||
| hostname | No | ||
| source_vmid | Yes | ||
| wait_timeout | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool returns a UPID or final task status when wait=True, but fails to explain other behavioral traits like whether the source container must be stopped, whether linked clones are supported (despite 'full' parameter), or any side effects. No annotations to compensate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise but too minimal. It is front-loaded with the core action and return info, but every sentence does not earn its place due to missing critical details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no schema descriptions, no annotations, and a complex cloning operation, the description is severely incomplete. It omits parameter meanings, behavioral details, and prerequisites, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It only mentions 'wait' behavior. The required 'extra' parameter is unexplained, and optional parameters like 'full' and 'target' are not described.
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?
Description clearly states 'Clone an LXC container', providing a specific verb and resource. It distinguishes from sibling 'clone_vm' by specifying container type. However, it lacks details on the nature of cloning (full vs linked).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'create_container' or 'clone_vm'. No prerequisites or context for invocation provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
clone_vmC
Clone a QEMU VM; returns a UPID, or final task status when wait=True.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | ||
| name | No | ||
| node | Yes | ||
| wait | No | ||
| extra | Yes | ||
| newid | Yes | ||
| target | No | ||
| storage | No | ||
| source_vmid | Yes | ||
| wait_timeout | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must cover behavioral traits. It mentions that waiting returns final status, but omits critical details like whether cloning locks the source VM, requires specific permissions, or has side effects (e.g., storage usage). The return behavior is partially disclosed, but the overall transparency is low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action and return type. It is very concise, but the conciseness sacrifices necessary detail. Still, it is well-structured and easy to read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, no schema descriptions, no annotations) and the presence of an output schema, the description fails to provide a complete picture. It does not explain the output schema beyond UPID/status, nor does it cover important aspects like clone type (full/linked), target node/storage, or parameter dependencies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It only indirectly hints at the 'wait' parameter through the return behavior. No other parameter (full, name, newid, target, storage, node, source_vmid, wait_timeout, extra) is explained. This provides almost no semantic value.
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?
The description clearly states the action ('Clone a QEMU VM') and the return type (UPID or final task status with wait=True). However, it does not distinguish from sibling tools like clone_container or other VM operations, which would help select the correct tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks any guidance on when to use this tool versus alternatives (e.g., clone_container, create_vm). It does not mention prerequisites, typical use cases, or constraints. The only operational hint is the wait parameter behavior, which is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cluster_resourcesC
List cluster resources of a given type (e.g. vm, storage, node).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| resource_type | No | vm |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only states that it lists resources of a given type, but does not disclose output format, pagination, performance, or side effects. This is minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the core action. No unnecessary words are present, and it gets straight to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not mention what the output contains. With many sibling listing tools, the description lacks context on how this tool differs or when to prefer it. It is barely adequate for a simple tool, missing crucial contextual information.
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?
The schema has 0% description coverage for the single parameter 'resource_type'. The description adds examples (vm, storage, node), providing some context beyond the parameter name, but does not specify allowed values or constraints. For a simple string parameter, this is adequate but not strong.
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?
The description clearly states the verb 'List' and the resource 'cluster resources', specifying a parameter 'resource_type' with examples. However, it does not differentiate from sibling tools like list_vms or list_nodes, which are type-specific listers. The purpose is clear but lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 the type-specific sibling tools (e.g., list_vms, list_nodes). An agent cannot decide whether to call this generic tool or the specialized ones based on the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
container_configC
Get the configuration of an LXC container.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description needs to disclose behavioral traits. It only says 'get configuration' without mentioning that this is a read-only operation, what permissions are needed, or whether any side effects exist. The description is insufficient for an agent to understand the tool's safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It front-loads the core purpose. However, it could include a bit more useful information without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 0% schema coverage, the description does not provide enough context. It does not explain what the configuration output looks like, how to interpret results, or any prerequisites. This is incomplete for a tool with two required parameters and many related siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for its two parameters (node, vmid). The description does not add any meaning beyond the parameter names, such as how to find valid values or what they represent. This leaves an agent without essential context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the configuration of an LXC container, using the specific verb 'get' and resource 'configuration of an LXC container'. This distinguishes it from sibling tools like 'set_container_config' (write) and 'container_status' (status).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'vm_config' for VMs or 'set_container_config' for modifying config. No prerequisites or contextual cues are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
container_statusC
Get the current runtime status of an LXC container.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
TDQS
C2.2/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description offers no behavioral traits beyond 'get'. Does not confirm idempotency, permissions, rate limits, or any side effects. For a read operation, this is a significant omission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but too brief for a meaningful tool description. It sacrifices informational value for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without output schema, annotations, or parameter explanations, the description fails to equip an agent with sufficient information to understand return values, errors, or usage constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description does not explain the semantics of node or vmid parameters, nor does it provide any additional context beyond schema types.
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?
Description clearly states the verb 'Get' and resource 'runtime status of an LXC container', distinguishing from VM-related tools like vm_status and from container config tools. However, does not specify that it returns a single status object, leaving slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as container_config or list_containers. No context about prerequisites or scenarios where status is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_containerB
Create an LXC container; returns a UPID, or final task status when wait=True.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| net0 | No | name=eth0,bridge=vmbr0,ip=dhcp | |
| node | Yes | ||
| vmid | Yes | ||
| wait | No | ||
| cores | No | ||
| extra | Yes | ||
| memory | No | ||
| rootfs | No | ||
| storage | Yes | ||
| hostname | No | ||
| ostemplate | Yes | ||
| wait_timeout | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides minimal behavioral context: it returns a UPID or task status when 'wait=True'. However, it does not disclose side effects (e.g., resource consumption), required permissions, or potential failure modes.
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?
A single, well-structured sentence that conveys the core action and return behavior efficiently. No extraneous words, and the key conditional ('wait=True') is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite output schema existing (but not shown), the description is inadequate for a tool with 12 parameters and no schema descriptions. It omits prerequisites, parameter relationships, and operational details, leaving an incomplete picture for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for its 12 parameters. The description adds no explanation beyond parameter names, leaving critical fields like 'extra', 'rootfs', and 'hostname' unclarified, which is insufficient given the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'LXC container'. It also distinguishes the return behavior (UPID vs final status) based on the 'wait' parameter, which helps differentiate from sibling tools like clone_container or create_vm.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'clone_container' or 'create_vm'. There is no mention of prerequisites (e.g., template existence, node state) or conditions where waiting is beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_vmC
Create a QEMU VM; returns a UPID, or final task status when wait=True.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| net0 | No | virtio,bridge=vmbr0 | |
| node | Yes | ||
| vmid | Yes | ||
| wait | No | ||
| cores | No | ||
| extra | Yes | ||
| scsi0 | No | ||
| memory | No | ||
| ostype | No | l26 | |
| wait_timeout | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions the return type but fails to describe side effects (e.g., resource consumption, required permissions, or potential failures). The creation process is essentially opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and is front-loaded with the action. However, it is too brief given the tool's complexity, leaving many important details unsaid.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, no annotations, and an existing output schema, the description is severely incomplete. It does not cover parameter meanings, default behaviors, error conditions, or prerequisites, making it insufficient for reliable agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 11 parameters (3 required), the description adds no meaning to any parameter except a brief mention of 'wait=True'. It does not explain what 'node', 'vmid', 'extra', 'cores', etc. represent or how they affect the VM creation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create a QEMU VM' and distinguishes from siblings like clone_vm and create_container. It also mentions the return type (UPID or task status), which adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the wait parameter but does not provide explicit guidance on when to use this tool versus other VM-related tools like clone, start, or stop. No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_task_statusC
Get a Proxmox task status by UPID and classify its final result.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| upid | Yes |
TDQS
C2.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It implies a read-only operation ('Get') but does not explicitly state whether it modifies state, requires authentication, or has rate limits. The classification phrase hints at interpretation but lacks detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the key action. However, it is too brief and could incorporate more helpful information without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description lacks details on return format, error handling, or what 'classify' entails. It is insufficient for an AI to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only mentions 'by UPID' without explaining what a UPID is, its format, or how to obtain it. The parameter definition alone provides no context.
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?
The description clearly states the verb 'Get' and resource 'a Proxmox task status by UPID', and adds 'classify its final result' which distinguishes it from sibling tools like list_tasks that list tasks instead of retrieving status of a specific one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., list_tasks) or prerequisites (e.g., obtaining a UPID from another tool).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_containersC
List LXC containers on a node.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.8/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like auth needs, side effects, or output specifics. It only states 'list' without any additional context, leaving the agent uninformed about potential behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. However, it is overly brief and could benefit from additional structure or bullet points for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 and sibling tools, the description lacks contextual completeness. It doesn't explain what distinguishes listing containers from listing VMs or how the node parameter is used, making it insufficient for effective tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no semantic detail beyond the parameter name 'node'. It doesn't clarify the format, allowed values, or meaning of the parameter, relying solely on the property title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List LXC containers on a node', which clearly identifies the verb (List), resource (LXC containers), and scope (on a node). It effectively differentiates from sibling tools like list_vms and list_nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as listing VMs or storage. The description implies usage for containers on a node but lacks context on prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_nodesA
List all nodes in the Proxmox cluster.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states 'list all nodes' which implies a read operation, but lacks details on permissions, output format, or side effects. Output schema likely provides return structure, reducing need for in-description details.
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?
Single sentence of 7 words, efficient and front-loaded. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and existence of output schema, the description covers essentials. Could hint at ordering or filtering, but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in input schema, so baseline is 4. The description adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'list' and resource 'nodes in the Proxmox cluster', clearly distinguishing from sibling tools that focus on VMs, containers, or storage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. However, the context of listing all nodes is straightforward, and sibling tools target different resources, so the usage is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_storageC
List storage available on a node.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It implies a read operation but does not state safety, required permissions, or potential errors, leaving the agent underinformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it lacks necessary detail. While front-loaded, it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no annotations), the description should clarify what 'storage' encompasses and what the output contains. It fails to provide a complete picture even though an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'node' with 0% description coverage, and the tool description adds no extra meaning. The format or constraints of the node value are not explained.
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?
The description 'List storage available on a node' clearly states the action (list) and resource (storage) with a scope (on a node). It distinguishes from sibling tools which focus on other resources like containers, VMs, or nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives, nor any prerequisites or context. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_tasksC
List recent Proxmox tasks for a node.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| limit | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description says 'list recent tasks' but does not disclose ordering, pagination behavior, or whether it is read-only. Lacks detail on what 'recent' means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single concise sentence. However, it may be too minimal for a tool with no annotations and low schema coverage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters, no annotations, but with an output schema, the description lacks sufficient context for an agent to know when to use it versus the similar get_task_status. Missing behavioral details like ordering and pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description adds no meaning to 'node' or 'limit' parameters. Does not explain default behavior or how 'limit' affects results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List recent Proxmox tasks for a node.' Verb 'list' and resource 'tasks' are clear, and the scope 'recent' and 'for a node' distinguishes it from sister tools like get_task_status (specific task) and other listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_task_status or other listing tools. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_templatesB
List content (ISOs, container templates, backups) in a storage on a node.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| storage | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full burden. It only states it lists content, but does not disclose behavioral traits like read-only nature, required permissions, or side effects. This is minimal 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core functionality without any unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and does not explain the output format (though output schema exists), prerequisites, or scope of storage types. More context would be beneficial given the number of sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for both parameters (node, storage). The description does not add any meaning beyond the parameter names, failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'content (ISOs, container templates, backups)', and the scoping 'in a storage on a node'. This distinguishes it from sibling tools like list_containers or list_vms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need ISOs, templates, or backups) but does not provide explicit guidance on when not to use it or mention alternative tools. No exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_vmsB
List QEMU virtual machines on a node.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits but only mentions the basic action. It does not indicate whether the operation is read-only, requires authentication, or handles errors (e.g., invalid node).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence with no wasted words. However, it could be structured to include key usage details without increasing length significantly.
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 simple list tool with one parameter and an output schema present, the description is minimally adequate. It covers the basic purpose but lacks details like whether it includes stopped VMs or performance considerations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not add meaning to the 'node' parameter beyond the phrase 'on a node', which is already generic. No extra semantics or constraints are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List QEMU virtual machines on a node', specifying the verb 'list', the resource 'QEMU VMs', and the scope 'on a node', which distinguishes it from sibling tools like list_containers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor does it specify prerequisites or exclusions. It only states the action without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
next_vmidA
Get the next free cluster-wide VM/container id.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It implies a read-only operation by stating 'Get', but does not detail idempotency, side effects, or error conditions. Adequate but minimal.
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?
Single sentence, no wasted words, front-loaded with verb and resource. Perfectly concise.
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 simple tool with no parameters and no output schema, the description is adequate but misses details like return format or error behavior. Could be enhanced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and the schema coverage is 100%. Per guidelines, 0 parameters gets baseline 4. Description adds nothing beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'next free cluster-wide VM/container id', specifying scope and what is returned. It distinguishes from siblings like allocate_vmid which allocates a specific id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like allocate_vmid, nor any prerequisites or context. The description is purely functional.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
node_statusC
Get status and resource usage for a single node.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes |
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It indicates a read operation but does not mention required permissions, rate limits, or what 'resource usage' includes. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks detail. It could be more informative while remaining brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, no annotations, and many sibling tools, the description is incomplete. It does not specify return format, what resource usage metrics are included, or any constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'node' has no schema description, and the description does not clarify its meaning (e.g., node ID or name). No additional semantics provided beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get status and resource usage for a single node,' specifying a verb ('Get') and a resource ('status and resource usage'). It effectively distinguishes this tool from siblings like 'list_nodes' that list all nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'container_status' or 'vm_status'. The description lacks context for selection among many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reboot_containerC
Reboot an LXC container; returns the task UPID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only mentions returning a UPID, but does not disclose if the operation is destructive, requires specific permissions, or affects container state beyond reboot (e.g., downtime).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) but lacks essential details. It is not front-loaded with the most critical information for selection; a brief description is acceptable only if comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is an output schema (not shown), the description fails to provide behavioral context for a 2-parameter tool with no annotations. Usage guidelines and transparency gaps make it incomplete for reliable agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description adds no parameter details beyond the names 'node' and 'vmid'. Despite being somewhat obvious, the description should clarify expected values (e.g., node hostname, container ID) to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action (Reboot), the resource (LXC container), and the return value (task UPID). It effectively distinguishes from sibling 'reboot_vm' by targeting containers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like shutdown_container/start_container or reboot_vm. There are no prerequisites, caveats, or context for optimal usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reboot_vmC
Reboot a QEMU VM; returns the task UPID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions returning a UPID but omits whether the reboot is graceful (ACPI) or forceful, whether it can be called repeatedly, and what happens to running processes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely short, but under-specified. It is concise but fails to provide necessary detail, making it insufficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a VM reboot, the description is severely incomplete. It lacks information about asynchronous operation, status checking, and prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description adds no explanation for the 'node' and 'vmid' parameters. The user must infer their meaning from titles alone.
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?
The description explicitly states the action ('Reboot a QEMU VM') and the return value ('returns the task UPID'). It clearly distinguishes from sibling tools like reboot_container and shutdown_vm.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention scenarios where reboot is inappropriate (e.g., if VM is already running or needs a hard reset).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_container_configB
Update the configuration of an LXC container (PUT); requires at least one field.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes | ||
| config | Yes |
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states it's a PUT operation but lacks any disclosure of side effects (e.g., whether container restarts, error handling, required permissions, or idempotency). This is insufficient for a mutation tool.
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?
The description is extremely concise—one sentence, no fluff. Every word serves a purpose, clearly stating the verb, resource, method, and a constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (updating LXC container configs), the absence of output schema, parameter details, and behavioral context makes it incomplete. The agent cannot infer return values, error states, or required preconditions accurately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no descriptions on properties). The description only adds that the tool 'requires at least one field', which is ambiguous. It does not explain what the 'config' object contains or what values are valid, which is critical for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update the configuration of an LXC container') and the HTTP method ('PUT'), distinguishing it from sibling tools like 'container_config' (GET) and 'set_vm_config' (for VMs). The phrase 'requires at least one field' further clarifies the minimum input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (you update configuration via PUT) but does not explicitly state when to use this tool over alternatives, nor does it mention prerequisites or when-not-to-use. No guidance on reading current config first or container state requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_vm_configB
Update the configuration of a QEMU VM (PUT); requires at least one field.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes | ||
| config | Yes |
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It indicates mutation ('Update', 'PUT') but does not disclose required permissions, whether unspecified fields are preserved or reset, rate limits, or error conditions. Behavior is minimally transparent.
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?
The description is a single sentence that front-loads the action ('Update the configuration of a QEMU VM (PUT)') and adds a key constraint. No wasted words; every part is valuable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, and minimal parameter documentation, the description does not fully equip an agent to use the tool. The config parameter's structure is unspecified; the agent would need external knowledge or rely on sibling tools like vm_config to understand possible fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; the description adds only 'requires at least one field', which clarifies that the config object must contain at least one property. However, it does not explain the individual parameters (node, vmid, config) or their expected formats/types, leaving the agent to infer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Update the configuration of a QEMU VM (PUT)', which clearly identifies the action (update) and resource (VM configuration). It distinguishes from sibling tools like vm_config (GET) and set_container_config (container-focused).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes 'requires at least one field', implying the config parameter must have content, but provides no explicit guidance on when to use this tool versus alternatives (e.g., when to update vs recreate). Usage context is implied but not detailed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shutdown_containerC
Gracefully shut down an LXC container via ACPI; returns the task UPID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description partially compensates: 'gracefully' and 'via ACPI' indicate a clean shutdown. Mentions returning a task UPID, suggesting async operation. However, does not disclose safety, waiting behavior, or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff. However, it is arguably too terse given the lack of parameter explanations. Still, it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks essential context: no preconditions, error conditions, or behavioral details. For a tool with only two parameters, it should provide more guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the tool description provides no explanation of parameters. 'node' and 'vmid' are common but their meaning is not elaborated, leaving the agent without guidance.
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?
Clearly states the action (shut down), resource (LXC container), and method (via ACPI). Mentions return value (UPID). Distinguishes from sibling 'stop_container' by implying graceful shutdown, though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs alternatives like 'stop_container' or 'reboot_container'. Does not specify prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shutdown_vmC
Gracefully shut down a QEMU VM via ACPI; returns the task UPID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover all behavioral aspects. Mentions ACPI and returns UPID, but lacks details on graceful behavior (timeout, guest response), permissions, side effects, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but could be restructured with more key information; no wasted words but missing critical details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of annotation or output schema detail, the description is insufficient; does not explain return format, error handling, or differentiation from similar sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description adds no meaning beyond field names; does not explain what node and vmid are or any constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Describes specific action 'shut down' on resource 'QEMU VM' with method 'via ACPI', clearly distinguishing from sibling tools like stop_vm (forceful) and shutdown_container (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Only hints at graceful shutdown but provides no explicit guidance on when to use this vs alternatives, no prerequisites or restrictions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
start_containerB
Start an LXC container; returns the task UPID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It states the core behavior (starts container) and output (UPID), but omits details like idempotency, error states, or required permissions. It is average—covers the main action but not side effects or preconditions.
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?
The description is a single sentence with no wasted words. It front-loads the action and result. This is appropriately concise for a simple tool.
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?
Given the tool's simplicity (start action, two params, output schema exists), the description is adequate but not thorough. It lacks context on whether the action is synchronous, what happens if the container is already running, or how to interpret the UPID. With richer annotations or parameter descriptions, this could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no explanation for 'node' or 'vmid'. The agent gets no context on what these parameters represent (e.g., node name, container ID), relying solely on the schema titles. This is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Start an LXC container') and the return value ('returns the task UPID'). It clearly distinguishes from sibling tools like stop_container, reboot_container, etc., by using a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., start_vm for VMs), no prerequisites mentioned, and no scenarios where the tool should not be used. The description is purely declarative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
start_vmC
Start a QEMU VM; returns the task UPID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It only states it starts a VM and returns a UPID. No disclosure of side effects, prerequisites (e.g., VM must be stopped), or behavior if VM is already running.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks critical information. It is not structured for readability and omits important details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of starting a VM, the description omits essential context like error handling, async nature (returns task ID), and existence checks. Output schema may supplement, but description alone is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description adds no parameter details. The two parameters ('node', 'vmid') are not explained beyond schema types, which is insufficient for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Start') and resource ('QEMU VM'), and mentions the return value ('task UPID'). It distinguishes from sibling tools like 'start_container' and 'shutdown_vm' by specifying the VM type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like 'start_container' or 'reboot_vm'. No prerequisites or context are provided, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
stop_containerA
Hard-stop an LXC container (immediate power off); returns the task UPID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the destructive nature ('hard-stop', 'immediate power off') and the return value. It does not mention idempotency or side effects but is sufficiently clear for a simple action.
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?
The description is a single sentence with no filler, directly stating the action and return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (stop container) and the presence of an output schema (mentioned in context), the description is complete enough. It conveys the core behavior without unnecessary details.
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%, and the description does not add any meaning beyond the parameter names (node, vmid). However, the parameters are self-explanatory from their names and types, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (hard-stop), the resource (LXC container), and distinguishes from siblings like shutdown_container by specifying 'immediate power off'. It also mentions the return value (task UPID).
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?
The description implies usage for hard stop via 'immediate power off', distinguishing from graceful shutdown (shutdown_container). However, it does not explicitly state when to use this vs alternatives, nor provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
stop_vmB
Hard-stop a QEMU VM (immediate power off); returns the task UPID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description mentions hard-stop but lacks disclosure of data loss risk, auth needs, or side effects beyond returning a task UPID.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded, but could be slightly expanded for completeness without adding bulk.
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?
Given only 2 required parameters and a straightforward action, the description covers the core purpose but lacks parameter descriptions and usage context to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no information about the parameters (node, vmid), leaving the agent without meaning beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (hard-stop, immediate power off) and resource (QEMU VM), differentiating from sibling tools like shutdown_vm that perform graceful shutdown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies immediate power off but does not explicitly state when to use versus alternatives like shutdown_vm or reboot_vm, leaving the agent without clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
vm_configC
Get the configuration of a QEMU VM.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
TDQS
C2.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only implies read-only via 'Get' but doesn't disclose any behavioral traits like required permissions, side effects, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no waste, but could include minimal context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks details about output, prerequisites, or error conditions. For a simple get-config tool, more context is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds no meaning to 'node' or 'vmid' beyond the schema type and requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'configuration of a QEMU VM', distinguishing it from siblings like set_vm_config or vm_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like vm_status or container_config. Lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
vm_statusC
Get the current runtime status of a QEMU VM.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description does not disclose what 'runtime status' entails (e.g., possible states like running/stopped/paused). Behavior is vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at one sentence with no fluff, though it could provide more detail without losing brevity. Score reflects efficiency but slight under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description is incomplete. It fails to specify what information the status includes, leaving the agent uncertain about the tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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, but it does not explain the parameters (node, vmid) beyond their names. The agent gains no additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('runtime status of a QEMU VM'), clearly distinguishing from sibling tools like vm_config or container_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as vm_config or container_status. The agent receives no context for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
29 tool updates
v0.1.0- First observed
allocate_vmid - First observed
clone_container - First observed
clone_vm - First observed
cluster_resources - First observed
container_config - First observed
container_status - First observed
create_container - First observed
create_vm - First observed
get_task_status - First observed
list_containers - First observed
list_nodes - First observed
list_storage - First observed
list_tasks - First observed
list_templates - First observed
list_vms - First observed
next_vmid - First observed
node_status - First observed
reboot_container - First observed
reboot_vm - First observed
set_container_config - First observed
set_vm_config - First observed
shutdown_container - First observed
shutdown_vm - First observed
start_container - First observed
start_vm - First observed
stop_container - First observed
stop_vm - First observed
vm_config - First observed
vm_status
TDQS
B3.2/5.0
Scored across 29 tools
Disambiguation5/5
Each tool targets a distinct resource (container, VM, node, cluster, storage) and action (create, clone, list, get, set, start, stop, reboot, shutdown). Descriptions clearly differentiate between container and VM operations, and there is no overlap.
Naming Consistency4/5
Most tools follow a verb_noun pattern (e.g., list_containers, create_vm), but there are minor inconsistencies: 'container_config' and 'vm_config' lack the 'get_' prefix, 'next_vmid' is not verb_noun, and 'allocate_vmid' and 'next_vmid' overlap in purpose.
Tool Count5/5
29 tools cover the core aspects of Proxmox cluster management (VMs, containers, nodes, storage, tasks, IDs) without being excessive. The scope is appropriate for a comprehensive MCP server.
Completeness3/5
The set covers creation, cloning, status, configuration, and lifecycle actions, but lacks delete operations for containers and VMs. Missing features like migration, snapshots, and network management, but core workflows are present.
Maintenance
ActivityStale
ResponsivenessResponsive
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
MCP server for Google Veo AI video generation
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server for Proxmox Virtual Environment that enables AI assistants to manage virtual machines, containers, nodes, and resources through natural language interactions.3MIT
- FlicenseNot gradedqualityCmaintenanceMCP server for Proxmox VE that enables AI assistants to inspect and manage LXC containers, VMs, snapshots, and resource pools via the Proxmox API.-
- AlicenseNot gradedqualityCmaintenanceAn MCP server for interacting with the Proxmox Virtual Environment API, enabling management of VMs, containers, storage, and cluster resources through natural language.MIT