Skip to main content
Glama
chrischall

gemini-mcp

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

gemini-mcp

CI npm license

MCP server for Google Gemini media generation. Exposes thirteen tools to Claude over stdio: list available models, generate/edit/compose images, generate a consistent set of images from a master prompt, multi-turn image refinement (Interactions API), video generation (omni), music generation (Lyria), an async result poll for long generations, and Files API upload/list/delete for reusable image references. Output is written to disk by default (path returned) or returned inline as base64. Built on the Gemini v1beta API (generativelanguage.googleapis.com) using the Nano Banana / Nano Banana Pro (images), omni (video), and Lyria (music) model families.

Developed and maintained by AI (Claude Code).

Environment Variables

Variable

Required

Description

GEMINI_API_KEY

Yes

Your Google Gemini API key (aistudio.google.com/apikey)

GEMINI_IMAGE_MODEL

No

Override the default image model (default: gemini-nano-banana-2.1)

GEMINI_OUTPUT_DIR

No

Default directory for generated images (default: ~/Downloads/gemini-mcp). When set, a per-call output_dir must be inside it.

GEMINI_INPUT_DIR

No

Directory to resolve bare input-image filenames against (so images: ["foo.jpg"] works)

GEMINI_UPLOAD_DIR

No

Restrict local files streamed to the Gemini Files API (gemini_upload_file path, video_path) to these directories — one or more, separated by : (; on Windows); ~ allowed. A path outside is refused before any upload. Unset: no restriction

GEMINI_REFERENCE_DIR

No

Restrict local reference images (the images / master_images paths read and sent to Gemini — inline, or as a Files API upload once reused) to these directories — :-separated (; on Windows), ~ allowed; GEMINI_OUTPUT_DIR is always allowed too, so generated images can be fed back in. A path outside (symlinks followed) is refused before it is read. Unset: GEMINI_UPLOAD_DIR applies instead. If both are unset, reference images are unrestricted on a local install (any file the server can read can be sent), and confined to $MCP_DATA_DIR/uploads when MCP_DATA_DIR is set (hosted)

GEMINI_TIMEOUT_MS

No

Upstream request timeout in ms (default: 60000, or 120000 for image_size: "4K"); each generation tool also takes a per-call timeout_ms

GEMINI_HEARTBEAT_MS

No

Progress-notification cadence in ms while a generation runs (default: 10000; 0 disables) — keeps MCP hosts that reset their timeout on progress from timing out long generations

GEMINI_CHAIN_RETRY_MS

No

How long to wait out interactions-store lag when a chained call 404s (default: 120000; 0 disables retrying)

Confirmations

