Skip to main content
Glama
claude-proxmox-controller

claude-proxmox-controller

host_command

Run root shell commands on a Proxmox host over SSH to handle tasks the API cannot, such as checking services, logs, files, or installed programs, and return output and exit codes.

Instructions

Run a shell command on the Proxmox host itself, as root, over the SSH key the user set up in Proxmox Controller, and get its output and exit code — for what the API cannot do (installed programs, services, logs, files). One command line a request: the user sees it as it is in the approval window, every time. It runs on the host at the address the app connects to.

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>",
      "command": "<command>",
      "reason": "<reason>"
    },
    "name": "host_command"
  }
}

Input Schema

NameRequiredDescriptionDefault
hostYesThe host's id, from list_hosts.
reasonYesWhy you are doing this, in a sentence. The user sees it in the approval window and in the log.
commandYesA shell command line, run by the user's shell on the host (pipes and ; work).
timeout_sNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/5

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

The description discloses a lot beyond the annotations: root privileges, the SSH key set up in Proxmox Controller, an approval window where the user sees the command verbatim, one command per request, and that output plus exit code are returned. However, the annotations declare openWorldHint=false while arbitrary shell lines (pipes and ';' explicitly allowed) can reach anything, a tension the description never resolves; it also says nothing about what happens on timeout or when the command fails.

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?

It is front-loaded with the core action and scope in the first clause, and the trailing sentences about approval visibility and execution address both carry real information. It is slightly long and the approval-window point is repeated for both the description and the reason parameter, but nothing is filler.

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 4-parameter, no-output-schema tool it covers the essentials: auth path, privilege level, execution location, approval gate, and the shape of the result (output and exit code). The main gaps are failure/timeout behavior and a hint that hosts should come from list_hosts, which only the schema supplies.

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 75%, so the baseline is a 3. The description does add meaning for 'host' ('runs on the host at the address the app connects to') and reinforces that the command is shown verbatim in the approval window, but timeout_s has no description anywhere and goes unmentioned in the prose.

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 a specific verb and resource ('Run a shell command on the Proxmox host itself, as root'), and the 'host itself' framing plus 'for what the API cannot do' implicitly separates it from guest-level siblings like run_command. It never names the sibling explicitly, so an agent comparing host_command against run_command still has to infer the split from the word 'host'.

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?

It gives a clear when-to-use rule: things the API cannot do, concretely illustrated as installed programs, services, logs and files. There is no explicit when-not-to-use or named alternative, so an agent is not told to prefer the API-backed sibling when one exists.

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