Skip to main content
Glama

Workspace checkpoint

snapshot
Destructive

Checkpoint workspace files git does not track before multi-file refactors, then list or restore checkpoints to roll back changes. Preview restores before writing.

Instructions

Checkpoint and roll back workspace files. action: create (label, paths) | list | restore (id) | delete (id) | mirror (copy to VENIRA_SNAPSHOT_MIRROR_DIR). Use when: before multi-file refactors or overwriting/deleting files git does not hold. Keep paths narrow and check file_count and skipped. Roll back with restore dry_run=true, then restore with verify=true. Avoid when: tiny single-file edits or states git already holds. Output: create: id, file_count, total_bytes, truncated, skipped[]. restore: restored[], deleted_count, skipped[].

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "snapshot"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoCheckpoint id (required for restore/delete; returned by create/list).
labelNoHuman label for the checkpoint, e.g. "before refactor auth".
limitNolist only: max checkpoints to return (default 20).
pathsNoWorkspace-relative paths to capture (default ['.'] = whole workspace; scope narrowly). For restore: subset to restore.
actionNocreate (default) captures paths; list; restore rolls back an id; delete removes an id; mirror copies the store to VENIRA_SNAPSHOT_MIRROR_DIR.create
reasonNoOptional why (max 400 chars), audit-logged.
verifyNorestore: true (default) verifies each blob before writing. mirror: true re-hashes blobs already at the mirror and re-copies bad ones (default false).
dry_runNorestore only: true previews path/size changes without writing.
excludeNoExtra directory/file names to skip.
max_filesNoMax files captured (default 20000, max 20000).
delete_extraNorestore only: true also deletes files in captured dirs that are not in the checkpoint (max 500). Default false; use only when intended.
max_total_bytesNoMax total bytes captured (default and max 512 MiB).
respect_default_excludesNotrue (default) skips standard generated/cache directories; false disables those exclusions.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed20 schema fields changedv4.5.0
    • removedInput schema / properties / delete_extra / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "maximum": 1,
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -]
    • changedInput schema / properties / delete_extra / description
      Previous value: -"restore only: 1 also deletes files in captured dirs that are not in the checkpoint (max 500). Default 0; use only when intended."New value: +"restore only: true also deletes files in captured dirs that are not in the checkpoint (max 500). Default false; use only when intended."
    • removedInput schema / properties / delete_extra / maximum
      Removed value: -1
    • removedInput schema / properties / delete_extra / minimum
      Removed value: -0
    • changedInput schema / properties / delete_extra / type
      Previous value: -"integer"New value: +"boolean"
    • removedInput schema / properties / dry_run / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "maximum": 1,
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -]
    • changedInput schema / properties / dry_run / description
      Previous value: -"restore only: 1 previews path/size changes without writing."New value: +"restore only: true previews path/size changes without writing."
    • removedInput schema / properties / dry_run / maximum
      Removed value: -1
    • removedInput schema / properties / dry_run / minimum
      Removed value: -0
    • changedInput schema / properties / dry_run / type
      Previous value: -"integer"New value: +"boolean"
    • removedInput schema / properties / respect_default_excludes / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "maximum": 1,
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -]
    • changedInput schema / properties / respect_default_excludes / description
      Previous value: -"1 skips standard generated/cache directories (default); 0 disables those exclusions."New value: +"true (default) skips standard generated/cache directories; false disables those exclusions."
    • removedInput schema / properties / respect_default_excludes / maximum
      Removed value: -1
    • removedInput schema / properties / respect_default_excludes / minimum
      Removed value: -0
    • changedInput schema / properties / respect_default_excludes / type
      Previous value: -"integer"New value: +"boolean"
    • removedInput schema / properties / verify / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "maximum": 1,
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -]
    • changedInput schema / properties / verify / description
      Previous value: -"restore: 1 verifies each blob before writing (default). mirror: 1 re-hashes blobs already at the mirror and re-copies bad ones (default 0)."New value: +"restore: true (default) verifies each blob before writing. mirror: true re-hashes blobs already at the mirror and re-copies bad ones (default false)."
    • removedInput schema / properties / verify / maximum
      Removed value: -1
    • removedInput schema / properties / verify / minimum
      Removed value: -0
    • changedInput schema / properties / verify / type
      Previous value: -"integer"New value: +"boolean"
  2. Addedv4.0.0

TDQS

A4.6/5.0
Behavior4/5

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

The annotations already declare destructive=true and non-readonly behavior, and the description adds useful operational context: mirror copies to VENIRA_SNAPSHOT_MIRROR_DIR, rollback should be previewed first, and users should inspect file_count and skipped. It could be more explicit about how restore may overwrite current workspace files, but it substantially enriches the annotation-level safety picture.

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?

The description is compact and front-loaded, starting with the tool's core purpose before listing actions, usage conditions, safety workflow, and output shape. Every section is relevant and there is no redundant filler.

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 complex, destructive, multi-action tool with 13 parameters and no output schema, the description supplies strong usage guidance, rollback safety steps, and key output fields for create and restore. It does not describe outputs for list, delete, or mirror, but the rich schema and annotations cover most remaining invocation details.

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 the schema already documents all parameters well. The description adds meaningful action-to-parameter mapping, especially create (label, paths), restore (id), delete (id), and mirror behavior, plus the dry_run-before-verify sequencing that is not fully captured by individual parameter descriptions.

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 description states specific verbs and resources: checkpoint, roll back, list, delete, and mirror workspace files/checkpoints. It enumerates all supported actions and clearly differentiates the tool from git-based workflows by focusing on states git does not hold.

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?

It gives explicit when-to-use guidance such as before multi-file refactors or overwriting/deleting files not held by git, and explicit avoid conditions for tiny single-file edits or states already in git. It also prescribes a safe rollback workflow: dry_run=true first, then verify=true.

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