Skip to main content
Glama
claude-proxmox-controller

claude-proxmox-controller

list_guests

Read-onlyIdempotent

Lists all VMs and containers on a Proxmox host, including state, CPU, memory, disk, IP addresses, tags, boot settings, and notes for quick inventory and status checks.

Instructions

Every VM and container of a host: state, CPU, memory, disk, IP addresses, tags, start at boot and boot order, notes.

Tool call template

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

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

Input Schema

NameRequiredDescriptionDefault
hostYesThe host's id, from list_hosts.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

B3.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description's added value is the return-payload inventory (state, CPU, memory, disk, IPs, tags, boot config, notes), which matters because there is no output schema, but it says nothing about pagination, ordering, or behavior when a host has no guests.

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?

One dense, front-loaded line with no filler; the field enumeration earns its space given the absence of an output schema. It is a verbless fragment, however, which makes it slightly telegraphic rather than a clean, self-contained statement of action.

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 one-parameter, read-only listing tool with full schema coverage and strong annotations, the description supplies the missing piece an agent needs — what comes back. Only minor gaps remain: no note on result volume or whether the listing is flat or grouped.

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?

There is a single parameter with 100% schema description coverage, and the schema already explains it is 'The host's id, from list_hosts.' The description adds no format, sourcing, or validation detail beyond that, so this lands at the baseline for a fully documented schema.

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 names the resource precisely ('Every VM and container of a host') and enumerates the fields returned, so an agent knows this is a host-scoped inventory listing. It does not explicitly contrast with guest_details or other per-guest tools, so the sibling boundary must be inferred from the name alone.

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?

There is no when-to-use guidance, no prerequisites, and no mention of when a different tool (e.g., guest_details for a single guest) would be preferred. The only usage signal is the required `host` parameter, which implies host-scoped enumeration but is left to inference.

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