Skip to main content
Glama
Sign In
instabox-mcp

instabox-mcp

by syrex1013
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Save a snapshot of a machine

instabox_create_snapshot

Save a machine as a private snapshot to reuse as a base for launching new machines; by default, waits until the snapshot is ready.

Instructions

Save a machine as a private snapshot, then start new machines from it with instabox_create_machine snapshotId. A stopped machine is saved at once; a running one is saved live (if the server allows) and the snapshot is pending until uploaded; data programs had not yet written to disk is not included. By default this waits until the snapshot is ready. Counts against your snapshot and storage limits. Needs images:write.

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": {
      "id": "<id>",
      "name": "<name>"
    },
    "name": "instabox_create_snapshot"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesMachine ID (m_...) or its unique name
nameYesUnique snapshot name: lowercase letters, digits, '-'
waitNoWait for the operation to finish before returning (default true)
rootOnlyNoSave installed software only; machines from it start with an empty home
descriptionNo
waitTimeoutSecondsNoMax seconds to wait (default 300)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.4/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses that stopped machines save instantly while running machines save live only 'if the server allows', that the snapshot stays `pending` until uploaded, that unflushed program data is excluded, that it blocks by default, that it consumes snapshot/storage quota, and that `images:write` is required. Nothing here contradicts readOnlyHint=false, idempotentHint=false, or destructiveHint=false.

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?

Four dense sentences, each carrying distinct information: what it produces, how running vs stopped differ, the blocking default, and the quota/permission cost. The core action is front-loaded before the caveats.

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 6-parameter mutation with no output schema, the description covers preconditions, async behavior, cost, and data-loss caveats thoroughly. The one gap is that with no output schema present, the agent is not told what a successful call returns (snapshot object, ID, operation handle) or how to poll it when `wait` is false.

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 83%, so the schema already documents id, name, wait, and waitTimeoutSeconds. The description reinforces the default-wait behavior and the pending-until-uploaded consequence, but adds nothing about `rootOnly` (which has real semantic weight) or `description`. Baseline 3 is appropriate when the schema carries most of the burden.

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 ('Save a machine as a private snapshot') and immediately ties it to the downstream action via instabox_create_machine `snapshotId`, which distinguishes it from sibling snapshot tools like instabox_list_snapshots or instabox_delete_snapshot. An agent can identify both what it produces and what consumes it without opening the schema.

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?

Explicitly names the follow-up tool and parameter ('start new machines from it with instabox_create_machine `snapshotId`') and explains the branching behavior between stopped and running machines, which is the main decision point when calling it. It stops short of stating when NOT to snapshot (e.g., prefer a template) but the usage context is unambiguous.

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

Deploy Server

Other Tools