Sending a local file to Google (the images / master_images / video_path inputs, or gemini_upload_file's path) and every delete ask for confirmation first. A client that can show a confirmation prompt (Claude Code) gets the real prompt, unless MCP_CONFIRM_ELICITATION=off. Elsewhere the first call does nothing and returns a preview (the resolved local paths with their MIME types and sizes, or the method/path being deleted) plus a confirmToken; only a repeat call with the same arguments and that token proceeds. The token is single-use, expires, and is bound to the exact arguments — a changed prompt or a swapped file between the two calls is refused. Pure text prompts, URLs, files/ references and base64 inputs are not gated.

variable

default

MCP_CONFIRM_MODE

ask-user

What a write does on a client that cannot show a confirmation prompt (claude.ai, Claude Desktop). ask-user: two steps — the first call does nothing and returns a preview plus a token, and the model must get your approval in chat before calling again with it. auto: the same two steps, but the model may use the token after reviewing the preview itself. refuse: writes are refused on such clients. A client that can show prompts (Claude Code) always gets the real prompt, unless MCP_CONFIRM_ELICITATION=off. An unrecognised value is treated as refuse.

MCP_CONFIRM_ELICITATION

on

off never shows a confirmation prompt, so every client gets the MCP_CONFIRM_MODE path. Set it for a client that claims to support prompts but never shows one (the gated call hangs — opencode 2.0.x). Any other value stays on, with a warning on stderr.

MCP_CONFIRM_TTL_SECONDS

600

How long a token stays valid.

MCP_CONFIRM_SECRET

random per process

Signing key; set it only if tokens must survive a server restart.

Long generations and client timeouts

4K / Pro-model generations can outrun an MCP host's own tools/call timeout (error -32001). The server sends notifications/progress heartbeats so hosts that reset their timeout on progress wait it out. If the host still gives up, the server-side generation usually completes anyway: the image is written to the output dir, gemini_interact also writes an <image>.json sidecar recording the interaction_id, and continue_last: true resumes the interaction the lost response belonged to.

When a chained call 404s

A 404 on a request carrying previous_interaction_id is not proof the chain expired. The only 404 body observed live is generic — "Requested entity was not found." — and never names which entity. An unknown or renamed model id, and an expired Files API files/… uri (~48h TTL), return exactly the same thing. So the server no longer asserts a cause it can't establish: the upstream text is surfaced verbatim, and gemini_interact runs an experiment to find out which it was.

Most often the id isn't missing at all — it just isn't visible yet. The interactions store is eventually consistent, and a freshly created id can 404 while the same id resolves fine minutes later; heavy turns (4K, Pro, thinking_level: high) are the likeliest to hit it, which is exactly the turn you most want to chain from. So a chained 404 is retried with exponential backoff for up to 120s (GEMINI_CHAIN_RETRY_MS) before anything is declared broken. The 404 generates nothing and isn't billed, so the wait costs only time.

After that budget is spent, the tool looks up that id's sidecar, re-attaches the image it produced, and re-issues the request without the chain:

  • The re-issue succeeds → the chain really was the problem, and you get your image anyway, reported as chain_recovered: { expired_interaction_id, reanchored_on }. The 404'd attempt generates nothing, so this costs the one generation you'd have paid for re-anchoring manually.

  • The re-issue 404s too → the interaction id was never the cause. You get told exactly that, with the upstream text, and pointed at the model id and any files/… uri instead of being sent to chase an interaction that was fine all along.

  • No sidecar matches the dead id → the original error, rather than a guess. Re-anchoring on the wrong picture would silently corrupt the edit.

Separately, continue_last no longer dies with the server process: with no in-memory id it resumes from the newest <image>.json sidecar in the output dir and reports continued_from_sidecar: true. That case was never an expired chain at all — the interaction was alive upstream the whole time; only our memory of its id was gone.

For hosts whose timeout can't be tamed (e.g. Claude Desktop, a fixed ~30s cap that ignores progress), two guards make re-issuing safe and unnecessary:

  • async: true returns a job_id immediately instead of the image, so the call can't time out at all; poll gemini_get_result with the job_id until it's done.

  • idempotency_key makes a repeat call idempotent — a retry with the same key returns the recorded result (reused: true) instead of billing a second generation. (Even without a key, two identical in-flight calls are deduplicated automatically.)

Related MCP server: mmxomni

Tools

Tool

Description

gemini_list_models

List available Gemini image models and the current default

gemini_image_generate

Generate image(s) from a text prompt

gemini_image_edit

One-off edits or multi-image composition with a text instruction (for a series of edits, use gemini_interact)

gemini_image_set

Generate a master image plus N consistent images referencing it

gemini_interact

Preferred tool for iterative refinement: multi-turn generation/editing via the Interactions API — chain the returned interaction_id via previous_interaction_id (or continue_last: true)

gemini_video_generate

Generate a short video (text→video, image→video, two-still interpolation, edit or extend) via the Gemini omni model; resolution 360p/720p/1080p/4k is the cost lever; written to disk as MP4

gemini_music_generate

Generate music from a text prompt via a Lyria model — lyria-3-clip-preview (30s, default), lyria-3.5 (full-length, vocals) or lyria-3-pro-preview; single-turn; written to disk as MP3

gemini_get_result

Fetch an async generation started with async: true by its job_id (status running → done result). Lets a long generation outlive a host's tools/call timeout

gemini_token_usage

Token usage and an estimated USD cost for this session so far. Call it before and after a workflow and subtract to attribute that workflow's spend. Priced per call against each call's own model from a dated rate card (GEMINI_RATE_CARD overrides it); there is no account-balance endpoint to read, so this is how spend is attributed

gemini_upload_file

Upload an image (or video/audio) to the Gemini Files API once — from a url, data_base64, or a local path — and get a reusable files/<id> reference

gemini_list_files

List the files currently uploaded under this API key, with MIME types and expiry times

gemini_delete_file

Delete an uploaded file before its ~48h expiry (confirmed first — see Confirmations)

gemini_sign_media

(hosted deployments only) Mint a fresh signed URL for generated media from its r2_key — an expired link is not a dead end

gemini_view_media

(hosted deployments only) Return a generated image as an inline image block from its r2_key, so a model can actually see what it made before refining it

gemini_get_upload_url

(hosted deployments only) Mint a short-lived signed PUT URL so a shell can upload a reference image with no auth header; the PUT returns an r2_key usable in images_r2_keys, gemini_save_character, or gemini_upload_file

gemini_save_character / gemini_list_characters / gemini_delete_character

(hosted deployments only) Persistent per-account character library: save a reference image + description under a name, then pass characters: ["name"] on generation tools. No expiry

gemini_save_style / gemini_list_styles / gemini_delete_style

(hosted deployments only) Persistent per-account style presets: a reusable prompt fragment (optionally with a reference image), applied by passing style: "name" on generation tools. No expiry

Generation tools also share three throughput/latency controls: async: true (return a job_id immediately), max_wait_ms (wait up to a budget, then hand back the job_id — fast results stay in-band, slow batches never trip the host timeout), and idempotency_key (a retry returns the recorded result instead of re-billing). On a hosted deployment, a gemini_image_set result with more than one image also carries a bundle_url — one signed URL for a zip of every image in the set. Like every hosted link it lives at most 24h (the host's blob-store ceiling); gemini_sign_media re-mints an expired one. (A set too large to zip safely in memory skips the bundle and says so via bundle_skipped; the per-image links are unaffected.)

Seeing your images (hosted)

On a hosted deployment there is no filesystem, so a generated image has to come back as something you can open. It does: every result includes a URL, with no configuration.

{
  "images": ["https://mcp.nullnet.app/b/<account>/gemini/gen/2026-07-29/ab12cd34-a-cat.png?exp=…&sig=…"],
  "media":  [{ "url": "https://…", "r2_key": "gen/2026-07-29/ab12cd34-a-cat.png",
               "expires_at": "2026-07-31T12:00:00.000Z",
               "curl_hint": "curl -sS -o a-cat.png \"https://…\"" }]
}

Those links need no auth header — the signature is in the URL — so they work in a browser, in curl, and in a chat message. They expire after at most 24h — the host's blob store refuses a longer signature — and the objects behind them are swept on the host's retention schedule. The r2_key is the durable handle for that window:

  • gemini_sign_media (hosted deployments only) mints a fresh signed URL from an r2_key, so an expired link never forces you to re-generate — and re-pay for — the image.

  • The interaction id is stored beside each image, so a hosted deployment recovers a lost turn the way the local one does: continue_last: true survives a restart, a chained 404 is re-anchored on the image that interaction produced, and gemini_list_recent_media shows the prompt, model and interaction id for every stored object rather than a wall of keys.

  • gemini_view_media (hosted deployments only) returns the image itself, inline, from an r2_key. A link is not something a model can look at, so without this a generate → refine loop runs blind. It is a separate call rather than bytes on every result: you pay image tokens only on the turns you actually look.

  • gemini_upload_file with r2_key turns media this server generated into a Files API reference (the server reads it back with its own key — no signature for you to mint), so a generated image can become the reference image for the next generation in one cheap call.

  • Idempotent replays (idempotency_key) re-mint the URLs inside the recorded result before returning it, so a reused result never carries a dead link.

Why this matters: MCP's inline image content blocks (inline: true) are visible to the assistant but many chat clients never render them to the user, and the assistant cannot extract bytes back out of its own context to save them elsewhere. A generation could bill successfully and be invisible. A URL is the portable answer; inline remains available, but it is no longer the only way to receive media.

How the bytes are served

The host stores each generated object and serves it back at a signed, expiring URL — https://<host>/b/<account>/gemini/<key>?exp=&sig=. No setup, and no auth header: the signature in the link is the authorization, so curl and a browser both work.

Auth is a signed, expiring URL rather than an unlisted key. Random keys would be simpler, but they never expire and never revoke: anything that ever logged or forwarded the link keeps working forever. A signature scopes access to one object with a deadline, and rotating the host's signing key (MCP_BLOB_SIGNING_KEY, which mcp-host injects together with MCP_BLOB_BASE_URL; this server never chooses either) invalidates every outstanding link at once. The tradeoff is that links are long and cannot be shortened by hand.

For assistants relaying a result

Show the user the URL. If your sandbox has network egress to the host, fetching it and attaching the bytes as a file gives the nicest result; otherwise present the link itself. Whether a given client renders ![](url) markdown inline varies by client — a bare URL is the safe form, and a markdown link is a reasonable enhancement where you know it renders.

Retention

Retention is the host's, not a setting of this server. On mcp-host, the blob store prunes generated media (gen/) and signed uploads (up/) on its own schedule (see mcp-host docs/BLOB-STORE.md; default 30 days), while the character/style library (lib/) is written as retention-exempt, so saved entries never expire. Every signed link is clamped to the store's 24h ceiling, so it never outlives what the store will honour; gemini_sign_media re-mints one for as long as the object exists. The variables this server reads for it are injected by the host: MCP_BLOB_BASE_URL and MCP_BLOB_SIGNING_KEY.

Prompts are stored too. Each generated object on a hosted deployment gets a small JSON record beside it holding the prompt (first 500 characters), model and interaction id — that is what gemini_list_recent_media shows and what lets a lost turn be recovered. The record lives and is swept with its object, so it is kept for the same retention window, not longer. Locally, gemini_interact writes an <image>.json sidecar (model, interaction id, options and any text the model replied with — not the prompt itself) next to each image in the output dir; those files are yours to keep or delete and never expire on their own. If your prompts describe real people, bear in mind they sit in your bucket for the retention window.

Sending reference images without burning context

Every tool that takes a reference image — gemini_image_generate, gemini_image_edit, gemini_image_set, gemini_interact, plus gemini_video_generate (reference stills) and gemini_music_generate — accepts them four ways. Only one of them costs model context:

Parameter

Where the bytes travel

Context cost

images_url (master_images_url)

the server downloads the https URL

none

images_file_uris (master_images_file_uris)

a files/<id> reference, already uploaded

none

images_r2_keys (master_images_r2_keys)

the server reads its own store (hosted deployments only)

none

images

read off local disk (stdio builds only)

none

characters / style

saved library entries, attached by name (hosted deployments only)

none

images_base64

through the tool-call JSON

~14k tokens per JPEG

images_base64 is the fallback of last resort. It costs roughly 14k tokens per modest photo, and it is silently corrupted whenever the file read that produced it was truncated — the payload still looks like base64, so the failure surfaces as a bad generation rather than an error. Prefer any of the other three.

images_url — the server fetches it

{ "prompt": "make it look like winter", "images_url": ["https://example.com/photo.jpg"] }

Fetches are restricted to public https:// URLs — private, loopback and link-local hosts are refused (IPv6 literals are parsed, so [::ffff:7f00:1] is caught as loopback), every redirect hop is revalidated, and each hop is bounded by a timeout. The response must be Content-Type: image/* and is capped at 15MB, enforced while streaming rather than trusted from Content-Length. A failure names the offending URL. Anything over 6MB is uploaded to the Files API and referenced by uri instead of inlined, since generateContent caps a whole request near 20MB.

images_file_uris — upload once, reference many times

// 1. upload
{ "tool": "gemini_upload_file", "url": "https://example.com/photo.jpg" }
// → { "file_uri": "files/abc123", "mime_type": "image/jpeg", "expires": "..." }

// 2. reference it, as many times as you like
{ "prompt": "make it winter",  "images_file_uris": ["files/abc123"] }
{ "prompt": "make it sunrise", "images_file_uris": ["files/abc123"] }

Uploads are retained ~48h; after that the reference stops resolving (as a generic 404 — see the chained-404 section above). gemini_image_set fetches or resolves such a reference once and passes it to the master and every scene call.

On stdio builds, a local images path that gets referenced more than once in a session is uploaded to the Files API automatically (keyed on path + mtime + size), so repeated edits of the same photo stop re-sending the bytes. Editing the file invalidates the cached upload.

Signed upload URLs — no token at all (hosted)

This is the intended path for an agent with a shell: disk file → curl → r2_key → tool call, with the image never entering the conversation. gemini_get_upload_url mints a short-lived (~10 min) signed PUT URL, and the shell uploads with zero auth headers — the signature in the URL is the authorization, mirroring how the download links work.

# 1. tool call: gemini_get_upload_url { filename: "photo.jpg", content_type: "image/jpeg" }
#    → { upload_url, r2_key, expires_at, curl_hint }

# 2. shell:
curl -sS -X PUT -H "Content-Type: image/jpeg" --data-binary @photo.jpg "$UPLOAD_URL"
# → { "r2_key": "up/<tenant>/2026-07-31/ab12cd34-photo.jpg", "size_bytes": 812345, ... }

The signature covers one tenant-scoped object key, the declared content type and the expiry; uploads are capped at 15MB, enforced while reading the stream. Only raster image types are accepted (jpeg/png/webp/gif/avif/heic/heif/bmp/tiff) — SVG is deliberately refused, because an SVG is a scriptable document and /media serves from the server's own origin. The returned r2_key is then usable three ways: directly as images_r2_keys on any generation tool (the server reads its own bucket — no bytes in the conversation), permanently via gemini_save_character, or as a ~48h Files API reference via gemini_upload_file({ r2_key }). Uploads themselves follow the host's blob-store retention schedule (up/ prefix).

Character & style library (hosted)

Recurring subjects and styles can be saved once, per account, with no expiry (the library's lib/ objects are written retention-exempt, so the host's prune skips them):

// once:
{ "tool": "gemini_save_character", "name": "finn",
  "description": "6-year-old boy, curly red hair", "image_r2_key": "up/…/photo.jpg" }
{ "tool": "gemini_save_style", "name": "bold-cartoon-sports",
  "prompt_fragment": "bold cartoon style, thick outlines, saturated colors" }

// afterwards, on any generation:
{ "tool": "gemini_image_set",
  "master_prompt": "Finn on a soccer field",
  "scenes": ["kicking the ball", "celebrating a goal"],
  "characters": ["finn"], "style": "bold-cartoon-sports" }

Naming a character attaches its saved reference image and weaves its description into the prompt; naming a style appends its fragment (and attaches its reference image, if it has one). gemini_image_set passes character references to the master and every scene call, which is what keeps the subject consistent across the set.

Quick Start

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@chrischall/gemini-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

See SKILL.md for full usage documentation.

Available Tools

13 tools
gemini_delete_fileA
Destructive

Delete an uploaded file, image or photo (by file_uri) from the Gemini Files API before its ~48h expiry. Any tool call still referencing it will then fail with a generic 404, so delete only references you are finished with. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

ParametersJSON Schema
NameRequiredDescriptionDefault
file_uriYesThe `files/<id>` reference (or full uri) to delete
confirmTokenNoONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the destructiveHint annotation, the description discloses important behaviors: the 48h expiry context, the cascading 404 failure mode for dependent calls, and the confirmation/confirmToken mechanism. It is honest and detailed about the destructive consequences without contradicting 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.

Conciseness5/5

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

Three dense sentences, each earning its place: purpose + expiry, failure consequence + usage rule, and confirmation behavior. The most important information is front-loaded, and the destructive-safety caveats are organized clearly.

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?

For a destructive tool with no output schema, the description covers what an agent needs: what gets deleted, when deletion is safe, what happens to referencing calls, and how confirmation works. The reference to MCP_CONFIRM_MODE is a minor external hook, but the core call sequence is fully specified.

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?

The schema already covers both parameters with 100% coverage, so the baseline is 3. The description adds useful operational meaning around confirmToken (preview first, repeat call only after approval, MCP_CONFIRM_MODE), which is helpfully above baseline, though it does not significantly add syntax details for file_uri beyond the schema.

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 opens with a specific verb ('Delete') and a precise resource ('uploaded file, image or photo (by file_uri) from the Gemini Files API'), which immediately disambiguates it from generation and listing siblings. It also adds meaningful context (the ~48h expiry) that the tool name alone cannot convey.

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

Usage Guidelines5/5

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

The description states both when to use the tool ('delete only references you are finished with') and when not to (any still-referenced file will fail with a generic 404). It also explains the two-step confirmation flow, giving the agent explicit operational guidance about how calls should proceed.

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

gemini_get_resultA
Destructive

Retrieve a generation started with async: true or handed off by max_wait_ms. Pass the returned job_id: while running it reports status "running"; on completion it returns the normal result (image URLs/paths + meta); on failure it raises the recorded error, including the case where the generation was killed before it finished. On the hosted connector job records are stored durably and survive a restart; on a local stdio server they live with the process and expire ~10 min after completion, where the output dir / .json sidecar is the fallback. A killed video/music job started with background: true is recovered from its upstream interaction when it finished there.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYesThe job_id returned by a generation tool called with async: true
output_dirNoWhere to write media recovered from a killed job (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), and the description layers on substantial extra behavior: the 'running' status during polling, that failures raise the recorded error (including killed-before-finish), durability differences between hosted and local stdio, ~10 min post-completion expiry, and the output-dir/sidecar fallback. This is exactly the kind of state and lifecycle context annotations cannot express.

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?

Purpose is front-loaded in sentence one, followed by tightly packed lifecycle behavior; nearly every clause earns its place. The paragraph is dense and long, but the density reflects real complexity rather than filler.

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?

For a complex async-retrieval tool with no output schema, the description covers return shape on success ('image URLs/paths + meta'), failure semantics, persistence/expiry, and recovery of killed background jobs. An agent has everything needed to call and interpret this correctly.

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, but the description adds meaningful origin context for `job_id` (it comes from an async call or a max_wait_ms handoff) beyond the schema's terse 'returned by a generation tool'. `output_dir` is left to the schema, which documents it fully.

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 precise verb+resource (retrieve a generation started with `async: true` or handed off by `max_wait_ms`) and identifies the exact handle to pass (`job_id`). It clearly positions itself as the retrieval counterpart to the generate/edit siblings, so an agent can tell it apart without opening a 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?

It names the triggering conditions directly: call it after a generation returned a job via `async: true` or a `max_wait_ms` handoff. It stops short of stating explicit when-not-to-use cases or naming an alternative poller, but the gating condition is unambiguous.

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

gemini_healthcheckVerify credentials and upstream reachabilityA
Read-onlyIdempotent

Resolves the credential the way real tools do, then makes one authenticated request to generativelanguage.googleapis.com. Reports which source supplied the credential, whether generativelanguage.googleapis.com accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a generativelanguage.googleapis.com-side problem'. Read-only; never returns the credential itself. Call this when a real tool fails and you want to know which hop broke.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds meaningful behavioral details: it never returns the credential, makes exactly one authenticated request, and reports a plain-English hint distinguishing 'no credential', 'credential rejected', and upstream problems. This goes well beyond what annotations convey.

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?

Four sentences with no filler: the core behavior is front-loaded, followed by reported outputs, the read-only safety note, and the usage instruction. Every sentence earns its place and the description remains compact.

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?

Despite having no parameters and no output schema, the description covers inputs, behavior, outputs, side effects, and invocation context. An agent has everything needed to decide when and how to call this tool.

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?

The tool has zero parameters and empty schema properties, so schema coverage is trivially 100%. There are no parameter semantics to describe, and the baseline of 4 for no-parameter tools 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?

The description states a specific diagnostic purpose: resolve the credential the way real tools do, then make one authenticated request to generativelanguage.googleapis.com and report source, acceptance, RTT, and failure hint. This clearly distinguishes it from all sibling tools that generate images, video, or music, manage files, or interact with models.

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?

It explicitly instructs to call this tool when a real tool fails and you want to know which hop broke, giving clear context for use. It doesn't name a specific alternative or say when not to use it, but the diagnostic positioning is unambiguous given the sibling list.

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

gemini_image_editA
Destructive

Edit or compose images: provide one or more input images (paths or base64), plus a text instruction. For a SERIES of successive edits to the same image, prefer gemini_interact (multi-turn) — it keeps edit context and avoids re-processing the full image each round; use gemini_image_edit for one-off edits or composing multiple distinct inputs. Gemini over-preserves the input; there is no edit-strength control — for large structural changes, reroll with a different seed or more forceful wording. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoSeed for reproducible generation; random if omitted
asyncNoReturn a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait.
modelNoModel id override (default: server default; see gemini_list_models). gemini-nano-banana-2.1 (Nano Banana 2.1, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding.
styleNoName of a saved style preset (gemini_list_styles): its prompt fragment, and reference image if it has one, are applied automatically. Hosted connector only.
imagesNoPaths to input image file(s) (1 = edit, 2+ = compose). Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set.
inlineNoReturn the image as an inline image block you can SEE, instead of a path (stdio) or link (hosted). The default costs nothing to carry and hands back a reference you can reuse; use this when you need to check the result yourself. On the hosted connector gemini_view_media does the same for an image you already have
promptYesInstruction describing the edit or composition
filenameNoBase filename for the output image (extension stripped; default: slugified prompt)
charactersNoNames of saved characters (gemini_list_characters): each one's reference image and description are attached automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only.
image_sizeNoOutput resolution (512 = 0.5K, gemini-3.1-flash-image only)
images_urlNoInput images as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*.
output_dirNoDirectory to write images to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)
timeout_msNoUpstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)
max_wait_msNoWait up to this many ms in-band, then hand back { job_id, status: "running" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set.
orientationNoOutput shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — 3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given.
aspect_ratioNoExact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.
confirmTokenNoONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
google_searchNoGround the image in live Google Search results (current events, weather, data)
images_base64NoInput images as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer images_url or images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to images_file_uris next time instead of re-sending the bytes.
from_clipboardNoUse the image currently on the macOS system clipboard as an input (downscaled to JPEG)
images_r2_keysNoInput images by r2_key from this connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket — no bytes in the conversation, no ~48h expiry. Hosted connector only.
thinking_levelNoReasoning depth (Gemini 3 models); higher can help complex/structural edits
idempotency_keyNoRepeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001).
images_file_urisNoInput images as Files API references ("files/<id>" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving.

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the write/overwrite nature is covered structurally. The description adds genuinely useful behavior beyond that: 'Gemini over-preserves the input; there is no edit-strength control' and the two-step confirmation fallback with confirmToken semantics. That extra context is real, but the bar is high when annotations already carry the safety profile, and return format/polling behavior is left to individual parameter descriptions rather than stated as tool behavior.

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 purpose and routing rules, with zero filler sentences; each clause carries operational information. It loses a point because the closing confirmation paragraph partially restates what the confirmToken schema description already documents, adding length without new meaning.

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?

For a 24-parameter tool with no output schema, the description covers the pieces an agent most needs before calling: which sibling to prefer, that edits over-preserve, how to reroll, and that local file inputs trigger confirmation. Return-shape choices are handled by the inline/images params, so nothing critical is missing at the tool level.

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% across all 24 parameters, and the schema itself explains seed, async, model, image input channels, timeouts and aspect ratios in detail. The description adds almost no parameter-level semantics of its own (only the seed reroll advice), so the baseline 3 is the correct ceiling here.

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?

Opens with a specific verb pair and resource: 'Edit or compose images', then immediately states the required input shape (one or more images plus a text instruction). It also routes between edit vs compose within the same tool ('1 = edit, 2+ = compose' via schema, and the description distinguishes them), so an agent can tell it apart from gemini_image_generate and gemini_image_set without opening either schema.

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

Usage Guidelines5/5

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

Gives an explicit when-to-use-this vs when-to-use-the-alternative rule: prefer gemini_interact for a SERIES of successive edits to the same image, use gemini_image_edit for one-off edits or composing distinct inputs. It also names the failure mode and its remedy ('for large structural changes, reroll with a different seed or more forceful wording'), which is actionable guidance rather than vague context.

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

gemini_image_generateA
Destructive

Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro). If the result will likely be refined iteratively, prefer gemini_interact (multi-turn) as the entry point. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoSeed for reproducible generation; random if omitted
asyncNoReturn a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait.
countNoNumber of independent images (default 1)
modelNoModel id override (default: server default; see gemini_list_models). gemini-nano-banana-2.1 (Nano Banana 2.1, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding.
styleNoName of a saved style preset (gemini_list_styles): its prompt fragment, and reference image if it has one, are applied automatically. Hosted connector only.
imagesNoPaths to reference input images (image-conditioned generation). Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set.
inlineNoReturn the image as an inline image block you can SEE, instead of a path (stdio) or link (hosted). The default costs nothing to carry and hands back a reference you can reuse; use this when you need to check the result yourself. On the hosted connector gemini_view_media does the same for an image you already have
promptYesText prompt describing the image
filenameNoBase filename for the output image (extension stripped; default: slugified prompt)
video_urlNoPublic YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)
charactersNoNames of saved characters (gemini_list_characters): each one's reference image and description are attached automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only.
image_sizeNoOutput resolution (512 = 0.5K, gemini-3.1-flash-image only)
images_urlNoReference images as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*.
output_dirNoDirectory to write images to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)
timeout_msNoUpstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)
video_pathNoPath to a local video file — uploaded to the Gemini Files API (~48h retention, 2 GB max) and used as the video reference. Alternative to video_url.
max_wait_msNoWait up to this many ms in-band, then hand back { job_id, status: "running" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set.
orientationNoOutput shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — 3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given.
aspect_ratioNoExact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.
confirmTokenNoONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
google_searchNoGround the image in live Google Search results (current events, weather, data)
images_base64NoReference images as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer images_url or images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to images_file_uris next time instead of re-sending the bytes.
from_clipboardNoUse the image currently on the macOS system clipboard as an input (downscaled to JPEG)
images_r2_keysNoReference images by r2_key from this connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket — no bytes in the conversation, no ~48h expiry. Hosted connector only.
thinking_levelNoReasoning depth (Gemini 3 models); higher can help complex/structural edits
idempotency_keyNoRepeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001).
images_file_urisNoReference images as Files API references ("files/<id>" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving.

TDQS

A4.2/5.0
Behavior4/5

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

Illustrates a concrete non-obvious behavioral trait: local file inputs trigger a two-step confirmation (elicitation prompt, or preview + confirmToken with MCP_CONFIRM_MODE). That goes beyond the readOnly/destructive/openWorld annotations. It does not explain why the tool is flagged destructive (e.g. that output files are written to disk) or the billing implication, which the schema only touches via idempotency_key.

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?

Three sentences, front-loaded with the core action, then the routing hint, then the confirmation caveat. For a 27-parameter tool this is remarkably economical and every sentence carries distinct information.

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?

Given 27 parameters, 100% schema coverage, no output schema, and a destructiveHint of true, the description covers the main things an agent needs to call it safely: the alternative entry point and the confirmation flow. It is slightly light on outcome behavior, since nothing states that images are written to a filesystem location rather than returned, leaving the agent to infer the destructive flag.

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% across 27 parameters, so the schema itself does the heavy lifting on every input, including confirmToken, model, and image sources. The description adds no parameter-level meaning beyond what the schema already documents, so the baseline 3 is correct.

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 ('Generate image(s) from a text prompt with a Gemini image model') and names the concrete model families involved. It also differentiates itself from the sibling it could be confused with by routing to gemini_interact for iterative work, so an agent can distinguish it without opening another 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?

Gives an explicit selection rule: prefer gemini_interact when the result will be refined iteratively. That is real when-to-use guidance tied to a named alternative. It stops short of contrasting with gemini_image_edit or stating when-not to use this tool at all, so it is clear but not exhaustive.

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

gemini_image_setA
Destructive

Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide scenes (explicit per-image prompts) OR count (variations of the master). Scene generations run in parallel (reference_mode "master", the default). On the hosted connector: saved characters and a saved style can seed the whole set by name, multi-image results include a bundle_url zip of every image (one curl instead of N), and max_wait_ms returns a pollable job handle if the batch runs long. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoSeed for reproducible generation; random if omitted
asyncNoReturn a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait.
countNoNumber of variations of master_prompt (when scenes omitted)
modelNoModel id override (default: server default; see gemini_list_models). gemini-nano-banana-2.1 (Nano Banana 2.1, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding.
styleNoName of a saved style preset (gemini_list_styles): its prompt fragment, and reference image if it has one, are applied automatically. Hosted connector only.
inlineNoReturn the image as an inline image block you can SEE, instead of a path (stdio) or link (hosted). The default costs nothing to carry and hands back a reference you can reuse; use this when you need to check the result yourself. On the hosted connector gemini_view_media does the same for an image you already have
scenesNoPer-image prompts (1-8); each references the master
basenameNoBase filename prefix for output images (default: slugified master_prompt)
charactersNoNames of saved characters (gemini_list_characters): each one's reference image and description are attached automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only.
image_sizeNoOutput resolution (512 = 0.5K, gemini-3.1-flash-image only)
output_dirNoDirectory to write images to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)
timeout_msNoUpstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)
max_wait_msNoWait up to this many ms in-band, then hand back { job_id, status: "running" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set.
orientationNoOutput shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — 3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given.
aspect_ratioNoExact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.
confirmTokenNoONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
google_searchNoGround the image in live Google Search results (current events, weather, data)
master_imagesNoReference image paths passed to the master generation call. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set.
master_promptYesPrompt for the master/reference image
from_clipboardNoUse the image currently on the macOS system clipboard as an input (downscaled to JPEG)
reference_modeNomaster: every image references the master (default). chain: each references the previous.
thinking_levelNoReasoning depth (Gemini 3 models); higher can help complex/structural edits
idempotency_keyNoRepeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001).
master_images_urlNoReference images passed to the master AND to every scene call (fetched once) as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*.
master_images_base64NoReference images for the master generation as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer master_images_url or master_images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to master_images_file_uris next time instead of re-sending the bytes.
master_images_r2_keysNoReference images passed to the master AND to every scene call by r2_key from this connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket — no bytes in the conversation, no ~48h expiry. Hosted connector only.
master_images_file_urisNoReference images passed to the master AND to every scene call as Files API references ("files/<id>" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving.

TDQS

A4.6/5.0
Behavior5/5

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

Beyond annotations, the description discloses parallel scene generation, hosted connector seeding via saved characters/style, bundle_url output, max_wait polling behavior, and a local-input confirmation flow. These are substantial behavioral details an agent would not know from the annotations alone.

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 description is long but front-loads the core purpose and set-generation model. Given the tool's 27 parameters and complex hosted/local behavior, the length is mostly justified, though the single dense paragraph could be more scannable.

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?

With no output schema, the description still covers key return behavior: multi-image results include a bundle_url zip, max_wait returns a pollable job handle, and inline controls visibility. For a complex 27-parameter tool, this gives an agent enough operational context alongside the fully described schema.

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, but the description adds orchestration semantics: `scenes` and `count` are alternatives, `reference_mode` defaults to master, and hosted connector parameters such as characters/style can seed the set. It still relies heavily on the schema for individual parameter meaning.

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 verb and resource: generate a consistent SET of images with a master image and one image per scene. It distinguishes this from sibling single-image generation by emphasizing set consistency and master/reference reuse.

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?

It clearly explains when to provide `scenes` versus `count`, and notes that `reference_mode: master` is the default. It does not explicitly name sibling alternatives such as gemini_image_generate, so it stops short of the highest usage-guideline score.

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

gemini_interactA
Destructive

Preferred tool for iterative refinement of a single image — multi-turn generation and editing via the Interactions API. To refine, pass the returned interaction id as previous_interaction_id on the next call; do NOT start a new interaction or re-send the image for each tweak. continue_last: true chains from this session's most recent interaction without threading the id. If a call times out client-side the generation usually still completes: the image and an <image>.json sidecar holding its interaction id land in the output dir, and continue_last: true still resumes it — look there before re-issuing, which bills a second generation. A chained 404 is re-anchored on the prior output and re-issued un-chained (chain_recovered); a second 404 means the interaction id was not the cause — check the model id / files uri. Output is JPEG. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

ParametersJSON Schema
NameRequiredDescriptionDefault
asyncNoReturn a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait.
inputYesText prompt or editing instruction
modelNoModel id override (default: server default; see gemini_list_models). gemini-nano-banana-2.1 (Nano Banana 2.1, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding.
imagesNoPaths to reference input images. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit.
inlineNoReturn base64 images inline instead of writing to disk
filenameNoBase filename for the output image (extension stripped; default: slugified input)
video_urlNoPublic YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)
image_sizeNoOutput resolution (512 = 0.5K, gemini-3.1-flash-image only)
images_urlNoReference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*.
output_dirNoDirectory to write images to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)
timeout_msNoUpstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)
video_pathNoPath to a local video file — uploaded to the Gemini Files API (~48h retention, 2 GB max) and used as the video reference. Alternative to video_url.
max_wait_msNoWait up to this many ms in-band, then hand back { job_id, status: "running" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set.
orientationNoOutput shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — 3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given.
aspect_ratioNoExact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.
confirmTokenNoONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
search_typesNoGrounding search types (implies google_search). image_search (gemini-3.1-flash-image only) uses Google Image Search results as visual references; per Google ToS the returned grounding.search_suggestions HTML must then be displayed to the user. Cannot depict real people from web images.
continue_lastNoContinue from the most recent interaction this server created (convenience for previous_interaction_id; an explicit id wins). Survives a server restart by falling back to the newest <image>.json sidecar in the output dir.
google_searchNoGround the image in live Google Search results (current events, weather, data)
images_base64NoReference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer images_url or images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to images_file_uris next time instead of re-sending the bytes.
from_clipboardNoUse the image currently on the macOS system clipboard as an input (downscaled to JPEG)
thinking_levelNoReasoning depth; higher can help complex/structural edits
idempotency_keyNoRepeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001).
images_file_urisNoReference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given as Files API references ("files/<id>" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving.
previous_interaction_idNoID from a prior gemini_interact call — continues that multi-turn conversation

TDQS

A4.4/5.0
Behavior5/5

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

Annotations declare destructive/openWorld/not-readOnly, and the description adds substantial context on top: billing for re-issued generations, the 404 re-anchor and chain_recovered behavior, the two-step confirmToken flow and MCP_CONFIRM_MODE fallback, JPEG output, and the sidecar file that survives a client timeout. This is exactly the beyond-annotation disclosure the dimension asks for.

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 purpose and chaining rule, and every sentence carries operational information (billing, recovery, confirmation). It is a single dense paragraph with no internal structure, which makes it harder to scan than it needs to be for a 25-parameter tool.

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?

No output schema exists, and the description still covers what comes back (image file, <image>.json sidecar, confirmToken phase-1 response, job_id handback) plus the failure and retry paths. For a 25-parameter tool with destructive annotations, nothing an agent needs to call it 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% and the schema entries are already very detailed (including the chaining warnings on every image parameter), so the bar for the description is low. The description largely restates the schema's chaining story (previous_interaction_id, continue_last) rather than adding syntax or format detail the schema lacks, so baseline 3 is right.

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?

Names a specific verb+resource ('iterative refinement of a single image — multi-turn generation and editing via the Interactions API') and positions itself as the 'preferred' tool for that job, which distinguishes it from gemini_image_generate and gemini_image_edit. An agent can tell what this does without opening the 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?

Gives strong when-to-use and when-not-to guidance: thread previous_interaction_id rather than starting a new interaction, use continue_last to chain without the id, and check the output dir/sidecar before re-issuing to avoid a billed second generation. It never names the sibling tools it supersedes for one-shot work, so differentiation from gemini_image_generate/edit is implied rather than explicit.

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

gemini_list_filesA
Read-only

List files, images and photos currently uploaded to the Gemini Files API under this API key, with their reusable file_uri (files/<id>) references, MIME types and expiry times. Retention is ~48h, so an entry that has vanished has expired rather than failed.

ParametersJSON Schema
NameRequiredDescriptionDefault
page_sizeNoMaximum files to return (1-100, default 100)

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to restate safety. It adds valuable behavioral context: retention is ~48h, so vanished entries have expired rather than failed, and it discloses that results include file_uri, MIME types, and expiry times. This goes beyond the annotations and helps the agent interpret results correctly.

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?

Two sentences, front-loaded with the core purpose and scope, followed by a useful retention caveat. No wasted words; 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 read-only list tool with one optional parameter and no output schema, the description is nearly complete. It explains what is returned (file_uri, MIME types, expiry times) and how to interpret missing entries. It doesn't describe pagination or the exact response format, but those are minor given the tool's simplicity and the annotations covering safety.

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% for the single optional page_size parameter, so the schema already documents it fully. The description doesn't add parameter-specific details, but with full coverage, baseline 3 is appropriate.

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 clearly states the tool lists files, images, and photos uploaded to the Gemini Files API under the current API key, and distinguishes it from other operations by mentioning reusable file_uri references, MIME types, and expiry times. It uses a specific verb ('List') and resource ('files... under this API key'), making it easy to differentiate from siblings like gemini_upload_file and gemini_delete_file.

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 implies when to use this tool: to check currently uploaded files and their references, and clarifies that missing entries mean expiry rather than failure. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over upload/delete/get_result tools.

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

gemini_list_modelsA
Read-only

List the Gemini image-generation models available to your API key (Nano Banana / Nano Banana Pro family), and the current default model.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context by stating results are scoped to 'your API key' and that the current default is included, but says nothing about ordering, pagination, or how model identifiers are returned.

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?

A single front-loaded sentence that names the resource first and the secondary output (default model) second. Nothing redundant, nothing padded.

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 no parameters and no output schema, the description needs to carry the return shape, and it does so at a high level: a list of models plus the current default. It stops short of describing the fields per model (IDs, capabilities), so it is nearly but not fully complete.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter information is missing.

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 ('List') and resource ('Gemini image-generation models'), scoped to the caller's API key, plus a second output element (current default model). The 'image-generation' qualifier and the Nano Banana family naming clearly separate it from gemini_list_files, gemini_healthcheck and the generation tools.

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?

Usage is only implied: an agent can infer this is a discovery call to run before choosing a model for gemini_image_generate/edit. There is no explicit 'use this when…' or 'prefer X instead' guidance, and no stated preconditions.

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

gemini_music_generateA
Destructive

Generate music from a text prompt (mood, genre, instruments, structure, or lyrics inline) via a Lyria model: lyria-3-clip-preview (30s instrumental clip, default, cheapest), lyria-3.5 (full-length song with vocals) or lyria-3-pro-preview (longer-form). Output is MP3, written to disk (or returned inline). Single-turn: a track cannot be refined by a follow-up call, so put the whole brief in the prompt. Runs long — give it a max_wait_ms budget (or async: true + gemini_get_result on a local install), or raise timeout_ms. Needs a funded account. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

ParametersJSON Schema
NameRequiredDescriptionDefault
asyncNoReturn a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait.
modelNoLyria model (default: lyria-3-clip-preview — 30s, $0.04). lyria-3.5 and lyria-3-pro-preview run minutes-long at $0.08.
imagesNoOptional reference image path(s) to condition the music. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set.
inlineNoReturn base64 audio inline instead of writing to disk. A 30s track is ~1.9MB of base64 — the default hands back a path instead
promptYesDescription of the music: mood, genre, instruments, tempo, structure, or lyrics
filenameNoBase filename for the output audio (extension stripped; default: slugified prompt)
backgroundNoRun the generation on Google's side and poll it, so a killed job can be recovered by gemini_get_result. Off by default — see gemini_video_generate
images_urlNoReference images as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*.
output_dirNoDirectory to write audio to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)
timeout_msNoUpstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)
max_wait_msNoWait up to this many ms in-band, then hand back { job_id, status: "running" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set.
confirmTokenNoONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
images_base64NoReference images as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer images_url or images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to images_file_uris next time instead of re-sending the bytes.
from_clipboardNoUse the image currently on the macOS clipboard as a reference
idempotency_keyNoRepeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001).
images_file_urisNoReference images as Files API references ("files/<id>" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving.

TDQS

A4.6/5.0
Behavior5/5

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

Annotations flag destructiveHint=true and openWorldHint=true, and the description adds substantial context beyond them: single-turn (no follow-up refinement), runs long, needs a funded account, and the full two-step confirmation flow for local file inputs. This is exactly the added value descriptions are for.

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?

Dense but front-loaded: purpose first, then model options, then cost/latency, then confirmation mechanics. Every clause carries information, though the confirmation paragraph is lengthy enough to slow scanning.

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?

For a 16-parameter generative tool with no output schema, the description covers cost, latency, output format, billing, confirmation, and polling — everything an agent needs to invoke correctly without exploring siblings.

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 already 100%, so the baseline is 3. The description nonetheless synthesizes cross-parameter behavior (async vs max_wait_ms vs timeout_ms tradeoffs, inline vs disk output, confirmToken semantics) that the per-parameter schema entries only state locally. Adds real value.

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+resource ('Generate music from a text prompt') and enumerates the exact model options with their tradeoffs, clearly distinguishing it from siblings like gemini_image_generate or gemini_video_generate. The agent knows precisely what this produces.

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 strong when-to-use context (model selection by length/cost, max_wait_ms budget, async + gemini_get_result routing) and names gemini_get_result as the polling alternative. However it doesn't explicitly contrast against adjacent tools, and the guidance is embedded rather than structured.

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

gemini_token_usageA
Read-only

Token usage for this session so far — what every generation has cost in tokens, added up. Call it before and after a workflow and subtract to get that workflow's cost; call it after a single generation for that call's. Reports tokens AND an estimated USD cost, priced per call against each call's own model and stamped with the date its rates were read (override with GEMINI_RATE_CARD). Note there is no account-balance endpoint to query — Google Cloud is post-paid and its billing data lags by hours — so this is the accurate way to attribute spend to a call.

ParametersJSON Schema
NameRequiredDescriptionDefault
resetNoZero the running total after reporting it, so the next call measures from here. Use it to bracket a workflow without arithmetic.

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only cover readOnlyHint/openWorldHint, but the description adds substantial context: it reports both tokens and estimated USD, prices each call against that call's own model, stamps the rate date, supports a GEMINI_RATE_CARD override, and explains that Google Cloud billing lags by hours so this is the accurate attribution path.

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?

Purpose is front-loaded in the first clause, and the workflow-vs-single-call guidance follows immediately. The closing sentence about billing lag is useful but slightly long; overall it stays tight with no filler.

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?

With no output schema, the description carries the burden of describing the return values, and it does: tokens plus an estimated USD cost with a rate-date stamp. It also covers the reset workflow and the billing-lag caveat, so an agent needs nothing more to call and interpret it.

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%, and the sole `reset` parameter is already fully documented in the schema ('zero the running total after reporting it'). The description hints at the subtract-before/after pattern but adds no syntax or semantics beyond what the schema provides, 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?

The opening sentence names the exact resource (token usage for the current session) and the scope (cumulative cost of every generation so far). No sibling tool reports usage or cost, so the agent can place it unambiguously. It is a specific verb+resource statement, not a restatement of the name.

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

Usage Guidelines5/5

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

It states exactly when to call it: before and after a workflow to get the delta, or after a single generation to get that call's cost. It also explains why no alternative exists ('there is no account-balance endpoint to query'), closing off the natural substitute an agent might reach for.

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

gemini_upload_fileA

Upload a file — an image, reference photo, picture, screenshot, video or audio clip — to the Gemini Files API ONCE, and get back a reusable file_uri (files/<id>) to attach to later image, video or music generations. Keywords: upload, upload file, upload image, upload photo, attach, reference image, reference photo, file_uri, files api, image reference, reuse across calls. Use this instead of pasting base64 into a tool call: the reference is a short string, so no image bytes ever enter the conversation, and it can be reused across many generations until it expires (~48h). Provide exactly one of url (the server downloads it), data_base64, or path (a local file). A local path is confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

ParametersJSON Schema
NameRequiredDescriptionDefault
urlNoPublic https URL the SERVER downloads and uploads (image/video/audio, up to 100MB). No bytes pass through the conversation.
pathNoPath to a local file (absolute, or resolved against $GEMINI_INPUT_DIR). Confirm-gated like every other local-file input.
r2_keyNoUnavailable on this server (media is written to local disk) — pass the file path via `path` instead.
mime_typeNoOverride the detected MIME type (sniffed from the bytes / taken from the server response otherwise)
data_base64NoRaw base64 or a data: URI. Last resort — this is the one form that costs model context (~14k tokens for a modest JPEG).
confirmTokenNoONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
display_nameNoHuman-readable name recorded against the upload

TDQS

A4.6/5.0
Behavior4/5

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

Goes well beyond annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing the ~48h expiry, the no-bytes-in-context property, and the two-phase local-path confirmation flow with confirmToken. Minor gap: it doesn't say whether re-uploading the same file is idempotent or what happens to the old file_uri after expiry.

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 and return value, then constraints, then the confirmation edge case. The keyword list is mild retrieval stuffing but arguably intentional; total length is justified by the two-parameter-mode and confirmation complexity.

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?

No output schema, yet the description gives the exact return shape (`file_uri` as `files/<id>`), the expiry, and the confirmation protocol. For a mutation tool with confirm gating and no output schema, nothing an agent needs to invoke it correctly is missing.

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, but the description adds genuinely new semantics the schema does not encode: 'Provide exactly one of `url`, `data_base64`, or `path`' (no oneOf in the schema) and that path is confirmation-gated. It does not explain mime_type/display_name beyond the schema, which is fine.

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+resource (upload a file to the Gemini Files API) plus the concrete payoff (a reusable `file_uri` of the form `files/<id>`), and enumerates accepted media types. It is clearly distinguishable from siblings like gemini_delete_file, gemini_list_files and the generation tools.

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

Usage Guidelines5/5

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

Explicitly routes the agent: 'Use this instead of pasting base64 into a tool call', names the alternative pattern and the reason (no image bytes in conversation), and states the reuse window until ~48h expiry. When/when-not is unambiguous.

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

gemini_video_generateA
Destructive

Generate a short video (~10s) via the Gemini omni model: text→video, image→video / reference→video (supply reference image[s]), interpolate between two stills (pass first frame then last frame as images), or continue a prior video (task: "edit" or "extend" + previous_interaction_id / continue_last; extensions add ~3-10s each, to ~40s total). Cost scales with resolution — draft at 360p, keep at 1080p/4k. Output is written to disk as MP4 (video has no inline MCP block). Video runs long — give it a max_wait_ms budget (or async: true + gemini_get_result on a local install), or raise timeout_ms. Needs a funded account. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

ParametersJSON Schema
NameRequiredDescriptionDefault
taskNotext_to_video (default), image_to_video / reference_to_video (need image input), or edit / extend (need previous_interaction_id)
asyncNoReturn a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait.
modelNoModel id override (default: gemini-omni-1.1-flash)
imagesNoReference image path(s) for image_to_video / reference_to_video. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set.
promptYesDescription of the video to generate (or the edit instruction when task=edit)
deliveryNoHow the clip comes back: "uri" (default — a Files API link the server downloads, no size ceiling) or "inline" (base64, capped ~4MB)
filenameNoBase filename for the output video (extension stripped; default: slugified prompt)
backgroundNoRun the generation on Google's side and poll it, so a killed job can be recovered by gemini_get_result. Trade-off: retrieving a backgrounded interaction is unreliable today (some become permanently unreadable), so the default is off
images_urlNoReference stills as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*.
output_dirNoDirectory to write the video to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)
resolutionNoOutput resolution (default 720p). Video is billed per output token, so 360p costs roughly a third of 720p — use it for drafts
timeout_msNoUpstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)
max_wait_msNoWait up to this many ms in-band, then hand back { job_id, status: "running" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set.
orientationNoOutput shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — 3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given.
aspect_ratioNoExact output aspect ratio (omni: 16:9 or 9:16). `orientation` is the plain-language shorthand; this wins if both are given.
confirmTokenNoONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
continue_lastNoContinue from the most recent video interaction this server created (explicit previous_interaction_id wins)
images_base64NoReference images as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer images_url or images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to images_file_uris next time instead of re-sending the bytes.
from_clipboardNoUse the image currently on the macOS clipboard as a reference
idempotency_keyNoRepeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001).
images_file_urisNoReference stills as Files API references ("files/<id>" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving.
previous_interaction_idNoInteraction id to edit/continue (with task: "edit")

TDQS

A4.6/5.0
Behavior4/5

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

Goes well beyond the annotations (destructive/openWorld) by disclosing cost-scaling behavior, disk-write output with no inline MCP block, long runtimes and timeout handling, the funded-account requirement, and the confirmation-token mechanics. The only thing it leaves slightly under-described is the exact failure/retry semantics of a killed job, but coverage is strong.

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?

Dense but front-loaded - the core purpose and mode list come first, then cost, then timing, then confirmation. It is a single long paragraph with little waste, though a 22-param tool would benefit from light structural breaks.

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?

For a 22-parameter generation tool with no output schema, the description covers the essentials an agent needs: output format and location, timing/timeout strategy, cost model, account requirement, and the confirmation protocol. Nothing critical is missing.

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?

With 100% schema coverage the schema already documents every parameter, so the baseline is 3. The description still adds synthesis the schema doesn't: extension durations (~3-10s each, to ~40s total), cost/resolution tradeoffs, and how confirmToken flows across two calls.

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 (generate a ~10s video via the Gemini omni model) and enumerates the exact modes it supports: text→video, image→video, reference→video, frame interpolation, and extend/edit. This clearly separates it from the sibling image, music, and interact tools.

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

Usage Guidelines5/5

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

Gives explicit routing: which task values need images vs previous_interaction_id, when to draft at 360p vs keep at 1080p/4k, and how to avoid the host timeout (max_wait_ms, async + gemini_get_result, or timeout_ms). It also names the confirmation flow so the agent knows the two-step path before calling.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv2.4.0
    • Changedgemini_get_result1 field changed
      • changedInput schema / properties / output_dir / description
        Previous value: -"Where to write media recovered from a killed job (default: $GEMINI_OUTPUT_DIR or cwd)"New value: +"Where to write media recovered from a killed job (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)"
    • Changedgemini_image_edit3 fields changed
      • changedInput schema / properties / image_size / description
        Previous value: -"Output resolution (512 = 0.5K, Flash-only)"New value: +"Output resolution (512 = 0.5K, gemini-3.1-flash-image only)"
      • changedInput schema / properties / model / description
        Previous value: -"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."New value: +"Model id override (default: server default; see gemini_list_models). gemini-nano-banana-2.1 (Nano Banana 2.1, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."
      • changedInput schema / properties / output_dir / description
        Previous value: -"Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"New value: +"Directory to write images to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)"
    • Changedgemini_image_generate3 fields changed
      • changedInput schema / properties / image_size / description
        Previous value: -"Output resolution (512 = 0.5K, Flash-only)"New value: +"Output resolution (512 = 0.5K, gemini-3.1-flash-image only)"
      • changedInput schema / properties / model / description
        Previous value: -"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."New value: +"Model id override (default: server default; see gemini_list_models). gemini-nano-banana-2.1 (Nano Banana 2.1, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."
      • changedInput schema / properties / output_dir / description
        Previous value: -"Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"New value: +"Directory to write images to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)"
    • Changedgemini_image_set3 fields changed
      • changedInput schema / properties / image_size / description
        Previous value: -"Output resolution (512 = 0.5K, Flash-only)"New value: +"Output resolution (512 = 0.5K, gemini-3.1-flash-image only)"
      • changedInput schema / properties / model / description
        Previous value: -"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."New value: +"Model id override (default: server default; see gemini_list_models). gemini-nano-banana-2.1 (Nano Banana 2.1, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."
      • changedInput schema / properties / output_dir / description
        Previous value: -"Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"New value: +"Directory to write images to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)"
    • Changedgemini_interact3 fields changed
      • changedInput schema / properties / image_size / description
        Previous value: -"Output resolution (512 = 0.5K, Flash-only)"New value: +"Output resolution (512 = 0.5K, gemini-3.1-flash-image only)"
      • changedInput schema / properties / model / description
        Previous value: -"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."New value: +"Model id override (default: server default; see gemini_list_models). gemini-nano-banana-2.1 (Nano Banana 2.1, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."
      • changedInput schema / properties / output_dir / description
        Previous value: -"Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"New value: +"Directory to write images to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)"
    • Changedgemini_music_generate1 field changed
      • changedInput schema / properties / output_dir / description
        Previous value: -"Directory to write audio to (default: $GEMINI_OUTPUT_DIR or cwd)"New value: +"Directory to write audio to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)"
    • Changedgemini_video_generate1 field changed
      • changedInput schema / properties / output_dir / description
        Previous value: -"Directory to write the video to (default: $GEMINI_OUTPUT_DIR or cwd)"New value: +"Directory to write the video to (default: $GEMINI_OUTPUT_DIR or ~/Downloads/gemini-mcp)"
  2. 6 tool updatesv2.3.1
    • Changedgemini_image_edit1 field changed
      • changedInput schema / properties / images / description
        Previous value: -"Paths to input image file(s) (1 = edit, 2+ = compose)"New value: +"Paths to input image file(s) (1 = edit, 2+ = compose). Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set."
    • Changedgemini_image_generate1 field changed
      • changedInput schema / properties / images / description
        Previous value: -"Paths to reference input images (image-conditioned generation)"New value: +"Paths to reference input images (image-conditioned generation). Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set."
    • Changedgemini_image_set1 field changed
      • changedInput schema / properties / master_images / description
        Previous value: -"Reference image paths passed to the master generation call"New value: +"Reference image paths passed to the master generation call. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set."
    • Changedgemini_interact1 field changed
      • changedInput schema / properties / images / description
        Previous value: -"Paths to reference input images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit."New value: +"Paths to reference input images. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit."
    • Changedgemini_music_generate1 field changed
      • changedInput schema / properties / images / description
        Previous value: -"Optional reference image path(s) to condition the music"New value: +"Optional reference image path(s) to condition the music. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set."
    • Changedgemini_video_generate1 field changed
      • changedInput schema / properties / images / description
        Previous value: -"Reference image path(s) for image_to_video / reference_to_video"New value: +"Reference image path(s) for image_to_video / reference_to_video. Local paths must be inside GEMINI_REFERENCE_DIR (else GEMINI_UPLOAD_DIR) when set."
  3. 8 tool updatesv2.3.0
    • Changedgemini_delete_file2 fields changed
      • removedInput schema / properties / confirm
        Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}
      • addedInput schema / properties / confirmToken
        Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}
    • Changedgemini_image_edit2 fields changed
      • removedInput schema / properties / confirm
        Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}
      • addedInput schema / properties / confirmToken
        Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}
    • Changedgemini_image_generate2 fields changed
      • removedInput schema / properties / confirm
        Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}
      • addedInput schema / properties / confirmToken
        Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}
    • Changedgemini_image_set2 fields changed
      • removedInput schema / properties / confirm
        Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}
      • addedInput schema / properties / confirmToken
        Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}
    • Changedgemini_interact2 fields changed
      • removedInput schema / properties / confirm
        Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}
      • addedInput schema / properties / confirmToken
        Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}
    • Changedgemini_music_generate2 fields changed
      • removedInput schema / properties / confirm
        Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}
      • addedInput schema / properties / confirmToken
        Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}
    • Changedgemini_upload_file2 fields changed
      • removedInput schema / properties / confirm
        Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}
      • addedInput schema / properties / confirmToken
        Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}
    • Changedgemini_video_generate2 fields changed
      • removedInput schema / properties / confirm
        Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}
      • addedInput schema / properties / confirmToken
        Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}
  4. 12 tool updatesv2.0.0
    • Changedgemini_delete_file1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • Changedgemini_get_result1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • Changedgemini_healthcheck1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • Changedgemini_image_edit1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • Changedgemini_image_generate1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • Changedgemini_image_set1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • Changedgemini_interact1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • Changedgemini_list_files1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • Changedgemini_music_generate1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • Changedgemini_token_usage1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • Changedgemini_upload_file1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • Changedgemini_video_generate1 field changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  5. 6 tool updatesv1.14.0
    • Changedgemini_image_edit13 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."New value: +"Return a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait."
      • changedInput schema / properties / characters / description
        Previous value: -"Names of saved characters (see gemini_list_characters / gemini_save_character): each one's reference image and description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only."New value: +"Names of saved characters (gemini_list_characters): each one's reference image and description are attached automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only."
      • changedInput schema / properties / idempotency_key / description
        Previous value: -"Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge."New value: +"Repeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001)."
      • changedInput schema / properties / images_base64 / description
        Previous value: -"Input images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation"New value: +"Input images as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer images_url or images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to images_file_uris next time instead of re-sending the bytes."
      • changedInput schema / properties / images_file_uris / description
        Previous value: -"Input images by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving."New value: +"Input images as Files API references (\"files/<id>\" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving."
      • changedInput schema / properties / images_r2_keys / description
        Previous value: -"Input images by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket directly — no bytes in the conversation, no signed URL, no ~48h Files API expiry. Hosted connector only."New value: +"Input images by r2_key from this connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket — no bytes in the conversation, no ~48h expiry. Hosted connector only."
      • changedInput schema / properties / images_url / description
        Previous value: -"Input images as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*)."New value: +"Input images as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*."
      • changedInput schema / properties / inline / description
        Previous value: -"Return base64 images inline instead of writing to disk"New value: +"Return the image as an inline image block you can SEE, instead of a path (stdio) or link (hosted). The default costs nothing to carry and hands back a reference you can reuse; use this when you need to check the result yourself. On the hosted connector gemini_view_media does the same for an image you already have"
      • changedInput schema / properties / max_wait_ms / description
        Previous value: -"Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set."New value: +"Wait up to this many ms in-band, then hand back { job_id, status: \"running\" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set."
      • changedInput schema / properties / model / description
        Previous value: -"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding)."New value: +"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."
      • changedInput schema / properties / orientation / description
        Previous value: -"Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given."New value: +"Output shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — 3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given."
      • changedInput schema / properties / style / description
        Previous value: -"Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment — and reference image, if it has one — is applied to the request automatically. Hosted connector only."New value: +"Name of a saved style preset (gemini_list_styles): its prompt fragment, and reference image if it has one, are applied automatically. Hosted connector only."
      • changedInput schema / properties / timeout_ms / description
        Previous value: -"Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)"New value: +"Upstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)"
    • Changedgemini_image_generate13 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."New value: +"Return a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait."
      • changedInput schema / properties / characters / description
        Previous value: -"Names of saved characters (see gemini_list_characters / gemini_save_character): each one's reference image and description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only."New value: +"Names of saved characters (gemini_list_characters): each one's reference image and description are attached automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only."
      • changedInput schema / properties / idempotency_key / description
        Previous value: -"Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge."New value: +"Repeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001)."
      • changedInput schema / properties / images_base64 / description
        Previous value: -"Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation"New value: +"Reference images as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer images_url or images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to images_file_uris next time instead of re-sending the bytes."
      • changedInput schema / properties / images_file_uris / description
        Previous value: -"Reference images by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving."New value: +"Reference images as Files API references (\"files/<id>\" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving."
      • changedInput schema / properties / images_r2_keys / description
        Previous value: -"Reference images by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket directly — no bytes in the conversation, no signed URL, no ~48h Files API expiry. Hosted connector only."New value: +"Reference images by r2_key from this connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket — no bytes in the conversation, no ~48h expiry. Hosted connector only."
      • changedInput schema / properties / images_url / description
        Previous value: -"Reference images as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*)."New value: +"Reference images as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*."
      • changedInput schema / properties / inline / description
        Previous value: -"Return base64 images inline instead of writing to disk"New value: +"Return the image as an inline image block you can SEE, instead of a path (stdio) or link (hosted). The default costs nothing to carry and hands back a reference you can reuse; use this when you need to check the result yourself. On the hosted connector gemini_view_media does the same for an image you already have"
      • changedInput schema / properties / max_wait_ms / description
        Previous value: -"Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set."New value: +"Wait up to this many ms in-band, then hand back { job_id, status: \"running\" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set."
      • changedInput schema / properties / model / description
        Previous value: -"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding)."New value: +"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."
      • changedInput schema / properties / orientation / description
        Previous value: -"Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given."New value: +"Output shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — 3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given."
      • changedInput schema / properties / style / description
        Previous value: -"Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment — and reference image, if it has one — is applied to the request automatically. Hosted connector only."New value: +"Name of a saved style preset (gemini_list_styles): its prompt fragment, and reference image if it has one, are applied automatically. Hosted connector only."
      • changedInput schema / properties / timeout_ms / description
        Previous value: -"Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)"New value: +"Upstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)"
    • Changedgemini_image_set13 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."New value: +"Return a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait."
      • changedInput schema / properties / characters / description
        Previous value: -"Names of saved characters (see gemini_list_characters / gemini_save_character): each one's reference image and description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only."New value: +"Names of saved characters (gemini_list_characters): each one's reference image and description are attached automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only."
      • changedInput schema / properties / idempotency_key / description
        Previous value: -"Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge."New value: +"Repeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001)."
      • changedInput schema / properties / inline / description
        Previous value: -"Return base64 images inline instead of writing to disk"New value: +"Return the image as an inline image block you can SEE, instead of a path (stdio) or link (hosted). The default costs nothing to carry and hands back a reference you can reuse; use this when you need to check the result yourself. On the hosted connector gemini_view_media does the same for an image you already have"
      • changedInput schema / properties / master_images_base64 / description
        Previous value: -"Reference images as base64 strings or data URIs for master generation. Last resort: prefer master_images_url or master_images_file_uris, which keep image bytes out of the conversation"New value: +"Reference images for the master generation as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer master_images_url or master_images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to master_images_file_uris next time instead of re-sending the bytes."
      • changedInput schema / properties / master_images_file_uris / description
        Previous value: -"Reference images passed to the master AND to every scene call by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving."New value: +"Reference images passed to the master AND to every scene call as Files API references (\"files/<id>\" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving."
      • changedInput schema / properties / master_images_r2_keys / description
        Previous value: -"Reference images passed to the master AND to every scene call by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket directly — no bytes in the conversation, no signed URL, no ~48h Files API expiry. Hosted connector only."New value: +"Reference images passed to the master AND to every scene call by r2_key from this connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket — no bytes in the conversation, no ~48h expiry. Hosted connector only."
      • changedInput schema / properties / master_images_url / description
        Previous value: -"Reference images passed to the master AND to every scene call (fetched once) as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*)."New value: +"Reference images passed to the master AND to every scene call (fetched once) as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*."
      • changedInput schema / properties / max_wait_ms / description
        Previous value: -"Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set."New value: +"Wait up to this many ms in-band, then hand back { job_id, status: \"running\" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set."
      • changedInput schema / properties / model / description
        Previous value: -"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding)."New value: +"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."
      • changedInput schema / properties / orientation / description
        Previous value: -"Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given."New value: +"Output shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — 3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given."
      • changedInput schema / properties / style / description
        Previous value: -"Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment — and reference image, if it has one — is applied to the request automatically. Hosted connector only."New value: +"Name of a saved style preset (gemini_list_styles): its prompt fragment, and reference image if it has one, are applied automatically. Hosted connector only."
      • changedInput schema / properties / timeout_ms / description
        Previous value: -"Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)"New value: +"Upstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)"
    • Changedgemini_interact9 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."New value: +"Return a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait."
      • changedInput schema / properties / idempotency_key / description
        Previous value: -"Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge."New value: +"Repeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001)."
      • changedInput schema / properties / images_base64 / description
        Previous value: -"Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit."New value: +"Reference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer images_url or images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to images_file_uris next time instead of re-sending the bytes."
      • changedInput schema / properties / images_file_uris / description
        Previous value: -"Reference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving."New value: +"Reference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given as Files API references (\"files/<id>\" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving."
      • changedInput schema / properties / images_url / description
        Previous value: -"Reference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*)."New value: +"Reference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*."
      • changedInput schema / properties / max_wait_ms / description
        Previous value: -"Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set."New value: +"Wait up to this many ms in-band, then hand back { job_id, status: \"running\" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set."
      • changedInput schema / properties / model / description
        Previous value: -"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding)."New value: +"Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2, the default) is the generalist: fast, 4K, reliable text, strong multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding."
      • changedInput schema / properties / orientation / description
        Previous value: -"Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given."New value: +"Output shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — 3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given."
      • changedInput schema / properties / timeout_ms / description
        Previous value: -"Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)"New value: +"Upstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)"
    • Changedgemini_music_generate13 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."New value: +"Return a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait."
      • removedInput schema / properties / audio_format
        Removed value: -{
-  "description": "Output format (default mp3). wav is lyria-3-pro-preview-only.",
-  "enum": [
-    "mp3",
-    "wav"
-  ],
-  "type": "string"
-}
      • removedInput schema / properties / continue_last
        Removed value: -{
-  "description": "Continue from the most recent music interaction this server created (explicit previous_interaction_id wins)",
-  "type": "boolean"
-}
      • changedInput schema / properties / idempotency_key / description
        Previous value: -"Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge."New value: +"Repeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001)."
      • changedInput schema / properties / images_base64 / description
        Previous value: -"Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation"New value: +"Reference images as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer images_url or images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to images_file_uris next time instead of re-sending the bytes."
      • changedInput schema / properties / images_file_uris / description
        Previous value: -"Reference images by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving."New value: +"Reference images as Files API references (\"files/<id>\" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving."
      • changedInput schema / properties / images_url / description
        Previous value: -"Reference images as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*)."New value: +"Reference images as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*."
      • changedInput schema / properties / inline / description
        Previous value: -"Return base64 audio inline instead of writing to disk"New value: +"Return base64 audio inline instead of writing to disk. A 30s track is ~1.9MB of base64 — the default hands back a path instead"
      • changedInput schema / properties / max_wait_ms / description
        Previous value: -"Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set."New value: +"Wait up to this many ms in-band, then hand back { job_id, status: \"running\" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set."
      • changedInput schema / properties / model / description
        Previous value: -"Lyria model (default: lyria-3-clip-preview). Pro is longer-form and supports WAV."New value: +"Lyria model (default: lyria-3-clip-preview — 30s, $0.04). lyria-3.5 and lyria-3-pro-preview run minutes-long at $0.08."
      • changedInput schema / properties / model / enum
        Previous value: -[
-  "lyria-3-clip-preview",
-  "lyria-3-pro-preview"
-]New value: +[
+  "lyria-3-clip-preview",
+  "lyria-3.5",
+  "lyria-3-pro-preview"
+]
      • removedInput schema / properties / previous_interaction_id
        Removed value: -{
-  "description": "Interaction id to continue from",
-  "type": "string"
-}
      • changedInput schema / properties / timeout_ms / description
        Previous value: -"Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)"New value: +"Upstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)"
    • Changedgemini_video_generate12 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."New value: +"Return a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout (-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a request is open, so async is served there as a bounded wait."
      • changedInput schema / properties / idempotency_key / description
        Previous value: -"Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge."New value: +"Repeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001)."
      • changedInput schema / properties / images_base64 / description
        Previous value: -"Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation"New value: +"Reference images as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer images_url or images_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to images_file_uris next time instead of re-sending the bytes."
      • changedInput schema / properties / images_file_uris / description
        Previous value: -"Reference stills by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving."New value: +"Reference stills as Files API references (\"files/<id>\" or the full uri) from gemini_upload_file. Upload once and reuse across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving."
      • changedInput schema / properties / images_url / description
        Previous value: -"Reference stills as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*)."New value: +"Reference stills as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred over images_base64, which costs ~14k tokens per photo. Max 15MB each, Content-Type image/*."
      • changedInput schema / properties / max_wait_ms / description
        Previous value: -"Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set."New value: +"Wait up to this many ms in-band, then hand back { job_id, status: \"running\" } to poll with gemini_get_result (e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). Ignored when async is set."
      • changedInput schema / properties / model / description
        Previous value: -"Model id override (default: gemini-omni-flash-preview)"New value: +"Model id override (default: gemini-omni-1.1-flash)"
      • changedInput schema / properties / orientation / description
        Previous value: -"Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given."New value: +"Output shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — 3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given."
      • addedInput schema / properties / resolution
        Added value: +{
+  "description": "Output resolution (default 720p). Video is billed per output token, so 360p costs roughly a third of 720p — use it for drafts",
+  "enum": [
+    "360p",
+    "720p",
+    "1080p",
+    "4k"
+  ],
+  "type": "string"
+}
      • changedInput schema / properties / task / description
        Previous value: -"text_to_video (default), image_to_video / reference_to_video (need image input), or edit (needs previous_interaction_id)"New value: +"text_to_video (default), image_to_video / reference_to_video (need image input), or edit / extend (need previous_interaction_id)"
      • changedInput schema / properties / task / enum
        Previous value: -[
-  "text_to_video",
-  "image_to_video",
-  "reference_to_video",
-  "edit"
-]New value: +[
+  "text_to_video",
+  "image_to_video",
+  "reference_to_video",
+  "edit",
+  "extend"
+]
      • changedInput schema / properties / timeout_ms / description
        Previous value: -"Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)"New value: +"Upstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)"
  6. 1 tool updatev1.12.0
    • Addedgemini_healthcheck
  7. 1 tool updatev1.11.1
    • Addedgemini_token_usage
  8. 7 tool updatesv1.10.0
    • Changedgemini_get_result1 field changed
      • addedInput schema / properties / output_dir
        Added value: +{
+  "description": "Where to write media recovered from a killed job (default: $GEMINI_OUTPUT_DIR or cwd)",
+  "type": "string"
+}
    • Changedgemini_image_edit2 fields changed
      • changedInput schema / properties / aspect_ratio / description
        Previous value: -"Output aspect ratio"New value: +"Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given."
      • addedInput schema / properties / orientation
        Added value: +{
+  "description": "Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given.",
+  "enum": [
+    "landscape",
+    "portrait",
+    "square"
+  ],
+  "type": "string"
+}
    • Changedgemini_image_generate2 fields changed
      • changedInput schema / properties / aspect_ratio / description
        Previous value: -"Output aspect ratio"New value: +"Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given."
      • addedInput schema / properties / orientation
        Added value: +{
+  "description": "Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given.",
+  "enum": [
+    "landscape",
+    "portrait",
+    "square"
+  ],
+  "type": "string"
+}
    • Changedgemini_image_set2 fields changed
      • changedInput schema / properties / aspect_ratio / description
        Previous value: -"Output aspect ratio"New value: +"Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given."
      • addedInput schema / properties / orientation
        Added value: +{
+  "description": "Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given.",
+  "enum": [
+    "landscape",
+    "portrait",
+    "square"
+  ],
+  "type": "string"
+}
    • Changedgemini_interact2 fields changed
      • changedInput schema / properties / aspect_ratio / description
        Previous value: -"Output aspect ratio"New value: +"Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given."
      • addedInput schema / properties / orientation
        Added value: +{
+  "description": "Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given.",
+  "enum": [
+    "landscape",
+    "portrait",
+    "square"
+  ],
+  "type": "string"
+}
    • Changedgemini_music_generate1 field changed
      • addedInput schema / properties / background
        Added value: +{
+  "description": "Run the generation on Google's side and poll it, so a killed job can be recovered by gemini_get_result. Off by default — see gemini_video_generate",
+  "type": "boolean"
+}
    • Changedgemini_video_generate4 fields changed
      • changedInput schema / properties / aspect_ratio / description
        Previous value: -"Output aspect ratio (omni: 16:9 or 9:16)"New value: +"Exact output aspect ratio (omni: 16:9 or 9:16). `orientation` is the plain-language shorthand; this wins if both are given."
      • addedInput schema / properties / background
        Added value: +{
+  "description": "Run the generation on Google's side and poll it, so a killed job can be recovered by gemini_get_result. Trade-off: retrieving a backgrounded interaction is unreliable today (some become permanently unreadable), so the default is off",
+  "type": "boolean"
+}
      • addedInput schema / properties / delivery
        Added value: +{
+  "description": "How the clip comes back: \"uri\" (default — a Files API link the server downloads, no size ceiling) or \"inline\" (base64, capped ~4MB)",
+  "enum": [
+    "inline",
+    "uri"
+  ],
+  "type": "string"
+}
      • addedInput schema / properties / orientation
        Added value: +{
+  "description": "Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given.",
+  "enum": [
+    "landscape",
+    "portrait",
+    "square"
+  ],
+  "type": "string"
+}
  9. 6 tool updatesv1.7.0
    • Changedgemini_image_edit5 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion)."New value: +"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."
      • addedInput schema / properties / characters
        Added value: +{
+  "description": "Names of saved characters (see gemini_list_characters / gemini_save_character): each one's reference image and description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only.",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 8,
+  "type": "array"
+}
      • addedInput schema / properties / images_r2_keys
        Added value: +{
+  "description": "Input images by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket directly — no bytes in the conversation, no signed URL, no ~48h Files API expiry. Hosted connector only.",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "type": "array"
+}
      • addedInput schema / properties / max_wait_ms
        Added value: +{
+  "description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
+  "exclusiveMinimum": 0,
+  "maximum": 600000,
+  "type": "integer"
+}
      • addedInput schema / properties / style
        Added value: +{
+  "description": "Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment — and reference image, if it has one — is applied to the request automatically. Hosted connector only.",
+  "minLength": 1,
+  "type": "string"
+}
    • Changedgemini_image_generate5 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion)."New value: +"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."
      • addedInput schema / properties / characters
        Added value: +{
+  "description": "Names of saved characters (see gemini_list_characters / gemini_save_character): each one's reference image and description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only.",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 8,
+  "type": "array"
+}
      • addedInput schema / properties / images_r2_keys
        Added value: +{
+  "description": "Reference images by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket directly — no bytes in the conversation, no signed URL, no ~48h Files API expiry. Hosted connector only.",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "type": "array"
+}
      • addedInput schema / properties / max_wait_ms
        Added value: +{
+  "description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
+  "exclusiveMinimum": 0,
+  "maximum": 600000,
+  "type": "integer"
+}
      • addedInput schema / properties / style
        Added value: +{
+  "description": "Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment — and reference image, if it has one — is applied to the request automatically. Hosted connector only.",
+  "minLength": 1,
+  "type": "string"
+}
    • Changedgemini_image_set5 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion)."New value: +"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."
      • addedInput schema / properties / characters
        Added value: +{
+  "description": "Names of saved characters (see gemini_list_characters / gemini_save_character): each one's reference image and description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only.",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 8,
+  "type": "array"
+}
      • addedInput schema / properties / master_images_r2_keys
        Added value: +{
+  "description": "Reference images passed to the master AND to every scene call by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket directly — no bytes in the conversation, no signed URL, no ~48h Files API expiry. Hosted connector only.",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "type": "array"
+}
      • addedInput schema / properties / max_wait_ms
        Added value: +{
+  "description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
+  "exclusiveMinimum": 0,
+  "maximum": 600000,
+  "type": "integer"
+}
      • addedInput schema / properties / style
        Added value: +{
+  "description": "Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment — and reference image, if it has one — is applied to the request automatically. Hosted connector only.",
+  "minLength": 1,
+  "type": "string"
+}
    • Changedgemini_interact2 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion)."New value: +"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."
      • addedInput schema / properties / max_wait_ms
        Added value: +{
+  "description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
+  "exclusiveMinimum": 0,
+  "maximum": 600000,
+  "type": "integer"
+}
    • Changedgemini_music_generate2 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion)."New value: +"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."
      • addedInput schema / properties / max_wait_ms
        Added value: +{
+  "description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
+  "exclusiveMinimum": 0,
+  "maximum": 600000,
+  "type": "integer"
+}
    • Changedgemini_video_generate2 fields changed
      • changedInput schema / properties / async / description
        Previous value: -"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion)."New value: +"Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."
      • addedInput schema / properties / max_wait_ms
        Added value: +{
+  "description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
+  "exclusiveMinimum": 0,
+  "maximum": 600000,
+  "type": "integer"
+}
  10. 1 tool updatev1.4.0
    • Changedgemini_upload_file1 field changed
      • addedInput schema / properties / r2_key
        Added value: +{
+  "description": "Unavailable on this server (media is written to local disk) — pass the file path via `path` instead.",
+  "minLength": 1,
+  "type": "string"
+}
  11. 11 tool updatesv1.2.0
    • First observedgemini_delete_file
    • First observedgemini_get_result
    • First observedgemini_image_edit
    • First observedgemini_image_generate
    • First observedgemini_image_set
    • First observedgemini_interact
    • First observedgemini_list_files
    • First observedgemini_list_models
    • First observedgemini_music_generate
    • First observedgemini_upload_file
    • First observedgemini_video_generate
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 13 tools

