imagen-mcp

Edit image

edit_image

Edit, restyle, or combine up to 16 reference images using a text prompt. Regenerates the entire picture, with optional mask to preserve areas, and saves results to disk.

Instructions

Edit, restyle, or combine 1-16 reference images with a text prompt using OpenAI GPT Image 2.5. The whole picture is regenerated; without a mask the prompt decides what changes. Saves files to disk and returns paths and token usage.

Input Schema

TableJSON Schema

Name	Required	Description
`n`	No	Number of variations to generate; each costs output tokens. Files get -1, -2 suffixes. Default 1.
`mask`	No	Path of a PNG with alpha, same size as first image. Transparent pixels = region to repaint (guidance, not a hard lock). Default none.
`size`	No	auto \| 1024x1024 \| 1536x1024 \| 1024x1536 \| WIDTHxHEIGHT (multiples of 16, ratio 1:3..3:1, max edge 3840). Overrides aspect_ratio. Default auto.
`model`	No	flare = fast, general purpose. sunburst = slower, higher precision. Same price. Default flare.
`images`	Yes	Paths of 1-16 reference images (png/jpeg/webp). First = main subject; others = elements to combine. Relative to server cwd.
`prompt`	Yes	Image description, or the change to make when editing.
`quality`	No	Higher = more detail, more output tokens. auto lets the model choose (may be costly). Default auto.
`file_name`	No	Base name without extension. Default timestamp + prompt slug.
`long_edge`	No	Longer side in px, used with aspect_ratio. Default 1536.
`background`	No	transparent needs png or webp. Default auto.
`output_dir`	No	Save directory. Default IMAGEN_OUTPUT_DIR env or ./output (relative to server cwd).
`aspect_ratio`	No	Computes size together with long_edge. Default none.
`return_image`	No	Also return the image inline (base64, ~1.4 MB per 1024x1024 png) so it can be viewed. File is saved either way. Default false.
`output_format`	No	Also the file extension. Default png.
`input_fidelity`	No	high keeps faces, text, logos and unmasked areas faithful; costs more input tokens. Default low.
`output_compression`	No	jpeg/webp quality like JPEG: lower = smaller file, more artifacts. Default 100.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`size`	Yes
`files`	Yes
`model`	Yes
`usage`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 9, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Beyond the annotations, the description discloses important non-obvious behavior: the entire picture is regenerated, and without a mask the prompt determines what changes. It also states the side effects of saving files to disk and returning paths plus token usage, which helps the agent anticipate results beyond the schema.

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 three tightly written sentences with no filler. It front-loads the core purpose, then adds the key behavioral caveat about regeneration and masks, and closes with the output side effect. Every sentence earns its place.

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 tool with 16 parameters, the description gives enough high-level orientation to avoid misuse, while the rich schema and output schema carry the remaining parameter-level detail. It could be slightly stronger by explicitly naming the sibling alternative for pure generation, but it is still complete enough for effective invocation.

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?

The input schema already provides detailed descriptions for all 16 parameters with 100% coverage, so the description does not need to repeat parameter details. It does add a small amount of conceptual glue, such as the relationship between masks, prompts, and regeneration, but this is not substantial enough to raise the score above the high-coverage baseline.

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 a specific action set (edit, restyle, combine) against a concrete resource (1-16 reference images with a text prompt), and its wording inherently differentiates it from the sibling generate_image, which would not involve reference images. It also clarifies that the output is a regenerated image rather than a targeted patch.

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?

The description makes clear this tool is for reworking or combining existing reference images with a prompt, which gives an agent a solid context for when to choose it over generate_image. It does not explicitly name the alternative or provide a when-not-to-use rule, so it stops short of 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