Skip to main content
Glama

version_create

Store a candidate state of editable files as a content-addressed snapshot or unified patch without changing the current base, so edits can be reviewed before proposal and launch.

Instructions

Store a candidate version of the editable files, either by snapshotting a complete scenario checkout or by applying a unified patch to a parent version. Use it after editing and before proposal_create and run_launch; use version_diff to review a stored change. Writes content-addressed snapshot files and appends a ledger event; it never adopts or changes the current base. Rejects edits outside the editable globs, unsafe paths and patches that do not apply. Returns {version, parent, changed}; identical content always gets the same version id.

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": {
      "config": "<config>"
    },
    "name": "version_create"
  }
}

Input Schema

NameRequiredDescriptionDefault
patchNoUnified Git-style patch text, as printed by `git diff`, applied to a temporary checkout of parent. Do not combine with directory.
configYesPath of the scenario YAML file on the server host, absolute or relative to the server's working directory, for example `scenario.yaml`. It selects the workspace; a server started with --config rejects any other path.
parentNoBase version of the change: 64-character lowercase SHA-256 version id, as returned by version_create. Default: current base.
directoryNoPath of a complete scenario checkout on the server host to snapshot. Defaults to the original scenario directory. Do not combine with patch.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.1.9
    • addedInput schema / properties / config / description
      Added value: +"Path of the scenario YAML file on the server host, absolute or relative to the server's working directory, for example `scenario.yaml`. It selects the workspace; a server started with --config rejects any other path."
    • addedInput schema / properties / directory / description
      Added value: +"Path of a complete scenario checkout on the server host to snapshot. Defaults to the original scenario directory. Do not combine with patch."
    • addedInput schema / properties / parent / description
      Added value: +"Base version of the change: 64-character lowercase SHA-256 version id, as returned by version_create. Default: current base."
    • addedInput schema / properties / patch / description
      Added value: +"Unified Git-style patch text, as printed by `git diff`, applied to a temporary checkout of parent. Do not combine with directory."
  2. First observedv0.1.7

TDQS

A4.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the write-without-destruction profile is known. The description goes further by disclosing that it writes content-addressed snapshot files, appends a ledger event, and never adopts or changes the current base, plus the rejection conditions (edits outside editable globs, unsafe paths, patches that do not apply) and the return keys {version, parent, changed}. That is solid added context, though the tension between 'identical content always gets the same version id' and idempotentHint=false is not reconciled for the caller.

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 sentences, each carrying distinct information: what it does, when to use it, side effects and constraints, and the return shape. The core action and mode choice are front-loaded with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description supplies the return keys, so return-value comprehension is covered. For a mutation tool with four parameters it also covers side effects, constraints, and sequencing, leaving no material gap for an agent to call it correctly.

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 100%, so all four parameters are already documented, which sets a baseline of 3. The description adds genuine semantics by framing patch and directory as mutually exclusive alternate modes and by explaining what rejection means for a patch that does not apply, clarifying how the parameters interact rather than restating them.

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?

The opening sentence gives a specific verb (store a candidate version) and names both supported modes (full checkout snapshot vs. unified patch against a parent). It is clearly distinguishable from siblings like version_diff and proposal_create, which are named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit sequencing is provided: use after editing and before proposal_create and run_launch. It also routes the agent to version_diff for reviewing a stored change, so the when-to-use and the alternative are both stated.

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