Skip to main content
Glama
claude-proxmox-controller

claude-proxmox-controller

create_backup_job

Destructive

Create a scheduled backup job so Proxmox runs guest backups automatically on a calendar schedule, with storage, retention (keep) and per-guest or all-guest targets.

Instructions

Schedule backups: a backup job that Proxmox runs by itself at its time. schedule as Proxmox writes it — 03:00 (every day), mon..fri 21:30, sat,sun 02:00, sun 04:00, or any Proxmox calendar event (*/6:00). Guests: vmids, or all (with exclude). storage: one that takes backups. keep (how many backups to keep: last, daily, weekly, monthly) makes Proxmox delete the older backups of these guests on that storage after each run: it needs the Destroy switch; without keep, the storage's own rule applies. The job gets an ID beginning with claude-.

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>",
      "schedule": "<schedule>",
      "storage": "<storage>",
      "reason": "<reason>"
    },
    "name": "create_backup_job"
  }
}

Input Schema

NameRequiredDescriptionDefault
allNoEvery guest of the host (but those in exclude).
hostYesThe host's id, from list_hosts.
keepNoHow many backups to keep (Destroy switch).
modeNo
notesNoEach backup's note: {{guestname}} and {{vmid}} are filled in.
vmidsNoThe guests it backs up.
reasonYesWhy you are doing this, in a sentence. The user sees it in the approval window and in the log.
commentNo
enabledNo
excludeNo
storageYes
compressNo
scheduleYesWhen: 03:00 · mon..fri 21:30 · sat,sun 02:00 · sun 04:00 · a Proxmox calendar event.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds real substance beyond them: it explains that keep causes Proxmox to delete older backups of these guests on that storage, that without keep the storage's own rule applies, and that the job ID begins with 'claude-'. It doesn't disclose what happens if a duplicate job or invalid schedule is supplied, keeping it out of 5 territory.

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?

It is a single tight block with the core purpose front-loaded, followed by the parameters that carry real risk or ambiguity (schedule, guests, storage, keep). Every sentence adds information; nothing is redundant.

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 13-parameter destructive creation tool with no output schema, the description covers the high-stakes semantics (retention deletion, guest selection, schedule format) well. It leaves the optional tuning parameters (mode, compress, enabled, comment) entirely to the schema, which is a modest but real 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?

With schema coverage at 54%, the description meaningfully compensates: it explains the schedule grammar with concrete examples (03:00, mon..fri 21:30, */6:00 calendar events), the all/exclude interaction, the retention semantics of keep, and the storage constraint. Several parameters (mode, compress, enabled, comment) carry no explanation beyond the schema, which caps the score.

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 first clause gives a concrete verb and resource — 'Schedule backups: a backup job that Proxmox runs by itself at its time' — which distinguishes it from immediate-backup siblings like backup_now. It stops short of naming the sibling alternatives explicitly, so it lands just below the top mark.

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 provides useful conditional rules — guests are either 'vmids, or all (with exclude)', storage 'one that takes backups', and keep 'needs the Destroy switch' — which guide correct configuration. However, it never states when to prefer this over edit_backup_job or backup_now, nor any exclusion conditions, so usage is implied rather than spelled out.

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