gimp-mcp

Overview Schema Source Related Servers Discussions Admin

Configure layer mask

gimp_set_layer_mask

Configure a GIMP layer mask's rendering and editing behavior by toggling apply, show, and edit flags so you can preview the unmasked layer or paint directly on the mask.

Instructions

apply: whether the mask affects the rendering (disable to see the layer unmasked); show: display the mask itself; edit: make painting tools target the mask.

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": {
      "item": "<item>"
    },
    "name": "gimp_set_layer_mask"
  }
}

Input Schema

Name	Required	Description
`edit`	No
`item`	Yes	Item id (layer, group, mask...) e.g. 'item:5@a1b2c3d4'.
`show`	No
`apply`	No

Output Schema

Name	Required	Description
`x`	Yes	Offset of the layer's top-left corner in image pixels.
`y`	Yes
`id`	Yes
`kind`	Yes
`mask`	Yes
`mode`	Yes	GIMP layer mode nick, e.g. 'normal', 'multiply'.
`name`	Yes	Layer name. GIMP keeps names unique within an image ('Title #1').
`locks`	Yes
`width`	Yes
`height`	Yes
`parent`	Yes	Id of the parent group, null at the top level.
`opacity`	Yes	0-100.
`visible`	Yes
`children`	No	Child layers of a group, top-most first; null for non-groups.
`has_alpha`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.6.0Nov 10, 2026

changedOutput schema / $defs / LayerNode / properties / kind / enum

Previous value: -[
-  "layer",
-  "group",
-  "text"
-]New value: +[
+  "layer",
+  "group",
+  "text",
+  "vector",
+  "link"
+]

changedOutput schema / properties / kind / enum

Previous value: -[
-  "layer",
-  "group",
-  "text"
-]New value: +[
+  "layer",
+  "group",
+  "text",
+  "vector",
+  "link"
+]

First observedv0.1.0Nov 7, 2026

TDQS

C2.4/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 openWorldHint=false, so the safety profile is covered. The description does add real behavior beyond that: the flags govern rendering, visibility and painting target of an existing mask rather than its pixel content, which tells the agent these are non-destructive configuration toggles. It says nothing about failure modes when the item has no mask, or about what 'null' does to the current state.

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 text is short and wastes no words, but it is a sentence fragment with no leading purpose statement, so nothing is front-loaded for an agent scanning for the tool's function. Brevity here shades into under-specification rather than efficiency.

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

Completeness2/5

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

For a mutation tool with four parameters, 25% schema coverage and no sibling differentiation, the description is incomplete: null semantics, the mask-existence prerequisite, and the relationship to add/remove mask tools are all absent. The presence of an output schema excuses it from explaining return values, but not from the missing invocation context.

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 25%, with only 'item' documented in the schema, so the description carries the burden for 'apply', 'show' and 'edit' and it does define each in concrete terms. The critical gap is the nullable default: it never explains whether passing null leaves the setting unchanged or resets it, which matters for every one of the three booleans.

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

Purpose2/5

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

The description never states what the tool does as a whole; it is a semicolon-separated glossary of three flags with no verb and no object. Only the name and title ('Configure layer mask') convey the action, and nothing distinguishes it from gimp_add_layer_mask or gimp_remove_layer_mask.

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

Usage Guidelines2/5

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

There is no when-to-use guidance, no statement that the item must already carry a mask, and no routing to sibling tools such as gimp_add_layer_mask for creating one. The flag explanations imply what happens when values are changed, but an agent receives no exclusions or preconditions.

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

Deploy Server