codex-image-mcp

Overview Schema Source Related Servers Discussions Admin

edit_image

Modify only a selected image region using a box or PNG mask while keeping all pixels outside it identical; use it for targeted retouching or local redraws without changing the rest.

Instructions

Edit only one region of an image; every pixel outside it stays identical to the original.

Pass exactly one region:

box: [x0, y0, x1, y1] in the image's pixels (x1, y1 exclusive).
mask_path: a PNG the same size as the image; white (or opaque white) pixels may change. Codex redraws the picture from the original and the mask (~30-60 s, plan usage limits); the result is aligned back onto the original and only the region's pixels are taken. background: flat colour a transparent original is shown on; inside the region that colour is keyed back to transparency (tolerance = RGB distance). The result reports alignment (scale, origin, error) and a warning when the match is poor; the full generated image stays at raw_path.

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_path": "<image_path>",
      "prompt": "<prompt>",
      "output_path": "<output_path>"
    },
    "name": "edit_image"
  }
}

Input Schema

Name	Required	Default
`box`	No
`prompt`	Yes
`mask_path`	No
`overwrite`	No
`tolerance`	No
`background`	No	#FF00FF
`image_path`	Yes
`output_path`	Yes
`timeout_seconds`	No
`reasoning_effort`	No	low

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 5, 2026

TDQS

A3.6/5.0

Behavior4/5

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

With no annotations at all, the description carries the full burden and does well: it discloses the ~30-60 s runtime, that it consumes plan usage limits, that the result is realigned onto the original with only region pixels taken, and that the response reports alignment (scale, origin, error) plus a poor-match warning with the raw generated image at raw_path. Gaps remain on overwrite semantics, timeout behavior, and failure modes.

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?

The core invariant is front-loaded and the mutually exclusive region inputs are bulleted for scannability. The later sentences are dense run-ons that mix the pipeline explanation with the background/tolerance parameter notes, so some content is harder to parse than it needs to be, but there is little pure filler.

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

Completeness3/5

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

For a 10-parameter, no-annotation, no-output-schema tool, it covers the central workflow, cost/time expectations, and return-value shape reasonably well. It is not complete enough on the operational flags (overwrite, timeout, reasoning_effort) or on error/retry behavior for an agent to call it confidently without inspecting the schema.

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 0% across 10 parameters, so the description must compensate and it only partly does. It clarifies box coordinate semantics (pixels, x1/y1 exclusive), mask pixel encoding (white/opaque white may change), background purpose, and tolerance meaning (RGB distance); it says nothing about overwrite, image_path, output_path, timeout_seconds, or reasoning_effort.

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

Purpose4/5

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

The description opens with a specific verb+resource and a defining invariant: 'Edit only one region of an image; every pixel outside it stays identical to the original.' That scope statement implicitly separates it from the generate_image / generate_images siblings, but no sibling is named explicitly, so differentiation is left to inference.

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

Usage Guidelines3/5

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

It gives a hard usage rule — 'Pass exactly one region' with box XOR mask_path — which is genuinely useful selection guidance between two mutually exclusive inputs. However, it never states when to choose edit_image over generate_image, nor any prerequisites or exclusions beyond that one constraint.

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

Deploy Server