Skip to main content
Glama
plemio

Nano Banana MCP Server

by plemio
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Nano Banana MCP Server 🍌

A production-ready Model Context Protocol (MCP) server that provides AI-powered image generation capabilities through Google's Gemini models with intelligent model selection.

⭐ NEW: Nano Banana 2 — Gemini 3.1 Flash Image! 🍌🚀

Nano Banana 2 (gemini-3.1-flash-image-preview) is now the default model — delivering Pro-level quality at Flash speed:

  • 🍌 Flash Speed + 4K Quality: Up to 3840px at Gemini 2.5 Flash latency

  • 🌐 Google Search Grounding: Real-world knowledge for factually accurate images

  • 🎯 Subject Consistency: Up to 5 characters and 14 objects per scene

  • ✍️ Precision Text Rendering: Crystal-clear text placement in images

  • 🏆 Gemini 3 Pro Image still available for maximum reasoning depth

Related MCP server: PixelForge MCP

✨ Features

  • 🎨 Multi-Model AI Image Generation: Three Gemini models with intelligent automatic selection

  • 🍌 Gemini 3.1 Flash Image (NB2): Default model — 4K resolution at Flash speed with grounding

  • 🏆 Gemini 3 Pro Image: Maximum reasoning depth for the most complex compositions

  • ⚡ Gemini 2.5 Flash Image: Legacy Flash model for high-volume rapid prototyping

  • 🤖 Smart Model Selection: Automatically routes to NB2 or Pro based on your prompt

  • 📐 Aspect Ratio Control ⭐ NEW: Specify output dimensions (1:1, 16:9, 9:16, 21:9, and more)

  • 📋 Smart Templates: Pre-built prompt templates for photography, design, and editing

  • 📁 File Management: Upload and manage files via Gemini Files API

  • 🔍 Resource Discovery: Browse templates and file metadata through MCP resources

  • 🛡️ Production Ready: Comprehensive error handling, logging, and validation

  • ⚡ High Performance: Optimized architecture with intelligent caching

🚀 Quick Start

Prerequisites

  1. Google Gemini API Key - Get one free here

  2. Python 3.11+ (for development only)

Installation

Option 1: From MCP Registry (Recommended) This server is available in the Model Context Protocol Registry. Search for "nanobanana" or use the MCP name below with your MCP client.

mcp-name: io.github.zhongweili/nanobanana-mcp-server

Option 2: Using uvx

uvx nanobanana-mcp-server@latest

Option 3: Using pip

pip install nanobanana-mcp-server

🔧 Configuration

Authentication Methods

Nano Banana supports two authentication methods via NANOBANANA_AUTH_METHOD:

  1. API Key (api_key): Uses GEMINI_API_KEY. Best for local development and simple deployments.

  2. Vertex AI ADC (vertex_ai): Uses Google Cloud Application Default Credentials. Best for production on Google Cloud (Cloud Run, GKE, GCE).

  3. Automatic (auto): Defaults to API Key if present, otherwise tries Vertex AI.

1. API Key Authentication (Default)

Set GEMINI_API_KEY environment variable.

2. Vertex AI Authentication (Google Cloud)

Required environment variables:

  • NANOBANANA_AUTH_METHOD=vertex_ai (or auto)

  • GCP_PROJECT_ID=your-project-id

  • GCP_REGION=global (default; required for Gemini 3 Pro Image and NB2. Use us-central1 only for the legacy 2.5 Flash Image model.)

Prerequisites:

  • Enable Vertex AI API: gcloud services enable aiplatform.googleapis.com

  • Grant IAM Role: roles/aiplatform.user to the service account.

Claude Desktop

Option 1: Using Published Server (Recommended)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Option 2: Using Local Source (Development)

If you are running from source code, point to your local installation:

