gemini-mcp

gemini_upload_file

Upload an image, video, or audio file once to get a reusable file_uri, then attach that reference to later generations without resending file bytes.

Instructions

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).

Input Schema

TableJSON Schema

Name	Required	Description
`url`	No	Public https URL the SERVER downloads and uploads (image/video/audio, up to 100MB). No bytes pass through the conversation.
`path`	No	Path to a local file (absolute, or resolved against $GEMINI_INPUT_DIR). Confirm-gated like every other local-file input.
`r2_key`	No	Unavailable on this server (media is written to local disk) — pass the file path via `path` instead.
`mime_type`	No	Override the detected MIME type (sniffed from the bytes / taken from the server response otherwise)
`data_base64`	No	Raw base64 or a data: URI. Last resort — this is the one form that costs model context (~14k tokens for a modest JPEG).
`confirmToken`	No	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.
`display_name`	No	Human-readable name recorded against the upload

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.3.0Sep 25, 2026

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"
+}

Changed1 schema field changedv2.0.0Sep 19, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedv1.4.0Jul 30, 2026

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"
+}

First observedv1.2.0Jul 29, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations are minimal (readOnlyHint=false, openWorldHint=true), so the description carries the behavioral burden. It discloses the one-time upload semantics, ~48h expiry, that the file_uri is reusable across calls, context-cost impact of base64, server-side download behavior, and confirmation-token rules.

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 dense and front-loaded with the core purpose. The keyword list and confirmation details are somewhat verbose, yet they carry practical value for an agent. Minor redundancy (e.g., image/reference photo/picture/screenshot) keeps it from a 5.

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 tool with 7 parameters, no output schema, and a nontrivial confirmation flow, the description is remarkably complete. It covers input modes, return value shape, expiration, context-cost tradeoffs, and the confirmToken lifecycle, leaving no critical call-time ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds significant meaning: exactly one source must be provided, url is server-downloaded, data_base64 is a costly last resort, r2_key is unusable, and confirmToken has strict two-phase usage rules. This goes well beyond the raw 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 states a specific verb ('Upload') and a clear resource ('the Gemini Files API'), and explains the output is a reusable file_uri for later generations. This clearly differentiates it from sibling generation/list/delete 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?

It explicitly tells the agent to use this instead of pasting base64, explains when to use url vs path vs data_base64, and details the two-step confirmation behavior. This provides actionable routing guidance beyond just saying what the tool does.

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

Deploy Server

gemini_upload_file

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools