Skip to main content
Glama
claude-proxmox-controller

claude-proxmox-controller

create_cloud_vm

Creates an Ubuntu VM from a cloud image on Proxmox with first-boot setup, optional desktop, remote desktop, and SSH key access—no manual OS installation.

Instructions

Create an Ubuntu VM from a cloud image (see get_cloud_image) — no installer: a user, its password (the USER types it in Proxmox Controller's window; you never give or see a password), optionally an SSH public key, network by DHCP. It sets itself up on the first start, from a setup disc the app makes and deletes afterwards: the updates and the QEMU guest agent (a server: 2-5 minutes). edition 'desktop' adds a SPICE display, sound and a USB tablet, and installs Ubuntu Desktop too (10-20 minutes); remote_desktop turns on Ubuntu's own Remote Desktop (GNOME Remote Desktop: RDP, port 3389, the Ubuntu desktop itself with its sound) with the same user and password; dark_theme makes the desktop dark.

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>",
      "name": "<name>",
      "image": "<image>",
      "reason": "<reason>"
    },
    "name": "create_cloud_vm"
  }
}

Input Schema

NameRequiredDescriptionDefault
hostYesThe host's id, from list_hosts.
nameYes
nodeNo
vmidNo
coresNo
imageYesThe image's volid.
startNoDefault: true.
bridgeNo
reasonYesWhy you are doing this, in a sentence. The user sees it in the approval window and in the log.
disk_gbNo
editionNo
storageNo
host_cpuNoThe host's own CPU type (else x86-64-v2-AES). Default: true for the desktop, false for a server.
usernameNoDefault: user.
static_ipNoA fixed address such as 192.168.1.50; the network's size, gateway and DNS are the host's own (on the VM's bridge). Default: DHCP.
dark_themeNoDesktop only.
memory_mibNo
start_at_bootNo
remote_desktopNoDesktop only.
ssh_public_keyNo
sudo_asks_passwordNoAs a normal Ubuntu, sudo asks for the user's password (at a console prompt: console_type_password). Default: true. false: sudo without a password, as the cloud image's own default.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior5/5

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

Annotations only cover the mutation/safety profile, but the description adds substantial behavior the agent could not otherwise know: a temporary setup disc is created and deleted, the VM self-configures on first boot (updates plus QEMU guest agent, 2-5 min; desktop 10-20 min), remote_desktop opens RDP on 3389, and the password never passes through the agent. The 'reason' parameter's visibility to the user is also explained, which supports the approval flow.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded, but the rest is a dense, semicolon-chained run-on mixing setup internals, timing estimates, and desktop options in one block. Much of the content earns its place for a complex tool, but structural separation (e.g., server vs desktop behavior) would make it far easier to parse.

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 21-parameter, no-output-schema creation tool this covers the essential mental model: where the image comes from, how credentials work, what happens on first boot, and how edition/remote_desktop/dark_theme change the outcome. Only the omitted resource-sizing and placement parameters (node, vmid, cores, memory, disk, storage, bridge) keep it from being fully complete.

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?

With 48% schema description coverage and 21 parameters, the description compensates for some of the gap by explaining edition, remote_desktop, dark_theme, the username/password model, SSH key, and DHCP-by-default networking. However, it says nothing about node, vmid, cores, memory_mib, disk_gb, storage, bridge, start, or start_at_boot, so many parameters remain undocumented anywhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create an Ubuntu VM from a cloud image') and immediately disambiguates the approach with 'no installer', which implicitly separates it from the installer-based create_vm sibling. It also names get_cloud_image as the prerequisite source of the image.

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?

Gives clear operational context: image must come from get_cloud_image, the user types the password in Proxmox Controller's window while the agent never supplies or sees one, and server vs desktop editions carry different setup times. It stops short of explicitly saying when to prefer this over create_vm/clone_vm, leaving that to inference from 'no installer'.

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