Skip to main content
Glama

List VMs with live details

proxmox_list_vms
Read-only

Lists QEMU VMs across all online Proxmox nodes with disk I/O counters, host memory, PSI pressure stalls, and QEMU version details; filter by node, status, or search text.

Instructions

List QEMU VMs straight from the nodes (GET /nodes/{node}/qemu?full=1), with details proxmox_list_guests lacks: disk I/O counters, host memory, PSI pressure stalls and the running QEMU version/machine. Without node, queries every online node. For a quick cluster-wide list with filters by tag/pool use proxmox_list_guests instead.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "proxmox_list_vms"
  }
}

Input Schema

NameRequiredDescriptionDefault
rawNoReturn the full unprocessed objects from the API (larger)
nodeNoOnly this node (default: all online nodes)
limitNoMaximum number of results (default 500)
fieldsNo
searchNoCase-insensitive substring filter on names, IDs, tags and similar fields
statusNoOnly VMs in this state

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.1

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: the underlying GET endpoint, that results are gathered per-node and fan out across all online nodes by default, and that the payload carries live host metrics. It does not explain pagination or how `limit`/`search` interact with the per-node fan-out, leaving a modest gap.

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?

Front-loaded with the verb, resource and the distinguishing payload details, then the default-scope caveat, then the sibling redirect. The parenthetical endpoint path is slightly noisy but earns its place by telling an agent exactly what is being fetched.

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?

There is no output schema, so the description correctly compensates by enumerating the distinguishing return fields (disk I/O, host memory, PSI stalls, QEMU version). Combined with the node-default behavior, that is enough for correct invocation; only pagination/error behavior is unaddressed.

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 coverage is 83%, so the schema already documents node, raw, limit, search and status. The description restates the `node` default (all online nodes) which the schema also states, and adds no syntax or format detail for `fields`, `search` or `status`. Baseline 3 is appropriate given the schema does the heavy lifting.

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?

States a specific verb and resource ("List QEMU VMs straight from the nodes") plus the exact API endpoint, and explicitly contrasts itself with proxmox_list_guests by naming the extra fields (disk I/O counters, host memory, PSI pressure, QEMU version/machine). An agent can distinguish this from the sibling without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Gives both the default scoping behavior ("Without `node`, queries every online node") and an explicit routing rule to the alternative ("For a quick cluster-wide list with filters by tag/pool use proxmox_list_guests instead"). When-to-use and when-to-prefer-a-sibling are both stated.

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

Deploy Server

Other Tools