Skip to main content
Glama
claude-proxmox-controller

claude-proxmox-controller

receive_files

Copy files and folders from a running Proxmox VM or container to a folder on your computer, leaving existing files untouched unless replacement is enabled.

Instructions

Copy files and folders (names) from a folder of a running VM or container into a folder of the user's computer (a whole path that exists). What is there already is not replaced unless replace is true.

Tool call template

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "host": "<host>",
      "vmid": "<vmid>",
      "folder": "<folder>",
      "names": "<names>",
      "to": "<to>",
      "reason": "<reason>"
    },
    "name": "receive_files"
  }
}

Input Schema

NameRequiredDescriptionDefault
toYesThe folder of the user's computer they go into.
hostYesThe host's id, from list_hosts.
vmidYesThe guest's ID (VMID).
namesYes
folderYesThe guest's folder they are in.
reasonYesWhy you are doing this, in a sentence. The user sees it in the approval window and in the log.
replaceNo

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 (readOnly=false, destructive=false, idempotent=false), the description discloses the key write behavior: existing files are not replaced unless replace is true, which tells the agent the default is a non-destructive copy. It does not cover partial-failure behavior or what happens when a name already exists and replace is false, so it is not fully 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?

Two tight sentences with the transfer direction front-loaded and the overwrite caveat appended. Parenthetical glosses on 'names' and 'a whole path that exists' add precision without waste.

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 7-parameter, 6-required copy operation with no output schema, the description covers direction, overwrite semantics, and destination constraints. It says nothing about what the tool returns or how errors/partial copies are reported, which an agent needs before invoking a multi-file transfer on a live guest.

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 71%, and the description compensates for the two undocumented parameters: it clarifies that 'names' are items relative to the guest folder and that 'replace' governs overwriting. The 'to' parameter is reinforced as a whole existing path. Only host/vmid/reason remain undescribed, but those carry schema text, including the reason's approval-window purpose.

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 gives a specific verb and resource ('Copy files and folders (names)') plus an explicit direction of transfer (from a guest VM/container folder into a folder of the user's computer), which distinguishes it from the reverse-direction sibling send_files. It stops short of naming that sibling explicitly, so the differentiation relies on the reader inferring the opposite tool.

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 implies when the tool applies by specifying a 'running VM or container' and a destination 'that exists', which are implicit preconditions. It never states when not to use it, nor does it point to send_files for the opposite direction, so an agent must infer the alternative.

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