Skip to main content
Glama
claude-proxmox-controller

claude-proxmox-controller

list_guest_files

List files and folders inside a running Proxmox VM or container, including name, type, size, and modified time, to inspect guest storage before file operations.

Instructions

The files and folders in a folder of a running VM (through its QEMU guest agent) or container (over the host's SSH): name, folder or not, size, modified. Without folder: /home on Linux, C:\Users on Windows, /root in a container; on Windows an empty folder lists the drives.

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>",
      "vmid": "<vmid>",
      "reason": "<reason>"
    },
    "name": "list_guest_files"
  }
}

Input Schema

NameRequiredDescriptionDefault
hostYesThe host's id, from list_hosts.
vmidYesThe guest's ID (VMID).
folderNo
reasonYesWhy you are doing this, in a sentence. The user sees it in the approval window and in the log.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

Beyond the annotations, it discloses the transport mechanism per guest type and the default path resolution (/home on Linux, C:\Users on Windows, /root in containers) plus the Windows edge case where an empty folder lists drives. The readOnlyHint=false with destructiveHint=false looks inconsistent for a listing call, but the required 'reason' parameter explaining the approval window accounts for the approval-gated framing rather than indicating mutation.

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?

Very compact: one clause sets the resource and return fields, a second covers defaults and the Windows edge case. Front-loaded and free of filler, though the fragment style ('name, folder or not, size, modified') reads telegraphically rather than as clean prose.

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?

With no output schema, the description compensates by listing the returned fields, and it covers defaults, transports, and a platform quirk, which is enough to call the tool correctly. Minor gaps remain: no mention of non-recursive listing behavior, error conditions (agent unreachable, path not found), or whether double quotes/escapes are needed in paths.

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?

Schema coverage is 75% and the undocumented parameter is 'folder', which the description explains semantically: it selects the directory to enumerate and, when absent, the platform-specific default is used. It does not clarify path format conventions (separators, trailing slashes, drive letters), so it stops short of full coverage.

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 definition names a specific resource and scope: files and folders inside one folder of a running VM (via QEMU guest agent) or container (via host SSH), and enumerates the returned fields (name, folder flag, size, modified). It is distinguishable from send_files/receive_files, though it is written as a noun phrase with no explicit verb.

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?

It usefully states applicability (running VMs via guest agent, containers via host SSH) and what happens when 'folder' is omitted, which is conditional usage guidance. However, it gives no guidance on when to prefer guest_details, console_* tools, or send_files/receive_files, and no prerequisites such as the guest agent needing to be installed and running.

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