{
  "mcpServers": {
    "nanobanana-local": {
      "command": "uv",
      "args": ["run", "python", "-m", "nanobanana_mcp_server.server"],
      "cwd": "/absolute/path/to/nanobanana-mcp-server",
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Option 3: Using Vertex AI (ADC)

To authenticate with Google Cloud Application Default Credentials (instead of an API Key):

{
  "mcpServers": {
    "nanobanana-adc": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "NANOBANANA_AUTH_METHOD": "vertex_ai",
        "GCP_PROJECT_ID": "your-project-id",
        "GCP_REGION": "global"
      }
    }
  }
}

Configuration file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code (VS Code Extension)

Install and configure in VS Code:

  1. Install the Claude Code extension

  2. Open Command Palette (Cmd/Ctrl + Shift + P)

  3. Run "Claude Code: Add MCP Server"

  4. Configure:

    {
  "name": "nanobanana",
  "command": "uvx",
  "args": ["nanobanana-mcp-server@latest"],
  "env": {
    "GEMINI_API_KEY": "your-gemini-api-key-here"
  }
}

Cursor

Add to Cursor's MCP configuration:

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml (global) or .codex/config.toml (project-scoped):

[mcp_servers.nanobanana]
command = "uvx"
args = ["nanobanana-mcp-server@latest"]

[mcp_servers.nanobanana.env]
GEMINI_API_KEY = "your-gemini-api-key-here"

Or add via the CLI:

codex mcp add

Codex supports both the CLI and VSCode extension using the same config.toml. Once added, Codex can call generate_image, edit_image, and upload_file tools directly in your coding sessions.

Note: The Codex config file is shared by the CLI and the IDE extension. A TOML syntax error will break both simultaneously, so validate your edits carefully.

Continue.dev (VS Code/JetBrains)

Add to your config.json:

{
  "mcpServers": [
    {
      "name": "nanobanana",
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  ]
}

Open WebUI

Configure in Open WebUI settings:

{
  "mcp_servers": {
    "nanobanana": {
      "command": ["uvx", "nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Gemini CLI / Generic MCP Client

# Set environment variable
export GEMINI_API_KEY="your-gemini-api-key-here"

# Run server in stdio mode
uvx nanobanana-mcp-server@latest

# Or with pip installation
python -m nanobanana_mcp_server.server

🤖 Model Selection

Nano Banana supports three Gemini models with intelligent automatic selection:

🍌 NB2 — Nano Banana 2 (Gemini 3.1 Flash Image) ⭐ DEFAULT

Flash speed with Pro-level quality — the best of both worlds

  • Quality: Production-ready 4K output

  • Resolution: Up to 4K (3840px)

  • Speed: ~2-4 seconds per image (Flash-class latency)

  • Special Features:

    • 🌐 Google Search Grounding: Real-world knowledge for factually accurate images

    • 🎯 Subject Consistency: Up to 5 characters and 14 objects per scene

    • ✍️ Precision Text Rendering: Clear, well-placed text in images

  • Best for: Almost everything — production assets, marketing, photography, text overlays

  • model_tier: "nb2" (or "auto" — NB2 is the auto default)

🏆 Pro Model — Nano Banana Pro (Gemini 3 Pro Image)

Maximum reasoning depth for the most demanding compositions

  • Quality: Highest available

  • Resolution: Up to 4K (3840px)

  • Speed: ~5-8 seconds per image

  • Special Features:

    • 🧠 Advanced Reasoning: Configurable thinking levels (LOW/HIGH)

    • 🌐 Google Search Grounding: Real-world knowledge integration

    • 📐 Media Resolution Control: Fine-tune vision processing detail

  • Best for: Complex narrative scenes, intricate compositions, maximum reasoning required

  • model_tier: "pro"

⚡ Flash Model (Gemini 2.5 Flash Image)

Legacy model for high-volume rapid iteration

  • Speed: Very fast (2-3 seconds)

  • Resolution: Up to 1024px

  • Best for: High-volume generation, quick drafts where 4K is not needed

  • model_tier: "flash"

🤖 Automatic Selection (Recommended)

By default, the server uses AUTO mode which routes to NB2 unless Pro's deeper reasoning is clearly needed:

Pro Model Selected When:

  • Strong quality keywords: "4K", "professional", "production", "high-res", "HD"

  • High thinking level requested: thinking_level="HIGH"

  • Multi-image conditioning with multiple input images

NB2 Model Selected When (default):

  • Standard requests, everyday image generation

  • Speed keywords: "quick", "draft", "sketch", "rapid"

  • High-volume batch generation (n > 2)

Usage Examples

# Automatic selection (recommended) — routes to NB2 by default
"A cat sitting on a windowsill"             # → NB2 (default)
"Quick sketch of a cat"                     # → NB2 (speed keyword, NB2 is fast enough)
"Professional 4K product photo"             # → Pro (strong quality keywords)

# Explicit NB2 selection
generate_image(
    prompt="Product photo on white background",
    model_tier="nb2",              # Nano Banana 2 (Flash speed + 4K)
    resolution="4k",
    enable_grounding=True
)

# Leverage Nano Banana Pro for complex reasoning
generate_image(
    prompt="Cinematic scene: three characters in a tense standoff at dusk",
    model_tier="pro",              # Pro for deep reasoning
    resolution="4k",
    thinking_level="HIGH",         # Enhanced reasoning
    enable_grounding=True
)

# Legacy Flash for high-volume drafts
generate_image(
    prompt="Simple icon",
    model_tier="flash"             # Fast 1024px generation
)

# Control aspect ratio for different formats ⭐ NEW!
generate_image(
    prompt="Cinematic landscape at sunset",
    aspect_ratio="21:9"            # Ultra-wide cinematic format
)

generate_image(
    prompt="Instagram post about coffee",
    aspect_ratio="1:1"             # Square format for social media
)

generate_image(
    prompt="YouTube thumbnail design",
    aspect_ratio="16:9"            # Standard video format
)

generate_image(
    prompt="Mobile wallpaper of mountain vista",
    aspect_ratio="9:16"            # Portrait format for phones
)

📐 Aspect Ratio Control

Control the output image dimensions with the aspect_ratio parameter:

Supported Aspect Ratios:

  • 1:1 - Square (Instagram, profile pictures)

  • 4:3 - Classic photo format

  • 3:4 - Portrait orientation

  • 16:9 - Widescreen (YouTube thumbnails, presentations)

  • 9:16 - Mobile portrait (phone wallpapers, stories)

  • 21:9 - Ultra-wide cinematic

  • 2:3, 3:2, 4:5, 5:4 - Various photo formats

# Examples for different use cases
generate_image(
    prompt="Product showcase for e-commerce",
    aspect_ratio="3:4",    # Portrait format, good for product pages
    model_tier="pro"
)

generate_image(
    prompt="Social media banner for Facebook",
    aspect_ratio="16:9"    # Landscape banner format
)

Note: Aspect ratio works with both Flash and Pro models. For best results with specific aspect ratios at high resolution, use the Pro model with resolution="4k".

📁 Output Path Control ⭐ NEW!

Control where generated images are saved with the output_path parameter:

Three modes of operation:

  1. Specific file path - Save to an exact file location:

generate_image(
    prompt="A beautiful sunset",
    output_path="/path/to/sunset.png"  # Exact file location
)

  1. Directory path - Use auto-generated filename in a specific directory:

generate_image(
    prompt="Product photo",
    output_path="/path/to/products/"  # Trailing slash indicates directory
)

  1. Default location - Uses IMAGE_OUTPUT_DIR or ~/nanobanana-images:

generate_image(
    prompt="Random image"
    # output_path defaults to None
)

Multiple images (n > 1): When generating multiple images with a file path, images are automatically numbered:

  • First image: /path/to/image.png

  • Second image: /path/to/image_2.png

  • Third image: /path/to/image_3.png

Precedence Rules:

  1. output_path parameter (if provided) - highest priority

  2. IMAGE_OUTPUT_DIR environment variable

  3. ~/nanobanana-images (default fallback)

# Save to specific location with Pro model
generate_image(
    prompt="Professional headshot",
    model_tier="pro",
    output_path="/Users/me/photos/headshot.png"
)

# Save multiple images to a directory
generate_image(
    prompt="Product variations",
    n=4,
    output_path="/path/to/products/"  # Each gets unique filename
)

⚙️ Environment Variables

Configuration options:

# Authentication (Required)
# Method 1: API Key
GEMINI_API_KEY=your-gemini-api-key-here

# Method 2: Vertex AI (Google Cloud)
NANOBANANA_AUTH_METHOD=vertex_ai
GCP_PROJECT_ID=your-project-id
GCP_REGION=global  # Required for gemini-3-pro-image-preview and NB2; use "us-central1" only for legacy 2.5 Flash Image

# Model Selection (optional)
NANOBANANA_MODEL=auto  # Options: flash, nb2, pro, auto (default: auto → nb2)

# Optional
IMAGE_OUTPUT_DIR=/path/to/image/directory  # Default: ~/nanobanana-images
GEMINI_BASE_URL=https://custom-api.example.com  # Custom API endpoint (for proxies/gateways)
LOG_LEVEL=INFO                             # DEBUG, INFO, WARNING, ERROR
LOG_FORMAT=standard                        # standard, json, detailed

🐛 Troubleshooting

Common Issues

"GEMINI_API_KEY not set"

  • Add your API key to the MCP server configuration in your client

  • Get a free API key at Google AI Studio

"Server failed to start"

  • Ensure you're using the latest version: uvx nanobanana-mcp-server@latest

  • Check that your client supports MCP (Claude Desktop 0.10.0+)

"Permission denied" errors

  • The server creates images in ~/nanobanana-images by default

  • Ensure write permissions to your home directory

Development Setup

For local development:

# Clone repository
git clone https://github.com/zhongweili/nanobanana-mcp-server.git
cd nanobanana-mcp-server

# Install with uv
uv sync

# Set environment
export GEMINI_API_KEY=your-api-key-here

# Run locally
uv run python -m nanobanana_mcp_server.server

📄 License

MIT License - see LICENSE for details.

🆘 Support

Available Tools

4 tools
generate_imageGenerate or edit images (Multi-Model: Flash & Pro)A
Read-only

Generate new images or edit existing images using natural language instructions.

Supports multiple input modes:

  1. Pure generation: Just provide a prompt to create new images

  2. Editing / fusion: pass input_image_paths — the first image is the one being edited (its scene and subjects are preserved), the rest are references to blend in. Up to 14 images with the 'nb2' and 'pro' tiers, 3 with 'flash'.

  3. File ID editing: Edit previously uploaded images using Files API ID

Automatically detects mode based on parameters or can be explicitly controlled. Input images are read from the local filesystem to avoid massive token usage. Returns both MCP image content blocks and structured JSON with metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
nNoRequested image count (model may return fewer).
modeNoOperation mode: 'generate' for new image creation, 'edit' for modifying existing images. Auto-detected based on input parameters if not specified.auto
promptYesClear, detailed image prompt. Include subject, composition, action, location, style, and any text to render. Use the aspect_ratio parameter to pin a specific canvas shape when needed.
file_idNoFiles API file ID to use as input/edit source (e.g., 'files/abc123'). If provided, this takes precedence over input_image_path_* parameters for the primary input.
model_tierNoModel tier: 'flash' (legacy, 1024px), 'nb2' (4K at Flash speed, default), 'pro' (max quality, 4K), or 'auto' (smart selection). Default: 'auto' - automatically selects nb2 or pro based on prompt.auto
resolutionNoOutput resolution: 'high', '4k', '2k', '1k'. 4K and 2K available with 'nb2' and 'pro' models. Default: 'high'.high
output_pathNoOutput path for generated image(s). If a file path with extension (e.g., '/path/image.png'), saves directly to that path. If a directory path (e.g., '/path/to/dir/'), uses default filename in that directory. If None, uses IMAGE_OUTPUT_DIR environment variable or ~/nanobanana-images.
aspect_ratioNoOptional output aspect ratio (e.g., '16:9'). Standard: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9. Extreme (nb2 only): 4:1, 1:4, 8:1, 1:8.
thinking_levelNoReasoning depth hint: 'low' (faster), 'high' (better quality). Applied to the 'nb2' model; 'high' also biases auto-selection toward Pro. Default: None (auto).
negative_promptNoThings to avoid (style, objects, text).
enable_groundingNoEnable Google Search grounding for factual accuracy (NB2 and Pro models). Useful for real-world subjects. Default: true.
input_image_pathsNoInput images, in order. The FIRST one is the image being edited (its scene, subjects and faces are preserved); the following ones are references whose subjects, characters or styles get brought into it. Up to 14 with the 'nb2' and 'pro' tiers, 3 with 'flash'. Pass a single path to plainly edit one image, none to generate from scratch.
return_full_imageNoReturn full-resolution images in MCP response instead of thumbnails. Warning: full images can be large (3-7MB each for 4K). Default: uses RETURN_FULL_IMAGE env var, or false if not set.
input_image_path_1NoLegacy single-slot form of input_image_paths[0].
input_image_path_2NoLegacy single-slot form of input_image_paths[1].
input_image_path_3NoLegacy single-slot form of input_image_paths[2].
system_instructionNoOptional system tone/style guidance.

TDQS

A3.9/5.0
Behavior1/5

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

The annotations declare readOnlyHint=true, but the description describes creating and editing image files, saving to output paths, and returning generated content — clearly a write-capable operation. This is a direct contradiction with the annotation. The description does add useful behavioral context (local filesystem reads, full-image size warnings, auto mode detection), but the contradiction forces a score of 1 per the evaluation rules.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

The description is well-structured and front-loaded: it states the core capability first, then enumerates modes, filesystem behavior, and return types in a scannable numbered/bulleted format. Despite the tool's complexity, every sentence contributes meaningful guidance without excessive redundancy with the schema.

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 17-parameter tool with no output schema, the description covers the essential aspects: mode selection, editing semantics, tier limits, local filesystem reads, and return format (MCP content blocks plus structured JSON). It does not detail the shape of the structured metadata JSON or error conditions, but it provides enough contextual breadth for correct invocation in most cases.

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?

Even though schema coverage is 100%, the description adds substantial semantic meaning beyond the schema: the first input image is the primary edit target while the rest are reference images, file_id takes precedence over input_image_path_* parameters, tier limits are clarified, and output_path behavior is summarized. This materially helps an agent choose and populate parameters correctly.

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 precise verb+resource statement: 'Generate new images or edit existing images using natural language instructions.' It further distinguishes the tool by enumerating three distinct input modes (pure generation, editing/fusion, file ID editing), making it easy to separate from siblings like upload_file and show_output_stats.

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 gives strong context for when to use each mode: pure generation vs editing via input_image_paths, file ID editing, and explicit vs auto-detected mode. It also explains tier-specific limits (14 images with nb2/pro, 3 with flash). It does not explicitly name sibling upload_file as the companion tool for obtaining a Files API ID, but 'File ID editing: Edit previously uploaded images using Files API ID' strongly implies that workflow.

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

maintenanceMaintenance and cleanup operationsA
Read-only

Perform maintenance operations following workflows.md patterns.

Available operations:

  • cleanup_expired: Remove expired Files API entries from database

  • cleanup_local: Clean old local files based on age/LRU

  • check_quota: Check Files API storage usage vs. ~20GB budget

  • database_hygiene: Clean up database inconsistencies

  • full_cleanup: Run all cleanup operations in sequence

ParametersJSON Schema
NameRequiredDescriptionDefault
dry_runNoIf true, only report what would be done without making changes
operationYesMaintenance operation to perform: 'cleanup_expired', 'cleanup_local', 'check_quota', 'database_hygiene', 'full_cleanup'
keep_countNoFor local cleanup: minimum number of recent files to keep
max_age_hoursNoFor local cleanup: maximum age in hours (default: 168 = 1 week)

TDQS

A3.6/5.0
Behavior1/5

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

Description directly contradicts readOnlyHint=true. Operations like 'Remove expired Files API entries from database' and 'Clean old local files' imply mutation, yet annotations declare the tool read-only. Also lacks disclosure of side effects, permissions, or reversibility.

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?

Very concise: one introductory line plus a clean bullet list of operations. Front-loads the tool purpose and uses scannable format with no fluff.

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

Completeness2/5

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

Complex tool with 4 parameters and 5 operation variants, yet the description lacks guidance on parameter applicability (e.g., keep_count and max_age_hours only for cleanup_local) and return behavior. The readOnlyHint contradiction further reduces completeness.

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 provides 100% parameter descriptions, but the tool description adds semantic detail for the operation parameter by explaining what each operation does (e.g., 'check_quota: Check Files API storage usage vs. ~20GB budget'). This goes beyond the schema's repetitive value list.

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?

Purpose is explicit: maintenance and cleanup operations. The description lists five distinct operations with concrete effects (e.g., 'Remove expired Files API entries from database'), distinguishing it from unrelated siblings like generate_image and upload_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?

Although no explicit 'use when' statement is given, the operation list clearly implies the tool is for maintenance/cleanup tasks, and the sibling tools are unrelated (image generation, upload, stats). Missing explicit exclusions or alternative routing, but context is adequate.

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

show_output_statsShow output directory statsA
Read-only

Show statistics about the output directory and recently generated images.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

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

The annotation readOnlyHint: true already establishes that the tool is read-only, and the description does not contradict this. There are no side effects or destructive actions mentioned. However, the description does not describe the output format, but given the read-only nature, transparency is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

The description is a single, concise sentence that conveys the essential purpose without any unnecessary words or 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?

Given the simplicity of the tool (no parameters, read-only, straightforward stats), the description is complete enough for an agent to invoke it correctly without needing additional context or output schema details.

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?

There are no parameters, so schema coverage is perfect and there is nothing to explain. The description provides no parameter details, but none are needed.

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's function: showing statistics about the output directory and recently generated images. It is distinct from sibling tools like generate_image and upload_file, which are creation/upload operations.

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?

There is no explicit guidance on when to use this tool vs. alternatives, but its purpose is self-evident as a stats-only tool. It lacks explicit exclusions or alternative references, so the usage context is implied rather than stated.

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

upload_fileUpload file to Gemini Files APIA

Upload a local file through the Gemini Files API and return its URI & metadata. Useful when the image is larger than 20MB or reused across prompts.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesServer-accessible file path to upload to Gemini Files API.
display_nameNoOptional display name for the uploaded file.

TDQS

A4/5.0
Behavior3/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 most of the disclosure burden. It adds useful context: the upload destination (Gemini Files API), the return value (URI & metadata), and the 20MB size threshold. However, it does not disclose side effects of an upload operation — persistence, storage quota, retention/deletion, or whether files can be cleaned up. Given the mutation nature, this is a notable gap but not severe.

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 with zero waste. The first sentence front-loads the action and outcome; the second provides a concrete usage criterion. Every clause 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 simple 2-parameter tool with 100% schema coverage, the description covers the essentials: action, return value, and when to use it. What is missing is minor but real — there is no output schema, so the agent only knows the return is 'URI & metadata' without structure, and no failure modes or file-type constraints are mentioned. Still, an agent can correctly invoke this tool with the information given.

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%, so both parameters (path, display_name) are already fully documented. Per baseline, a 3 is appropriate. The description's mention of 'return its URI & metadata' and the 20MB threshold adds context about tool behavior but does not add parameter-level meaning beyond what the schema already provides.

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+resource+outcome: 'Upload a local file through the Gemini Files API and return its URI & metadata.' This is unambiguous and easily distinguished from the sibling tools (generate_image, show_output_stats, maintenance), none of which involve file upload. The title and description align without redundancy.

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 gives an explicit conditional for when to use the tool: 'Useful when the image is larger than 20MB or reused across prompts.' This gives the agent a concrete decision rule. However, it does not explicitly name an alternative or state when NOT to use it — it only implies that smaller/single-use images would use a different path.

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. 4 tool updatesv0.1.0
    • First observedgenerate_image
    • First observedmaintenance
    • First observedshow_output_stats
    • First observedupload_file
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct role: generation/editing, file upload, output statistics, and maintenance operations. There is no meaningful overlap between them, and the descriptions make the boundaries obvious.

Naming Consistency4/5

Three tools follow a consistent verb_noun pattern: generate_image, upload_file, show_output_stats. The 'maintenance' tool breaks this pattern by using a bare noun instead of something like run_maintenance or perform_maintenance.

Tool Count5/5

Four tools is well-scoped for an image generation server: one core generation tool, one upload helper, one stats view, and one maintenance tool. Each tool earns its place without unnecessary bloat or redundancy.

Completeness4/5

The core image generation and editing workflow is covered, along with upload support for large files and basic output monitoring. Minor gaps exist around explicit file deletion or listing of uploaded Files API entries, but these are workable through maintenance and stats tools.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers