Skip to main content
Glama
claude-proxmox-controller

claude-proxmox-controller

guest_usage

Read-onlyIdempotent

Retrieve average and peak CPU, memory, network, and disk usage for a Proxmox guest over the last hour, day, week, or month to monitor resource consumption.

Instructions

A guest's average and peak CPU, memory, network and disk use over the last hour, day, week or month.

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>"
    },
    "name": "guest_usage"
  }
}

Input Schema

NameRequiredDescriptionDefault
hostYesThe host's id, from list_hosts.
vmidYesThe guest's ID (VMID).
timeframeNo

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that values are aggregated as both average and peak, which is genuine behavioral context, but it does not say what happens when historical data is unavailable or the guest was recently started.

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?

One sentence, front-loaded with the resource and the metrics, followed by the temporal scope. No filler, no restatement of the tool name.

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?

The tool is a simple read with four annotated hints, and the description covers what is measured and over what window. However, with no output schema, the agent is left guessing the response shape — whether metrics are returned as four paired average/peak fields or a nested series — which for a metrics tool is a meaningful gap.

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 67%; host and vmid are documented in-schema, and the timeframe enum's four values are self-describing. The description adds meaning beyond the bare enum by stating the window applies to the metrics and that both average and peak are computed over it, which clarifies how timeframe changes the result.

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?

States a specific resource (a guest's CPU, memory, network and disk use) and the aggregation (average and peak) over selectable windows, so the agent knows exactly what it returns. It does not differentiate from the nearest sibling, guest_details, which an agent could easily confuse with a metrics read.

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?

Usage is implied by the wording 'over the last hour, day, week or month' but there is no explicit when-to-use statement, no when-not, and no pointer to guest_details for static configuration versus this tool for time-series metrics. No prerequisites (guest must exist, host id from list_hosts) are mentioned in the description, though the schema covers list_hosts.

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