gemini-media-mcp

Overview Schema Source Related Servers Discussions Admin

Edit image

edit_image

Modify an existing image with a text prompt: add, remove, or replace elements, restyle, relight, change aspect ratio, or fix text while keeping other parts unchanged. Saves a new file, original kept.

Instructions

Change an existing image with an instruction (add/remove/replace elements, restyle, relight, change aspect ratio, fix text) while keeping everything else. Accepts extra reference images to insert or match. Say what must stay unchanged. Saves a new file; the original is kept.

Input Schema

Name	Required	Description
`image`	Yes	The image to edit: file path, gemini-media:// URI from an earlier result, or data: URI.
`model`	No	Model ID or alias. Defaults to the model that created the source image, else nb2.
`prompt`	Yes	The change to make, stated specifically, plus what must stay the same (e.g. 'Replace the sky with a sunset; keep the people, framing and lighting on faces unchanged').
`imageSize`	No	Output size: 1K, 2K or 4K (512 only on the deprecated gemini-3.1-flash-image).
`outputName`	No	Optional base file name for the saved file. Defaults to the source name plus -edit.
`aspectRatio`	No	Change the aspect ratio (outpainting). Omit to keep the source ratio.
`approvedCostUsd`	No	Only needed above the confirmation threshold: the cost in USD the user approved.
`referenceImages`	No	Optional extra images to pull elements or style from (e.g. 'put the logo from image 2 on the mug').

Output Schema

Name	Required	Description
`cost`	Yes
`text`	No	Commentary the model returned alongside the image(s)
`files`	Yes
`model`	Yes
`warnings`	No
`grounding`	No	Google Search queries the model ran and the pages it used (googleSearch only)

Schema Changelog

Changes observed during successful MCP inspections.

Changed18 schema fields changedv1.1.0Oct 14, 2026

addedInput schema / properties / approvedCostUsd

Added value: +{
+  "description": "Only needed above the confirmation threshold: the cost in USD the user approved.",
+  "type": "number"
+}

addedInput schema / properties / aspectRatio

Added value: +{
+  "description": "Change the aspect ratio (outpainting). Omit to keep the source ratio.",
+  "type": "string"
+}

addedInput schema / properties / image

Added value: +{
+  "description": "The image to edit: file path, gemini-media:// URI from an earlier result, or data: URI.",
+  "type": "string"
+}

removedInput schema / properties / imagePath

Removed value: -{
-  "description": "Path to the image to edit",
-  "type": "string"
-}

addedInput schema / properties / imageSize

Added value: +{
+  "description": "Output size: 1K, 2K or 4K (512 only on the deprecated gemini-3.1-flash-image).",
+  "type": "string"
+}

changedInput schema / properties / model / description

Previous value: -"Model tier: nb2 (default) or pro"New value: +"Model ID or alias. Defaults to the model that created the source image, else nb2."

addedInput schema / properties / outputName

Added value: +{
+  "description": "Optional base file name for the saved file. Defaults to the source name plus -edit.",
+  "type": "string"
+}

changedInput schema / properties / prompt / description

Previous value: -"Text description of the edit to apply"New value: +"The change to make, stated specifically, plus what must stay the same (e.g. 'Replace the sky with a sunset; keep the people, framing and lighting on faces unchanged')."

addedInput schema / properties / referenceImages

Added value: +{
+  "description": "Optional extra images to pull elements or style from (e.g. 'put the logo from image 2 on the mug').",
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

changedInput schema / required

Previous value: -[
-  "prompt",
-  "imagePath"
-]New value: +[
+  "image",
+  "prompt"
+]

addedOutput schema / properties / cost

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "basis": {
+      "description": "How usd was derived: usage_metadata, unit_params, token_estimate or unpriced",
+      "type": "string"
+    },
+    "breakdown": {
+      "type": "string"
+    },
+    "estimatedUsd": {
+      "description": "Estimate computed before the call from the price table",
+      "type": "number"
+    },
+    "pending": {
+      "description": "True while a video job is still running (cost is reserved, not final)",
+      "type": "boolean"
+    },
+    "priceAsOf": {
+      "type": "string"
+    },
+    "usd": {
+      "description": "Best-known cost in USD; reconciled from token usage when the API reports it",
+      "type": "number"
+    }
+  },
+  "required": [
+    "estimatedUsd",
+    "usd",
+    "basis"
+  ],
+  "type": "object"
+}

removedOutput schema / properties / filePath
```
Removed value: -{
-  "type": "string"
-}
```

addedOutput schema / properties / files

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "bytes": {
+        "type": "integer"
+      },
+      "durationSeconds": {
+        "type": "number"
+      },
+      "height": {
+        "type": "integer"
+      },
+      "mimeType": {
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "path": {
+        "description": "Absolute path of the saved file on the server's filesystem",
+        "type": "string"
+      },
+      "uri": {
+        "description": "MCP resource URI; pass it back as an input to other tools or read it with resources/read",
+        "type": "string"
+      },
+      "width": {
+        "type": "integer"
+      }
+    },
+    "required": [
+      "path",
+      "uri",
+      "name",
+      "mimeType",
+      "bytes"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / grounding

Added value: +{
+  "additionalProperties": false,
+  "description": "Google Search queries the model ran and the pages it used (googleSearch only)",
+  "properties": {
+    "queries": {
+      "items": {
+        "type": "string"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "sources": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "title": {
+            "type": "string"
+          },
+          "uri": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "uri"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    }
+  },
+  "type": [
+    "null",
+    "object"
+  ]
+}

removedOutput schema / properties / mimeType
```
Removed value: -{
-  "type": "string"
-}
```

addedOutput schema / properties / text

Added value: +{
+  "description": "Commentary the model returned alongside the image(s)",
+  "type": "string"
+}

addedOutput schema / properties / warnings

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "filePath",
-  "model",
-  "mimeType"
-]New value: +[
+  "files",
+  "model",
+  "cost"
+]

First observedApr 15, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false; the description corroborates and enriches this by stating "Saves a new file; the original is kept", which is exactly the consequence an agent needs for a non-destructive mutation. It adds nothing about cost approvals, model selection, or rate limits, so it is not fully rich.

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?

Four short sentences, front-loaded with the core purpose and scoping constraint. "Say what must stay unchanged" slightly overlaps the prompt field's own example in the schema, a minor redundancy, but every sentence otherwise carries weight.

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?

With an output schema present, return values need no explanation, and the schema documents all 8 parameters at full coverage. The description completes the picture on mutation semantics, preservation of the original, and reference-image behavior; it omits any note on the cost-confirmation threshold, which the schema covers indirectly.

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 baseline is 3; the description still adds meaning beyond the field docs by explaining what referenceImages are for ("pull elements or style from" / "insert or match") and by prescribing the prompt structure (change + what must stay the same).

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 ("Change an existing image") and enumerates the concrete edit classes it supports (add/remove/replace, restyle, relight, aspect ratio, text fixes). The phrase "existing image" cleanly separates it from the sibling generate_image, which creates rather than modifies.

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?

Gives clear context for use (modify an existing image while keeping everything else) and practical guidance ("Say what must stay unchanged", extra reference images for insert/match). It does not explicitly name when not to use it or point to an alternative sibling, so it falls short of the 5 bar.

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

Deploy Server