gimp-mcp

Overview Schema Source Related Servers Discussions Admin

Restore checkpoint (undo/redo)

gimp_restore_checkpoint

Destructive

Restore an image to a saved checkpoint, replacing current state with new IDs and empty undo history. Use to revert destructive edits when a checkpoint exists.

Instructions

Replace the image with the state saved in a checkpoint. The restored image gets a NEW image id and new item ids (the old ones become invalid); GIMP windows showing it are reconnected; its file association is kept and it is marked as having unsaved changes; its GIMP undo history starts empty. Checkpoints are kept, so restoring a later one redoes. Destructive for the current state unless it was checkpointed.

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": {
      "image": "<image>",
      "checkpoint": "<checkpoint>"
    },
    "name": "gimp_restore_checkpoint"
  }
}

Input Schema

Name	Required	Description	Default
`image`	Yes	Image id from gimp_status, e.g. 'image:1@a1b2c3d4'.
`checkpoint`	Yes	Checkpoint id from gimp_create_checkpoint.

Output Schema

Name	Required	Description
`id`	Yes
`file`	Yes
`name`	Yes	GIMP's display name (may be localized).
`dirty`	Yes
`image`	Yes	Id of the restored image (a new id: all item ids changed).
`width`	Yes
`height`	Yes
`xcf_file`	Yes
`displayed`	Yes	True when a GIMP window shows the image (GUI sessions only).
`layer_count`	Yes	Number of top-level layers.
`previous_image`	Yes	Id the image had before; it is no longer valid.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 7, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true, but the description goes well beyond them: the restored image gets a NEW id and old item ids become invalid, windows are reconnected, file association is retained, the image is marked unsaved, and undo history starts empty. Those id-invalidation and history-reset details are exactly the side effects an agent cannot infer from the annotations.

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

Conciseness4/5

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

Front-loaded with the core action, then a compact clause list of consequences, ending with the destructiveness caveat. Dense but every clause carries distinct information; slightly list-like phrasing keeps it from a 5.

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?

An output schema exists, so return values needn't be described, and the description covers the mutation mechanics, id invalidation, unsaved-state flag, and redo semantics. Nothing an agent needs in order to call this safely is missing.

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 description coverage is 100%, with both parameters documented as ids sourced from gimp_status and gimp_create_checkpoint. The description adds no further syntax or format detail, so the baseline 3 applies.

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: 'Replace the image with the state saved in a checkpoint.' That distinguishes it cleanly from gimp_create_checkpoint, gimp_delete_checkpoint, and gimp_list_checkpoints without opening any 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?

'Checkpoints are kept, so restoring a later one redoes' gives the redo use case, and 'Destructive for the current state unless it was checkpointed' warns when not to call it. There's no explicit named alternative such as undo grouping or gimp_create_checkpoint for safety, which keeps it below a 5.

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

Deploy Server