Disambiguation4/5

The four image-centric tools (gemini_image_generate, gemini_image_edit, gemini_image_set, gemini_interact) genuinely overlap, but the descriptions explicitly route between them (use interact for iterative work, edit for one-off edits, set for batches). Video and music tools are clearly distinct modalities, and get_result/token_usage/healthcheck have no ambiguity. Only the generate-vs-interact boundary remains a mild judgment call.

Naming Consistency4/5

All names share the gemini_ prefix and snake_case, so the set reads predictably. However, ordering is mixed: media tools use resource_action (image_generate, video_generate) while file tools use action_resource (upload_file, list_files), and a few tools are noun-only (healthcheck, token_usage). Minor deviation, not confusing.

Tool Count5/5

13 tools is well within the sweet spot and each earns its place: generation per modality (image/video/music), file lifecycle, async result retrieval, cost tracking, and healthcheck. No tool appears redundant or filler. The surface is appropriately scoped for a generative-media API server.

Completeness4/5

Coverage is strong: generation, iterative refinement, file upload/list/delete, async job retrieval, and token/cost accounting form a full lifecycle with no obvious dead ends. Minor gaps exist — gemini_list_models appears image-only (no video/music model listing) and there is no explicit job-cancel tool, though agents can work around both.

Maintenance

ActivityActive
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers