Enables AI-powered image generation, editing, and restoration using Google's Gemini 2.5 Flash image model for creating images from text prompts, modifying existing images with natural language instructions, generating icons, patterns, visual stories, and technical diagrams.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Nano Banana create a logo for a coffee shop called 'Brew Haven' with warm colors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A professional MCP (Model Context Protocol) extension for any MCP-compatible client (including Gemini CLI and Codex CLI), for generating and manipulating images. It uses the google/gemini-2.5-flash-image model by default, and is pre-configured to connect to OpenRouter. You can point it at any provider that hosts the model by adjusting the MODEL_* environment variables.
🎨 Text-to-Image Generation: Create stunning images from descriptive prompts
✏️ Image Editing: Modify existing images with natural language instructions
🔧 Image Restoration: Restore and enhance old or damaged photos
📁 Smart File Management: User-friendly filenames with automatic duplicate prevention
Related MCP server: Gemini Flash Image MCP Server
MCP-compatible CLI installed and configured (e.g., Gemini CLI, Codex CLI)
Node.js 18+ and npm
API Key: You will need an API key from OpenRouter or another provider that hosts the google/gemini-2.5-flash-image model.
By default, the extension talks to OpenRouter. Optional overrides are useful when targeting other providers that host the model:
MODEL_BASE_URL – alternate provider endpoint (default: https://openrouter.ai/api/v1)
MODEL_ID – override model id (default: google/gemini-2.5-flash-image)
MODEL_REFERER / MODEL_TITLE – analytics headers for providers that require them
MODEL_GENERATE_PATH – alternate generation endpoint path (default: /responses)
If you are using OpenRouter, refer to their authentication guide for generating API keys. For other providers, consult their documentation.
For most users, installing via npx or your CLI's extension manager is the easiest method.
Gemini CLI:
When you install the extension, you will be prompted to enter your API key.
gemini extensions install https://github.com/Aeven-AI/mcp-nanobananaCodex CLI:
codex mcp add nanobanana --env MODEL_API_KEY="YOUR_API_KEY_HERE" -- npx -y @aeven/nanobanana-mcp@latestOpencode CLI:
Run opencode config edit (or open your opencode.jsonc settings file manually).
Register the server with an entry similar to:
{
"mcp": {
"nanobanana": {
"type": "local",
"command": ["npx", "-y", "@aeven/nanobanana-mcp@latest"],
"enabled": true,
"environment": {
"MODEL_API_KEY": "{env:MODEL_API_KEY}"
}
}
}
}Save the file and restart Opencode so it picks up the new MCP server.
Claude Code:
Open Claude Code and navigate to Settings → Model Context Protocol → Add Server.
Set the command to npx and the arguments to -y and @aeven/nanobanana-mcp@latest.
Add an environment variable MODEL_API_KEY pointing at your provider key.
Save the server configuration and restart Claude Code (or reload the window) to connect.
If you have cloned this repository to work on the code, you can register your local version.
1. Install server dependencies (once per clone):
npm run install-deps2. Build the server:
npm run build3. Register with your CLI:
For Codex CLI:
codex mcp add nanobanana --env MODEL_API_KEY="YOUR_API_KEY_HERE" -- node mcp-server/dist/index.js
This extension requires a MODEL_API_KEY to authenticate with your model provider (e.g., OpenRouter). Here’s how to configure it for different clients:
You will be prompted to enter your API key automatically during the installation process.
The codex mcp add command has a dedicated --env flag to handle this for you. The command provided in the "Installation" section already includes this and is the recommended way to install.
For other clients, or if you prefer to manage the key manually, you can set the MODEL_API_KEY as an environment variable in your shell's profile file (e.g., ~/.zshrc, ~/.bashrc, or ~/.profile).
Add the following line to the end of the file:
export MODEL_API_KEY="YOUR_API_KEY_HERE"Restart your terminal for the change to take effect.
Restart your MCP CLI (Gemini CLI, Codex CLI, etc.). The following commands will be available:
/generate - Single or multiple image generation with style/variation options
/edit - Image editing
/restore - Image restoration
/icon - Generate app icons, favicons, and UI elements in multiple sizes
/pattern - Generate seamless patterns and textures for backgrounds
/story - Generate sequential images that tell a visual story or process
/diagram - Generate technical diagrams, flowcharts, and architectural mockups
/nanobanana - Natural language interface
The extension provides multiple command options for different use cases:
Note: Examples below use Gemini CLI slash commands. In Codex CLI and other MCP clients, call the same MCP tools (
generate_image,edit_image, etc.) using the syntax your client provides.
Generate Images:
# Single image
/generate "a watercolor painting of a fox in a snowy forest"
# Multiple variations with preview
/generate "sunset over mountains" --count=3 --previewEdit Images:
/edit my_photo.png "add sunglasses to the person"
/edit portrait.jpg "change background to a beach scene" --previewRestore Images:
/restore old_family_photo.jpg "remove scratches and improve clarity"Generate Icons:
/icon "coffee cup logo" --sizes="64,128,256" --type="app-icon" --previewCreate Patterns:
/pattern "geometric triangles" --type="seamless" --style="geometric" --previewGenerate Stories:
/story "a seed growing into a tree" --steps=4 --type="process" --previewCreate Diagrams:
/diagram "user login process" --type="flowchart" --style="professional" --previewOpen-ended prompts:
/nanobanana create a logo for my tech startup
/nanobanana I need 5 different versions of a cat illustration in various art styles
/nanobanana fix the lighting in sunset.jpg and make it more vibrantThe /generate command supports advanced options for creating multiple variations with different styles and parameters.
<details> <summary>Generation Options</summary>
--count=N - Number of variations (1-8, default: 1)
--styles="style1,style2" - Comma-separated artistic styles
--variations="var1,var2" - Specific variation types
--format=grid|separate - Output format (default: separate)
--seed=123 - Seed for reproducible variations
--preview - Automatically open generated images in default viewer
</details>
<details> <summary>Available Styles</summary>
photorealistic - Photographic quality images
watercolor - Watercolor painting style
oil-painting - Oil painting technique
sketch - Hand-drawn sketch style
pixel-art - Retro pixel art style
anime - Anime/manga art style
vintage - Vintage/retro aesthetic
modern - Contemporary/modern style
abstract - Abstract art style
minimalist - Clean, minimal design
</details>
<details> <summary>Available Variations</summary>
lighting - Different lighting conditions (dramatic, soft)
angle - Various viewing angles (above, close-up)
color-palette - Different color schemes (warm, cool)
composition - Different layouts (centered, rule-of-thirds)
mood - Various emotional tones (cheerful, dramatic)
season - Different seasons (spring, winter)
time-of-day - Different times (sunrise, sunset)
</details>
Style Variations:
/generate "mountain landscape" --styles="watercolor,oil-painting,sketch,photorealistic"
# Creates the same mountain scene in 4 different artistic stylesMultiple Variations:
/generate "cozy coffee shop" --variations="lighting,mood" --count=4
# Generates: dramatic lighting, soft lighting, cheerful mood, dramatic mood versionsThe /icon command specializes in creating app icons, favicons, and UI elements with proper sizing and formatting.
<details> <summary>Icon Options</summary>
--sizes="16,32,64" - Array of icon sizes in pixels (common: 16, 32, 64, 128, 256, 512, 1024)
--type="app-icon|favicon|ui-element" - Icon type (default: app-icon)
--style="flat|skeuomorphic|minimal|modern" - Visual style (default: modern)
--format="png|jpeg" - Output format (default: png)
--background="transparent|white|black|color" - Background type (default: transparent)
--corners="rounded|sharp" - Corner style for app icons (default: rounded)
</details>
# Complete app icon set
/icon "productivity app with checklist" --sizes="64,128,256,512" --corners="rounded"
# Website favicon package
/icon "mountain logo" --type="favicon" --sizes="16,32,64" --format="png"The /pattern command creates seamless patterns and textures perfect for backgrounds and design elements.
<details> <summary>Pattern Options</summary>
--size="256x256" - Pattern tile size (common: 128x128, 256x256, 512x512)
--type="seamless|texture|wallpaper" - Pattern type (default: seamless)
--style="geometric|organic|abstract|floral|tech" - Pattern style (default: abstract)
--density="sparse|medium|dense" - Element density (default: medium)
--colors="mono|duotone|colorful" - Color scheme (default: colorful)
--repeat="tile|mirror" - Tiling method for seamless patterns (default: tile)
</details>
# Website background pattern
/pattern "subtle geometric hexagons" --type="seamless" --colors="duotone" --density="sparse"
# Material texture
/pattern "brushed metal surface" --type="texture" --style="tech" --colors="mono"The /story command generates sequential images that tell a visual story or demonstrate a step-by-step process.
<details> <summary>Story Options</summary>
--steps=N - Number of sequential images (2-8, default: 4)
--type="story|process|tutorial|timeline" - Sequence type (default: story)
--style="consistent|evolving" - Visual consistency across frames (default: consistent)
--layout="separate|grid|comic" - Output layout (default: separate)
--transition="smooth|dramatic|fade" - Transition style between steps (default: smooth)
--format="storyboard|individual" - Output format (default: individual)
</details>
# Product development process
/story "idea to launched product" --steps=5 --type="process" --style="consistent"
# Educational tutorial
/story "git workflow tutorial" --steps=6 --type="tutorial" --layout="comic"The /diagram command generates professional technical diagrams, flowcharts, and architectural mockups from simple text descriptions.
<details> <summary>Diagram Options</summary>
--type="flowchart|architecture|network|database|wireframe|mindmap|sequence" - Diagram type (default: flowchart)
--style="professional|clean|hand-drawn|technical" - Visual style (default: professional)
--layout="horizontal|vertical|hierarchical|circular" - Layout orientation (default: hierarchical)
--complexity="simple|detailed|comprehensive" - Level of detail (default: detailed)
--colors="mono|accent|categorical" - Color scheme (default: accent)
--annotations="minimal|detailed" - Label and annotation level (default: detailed)
</details>
flowchart: Process flows, decision trees, workflows
architecture: System architecture, microservices, infrastructure
network: Network topology, server configurations
database: Database schemas, entity relationships
wireframe: UI/UX mockups, page layouts
mindmap: Concept maps, idea hierarchies
sequence: Sequence diagrams, API interactions
# Development workflow
/diagram "CI/CD pipeline with testing stages" --type="flowchart" --complexity="detailed"
# System design
/diagram "chat application architecture" --type="architecture" --style="technical"Images are saved with user-friendly names based on your prompts:
"sunset over mountains" → sunset_over_mountains.png
"abstract art piece" → abstract_art_piece.png
If a file already exists, a counter is automatically added:
sunset_over_mountains.png
sunset_over_mountains_1.png
sunset_over_mountains_2.png
For editing/restoration, the extension searches for input images in:
Current working directory
./images/ subdirectory
./input/ subdirectory
./nanobanana-output/ subdirectory
~/Downloads/
~/Desktop/
Generated images are saved to ./nanobanana-output/ which is created automatically.
# Build the MCP server
npm run build
# Install MCP server dependencies
npm run install-deps
# Development mode with file watching
npm run dev# Build MCP server directly
cd mcp-server && npm run build
# Start server standalone (for testing)
cd mcp-server && npm start
# Development mode with TypeScript watching
cd mcp-server && npm run dev# Run the full suite (build + unit + integration)
cd mcp-server && npm test
# Only unit tests (FileHandler, ImageGenerator with mocked fetch)
cd mcp-server && npm run test:unit
# Only integration tests (in-memory MCP handshake with a stub image generator)
cd mcp-server && npm run test:integrationThe default integration test uses an in-memory transport and a stubbed image generator, so it runs offline and does not require an API key.
To exercise the real OpenRouter workflow end-to-end, run the manual script after setting MODEL_API_KEY:
cd mcp-server
MODEL_API_KEY="sk-..." node ./tests/manual/openrouter.integration.jsGenerated assets are placed under mcp-server/nanobanana-output/ for manual inspection.
Run the automated smoke test to make sure the published npm binary boots correctly:
npm run verify:npmThis command packs the project, installs the tarball in a temporary directory, launches npx nanobanana-mcp, and confirms the stdio server banner appears. It is safe to interrupt after the success message.
index.ts: MCP server using @modelcontextprotocol/sdk for professional protocol handling
imageGenerator.ts: Handles all OpenRouter API interactions and response processing
fileHandler.ts: Manages file I/O, smart filename generation, and file searching
types.ts: Shared TypeScript interfaces for type safety
The extension uses the official Model Context Protocol (MCP) SDK for robust client-server communication:
Protocol: JSON-RPC over stdio
SDK: @modelcontextprotocol/sdk
Tools: generate_image, edit_image, restore_image
Model: google/gemini-2.5-flash-image (configurable via environment variable)
Transport: Direct HTTP requests (OpenRouter by default; set MODEL_BASE_URL to target other providers hosting the model)
Response Handling: Base64 decoding with graceful fallbacks for missing image data
Output Size: All images are returned at 1024×1024 resolution (model maximum)
Comprehensive error messages with debugging information
Graceful fallbacks for API response parsing
File validation and search path reporting
"Command not recognized": Verify the MCP server is registered for your CLI (e.g., ~/.gemini/extensions/nanobanana-extension/ for Gemini CLI, Codex CLI configuration for Codex users) and restart the client
"No API key found": Ensure you have entered the API key correctly when prompted during installation, or that the MODEL_API_KEY environment variable is set correctly if you are not using Gemini CLI.
"Build failed": Ensure Node.js 18+ is installed and run npm run install-deps && npm run build.
"Image not found": Check that input files are in one of the searched directories (see File Search Locations above)
npx install errors: Stale directories in ~/.npm/_npx can cause install failures. Remove the cache with rm -rf ~/.npm/_npx/* and rerun the install command.
The MCP server includes detailed debug logging that appears in your CLI console (Gemini CLI, Codex CLI, etc.) to help diagnose issues.
License: Apache License 2.0
Security: Security Policy
Fork the repository
Create a feature branch
Make your changes in the modular architecture
Run npm run build to ensure compilation
Test with your MCP CLI (Gemini CLI, Codex CLI, etc.)
Submit a pull request
Edit an existing image based on a text prompt
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The text prompt describing the edits to make | |
| file | Yes | The filename of the input image to edit | |
| preview | No | Automatically open generated images in default viewer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'edit' without specifying whether it overwrites the original, preserves dimensions, or what output is produced. This leaves significant ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence. It front-loads the key action and resource, with no unnecessary words. While it could be more informative, it is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters and no output schema, the description is too sparse. It does not explain return values, error conditions, or the scope of edits, leaving the agent with incomplete information for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is complete (100%), so baseline is 3. The description adds no extra meaning beyond the parameter names and schema descriptions, but it does not detract either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'edit' on an 'existing image' and specifies the means 'based on a text prompt'. It differentiates from siblings like generate_image (creates new) and restore_image (restores).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an existing image and want to modify it via a prompt, but it provides no explicit when-to-use or when-not-to-use guidance compared to alternatives like generate_image or restore_image.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate technical diagrams, flowcharts, and architectural mockups
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Description of the diagram content and structure | |
| type | No | Type of diagram to generate | flowchart |
| style | No | Visual style of the diagram | professional |
| layout | No | Layout orientation | hierarchical |
| complexity | No | Level of detail in the diagram | detailed |
| colors | No | Color scheme | accent |
| annotations | No | Label and annotation level | detailed |
| preview | No | Automatically open generated images in default viewer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'generate' with no details on side effects, limitations, or behavior. Lacks disclosure of any important behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very short (7 words) but not structured. While concise, it could add more value without becoming verbose. Minimalism here sacrifices clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 8 parameters, no output schema, no annotations. Description is insufficient to fully guide an agent; lacks information on return values, error cases, or behavioral nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for all 8 parameters. Description adds no additional meaning beyond stating the tool's purpose; it does not explain parameter contexts or enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action 'generate' and resource types (technical diagrams, flowcharts, architectural mockups). Differentiates from siblings like generate_image (general images) and generate_icon (icons).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. The enum for 'type' implies intended diagram types, but no when-not-to-use or sibling comparisons are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate app icons, favicons, and UI elements in multiple sizes and formats
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Description of the icon or UI element to generate | |
| sizes | No | Array of icon sizes in pixels (16, 32, 64, 128, 256, 512, 1024) | |
| type | No | Type of icon to generate | app-icon |
| style | No | Visual style of the icon | modern |
| format | No | Output format | png |
| background | No | Background type: transparent, white, black, or color name | transparent |
| corners | No | Corner style for app icons | rounded |
| preview | No | Automatically open generated images in default viewer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It fails to mention key traits such as generation speed, determinism, output format handling, or any side effects. The 'preview' parameter behavior is hinted but not clearly described for the overall tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence that captures the core functionality. However, it could be slightly more detailed without becoming verbose, e.g., listing supported formats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 8 parameters and no output schema, the description does not explain return values or how multiple generated images are delivered. It also lacks behavior on errors or prerequisites, leaving significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented. The description adds high-level context but does not enhance individual parameter meaning. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: generating specific icon types (app icons, favicons, UI elements) with explicit mention of multiple sizes and formats. It effectively differentiates from sibling tools like generate_image (general images) and generate_diagram.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context (icons and UI elements) but lacks explicit guidance on when to use this tool versus alternatives like generate_image. It does not include when-not-to-use or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate single or multiple images from text prompts with style and variation options
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The text prompt describing the image to generate | |
| outputCount | No | Number of variations to generate (1-8, default: 1) | |
| styles | No | Array of artistic styles: photorealistic, watercolor, oil-painting, sketch, pixel-art, anime, vintage, modern, abstract, minimalist | |
| variations | No | Array of variation types: lighting, angle, color-palette, composition, mood, season, time-of-day | |
| format | No | Output format: separate files or single grid image | separate |
| seed | No | Seed for reproducible variations | |
| preview | No | Automatically open generated images in default viewer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It does not mention return format, side effects, authentication, or rate limits, leaving significant gaps for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 12 words with no redundancy. Every word adds value, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema, the description is too brief. It does not explain output format behavior, return values, or how to use the preview option, leaving the agent under-informed about key aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema, only loosely grouping parameters under 'style and variation options'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates single or multiple images from text prompts, specifying the key feature of style and variation options. This distinguishes it from sibling tools like edit_image (editing) and generate_diagram (diagrams), providing a clear purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks any guidance on when to use or when not to use this tool. It does not mention alternatives or conditions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate seamless patterns and textures for backgrounds and design elements
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Description of the pattern or texture to generate | |
| size | No | Pattern tile size (e.g., "256x256", "512x512") | 256x256 |
| type | No | Type of pattern to generate | seamless |
| style | No | Pattern style | abstract |
| density | No | Element density in the pattern | medium |
| colors | No | Color scheme | colorful |
| repeat | No | Tiling method for seamless patterns | tile |
| preview | No | Automatically open generated images in default viewer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states generation, omitting side effects, return format, or any restrictions. Bare minimum info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 13 words, no fluff. Front-loaded with action and object. Could include a hint about capabilities while remaining concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters and no output schema, the description is too minimal. It lacks information about output format, usage patterns, or behavior. Incomplete for a complex generative tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains each parameter. The description adds no extra meaning beyond the schema, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('generate') and nouns ('seamless patterns and textures', 'backgrounds and design elements'), clearly distinguishing it from siblings like generate_image (general images) and generate_icon (icons).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for patterns/textures but does not explicitly state when to use it over siblings or provide exclusion criteria. No guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a sequence of related images that tell a visual story or show a process
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Description of the story or process to visualize | |
| steps | No | Number of sequential images to generate (2-8) | |
| type | No | Type of sequence to generate | story |
| style | No | Visual consistency across frames | consistent |
| layout | No | Output layout format | separate |
| transition | No | Transition style between steps | smooth |
| format | No | Output format | individual |
| preview | No | Automatically open generated images in default viewer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits but only states the high-level purpose. It does not mention whether the tool is read-only, destructive, or any side effects. No information about performance, limits, or security implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff. Every word serves a purpose, making it highly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters and no output schema, yet the description is minimal. It does not explain what the tool returns, how the sequence is delivered, or any important behaviors like default layouts or transitions. Significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for each parameter. No extra context or constraints are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Generate a sequence of related images that tell a visual story or show a process', using a specific verb and resource. It distinguishes this tool from siblings like generate_image (single image) by emphasizing the sequential nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like generate_image or generate_diagram. The description does not mention when-not-to-use or provide any context for choosing among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A simple hello world tool
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name to say hello to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided and description omits behavioral traits like side effects, idempotency, or output format. Agent lacks essential context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but too vague; it sacrifices substance for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and description fails to explain tool's return value or behavior, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers parameter 'name' with description. Tool description adds no extra meaning, achieving baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'A simple hello world tool' is vague; it does not specify the action or return value. It contrasts with image tools but lacks precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings. While siblings are image-related, no explicit when-to-use or when-not-to-use logic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore or enhance an existing image
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The text prompt describing the restoration to perform | |
| file | Yes | The filename of the input image to restore | |
| preview | No | Automatically open generated images in default viewer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It does not mention side effects (e.g., whether the original file is overwritten), authentication needs, or any other behavioral implications beyond the vague action of restoration/enhancement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but overly terse. It front-loads the purpose but fails to include necessary details, making it less useful for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and the description is minimal, the agent has almost no information about return values, formats, or post-conditions. The description is insufficient for a tool with three parameters and no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (prompt, file, preview) have descriptions in the input schema, providing high coverage. The tool description adds no additional meaning beyond the schema, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'restores or enhances an existing image', which is clear but vague. It does not differentiate from the sibling tool 'edit_image', which likely performs similar modifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'edit_image' or 'generate_image'. No conditions, prerequisites, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
edit_imagegenerate_diagramgenerate_icongenerate_imagegenerate_patterngenerate_storyhellorestore_imageScored across 8 tools
Each tool targets a distinct purpose: editing, restoration, and various types of image generation (general, icons, diagrams, patterns, stories). The 'hello' tool is a trivial standalone, but it does not create confusion with the others.
Most tools follow a verb_noun pattern in snake_case (e.g., generate_image, edit_image, restore_image). The 'hello' tool breaks this pattern, but it is a single outlier among eight tools.
With 8 tools covering generation, editing, and restoration, the count is well-suited for the domain. It is neither too sparse nor too heavy for an image-focused server.
The set covers core image operations: generating various types, editing, and restoring. Minor gaps like image deletion or listing are present but not critical for the intended use case.
Generate logos, social posts, app screenshots, comic panels & visual-novel assets from prompts.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Upload, organize, search, and transform images, videos, and files with AI-powered tools.
Generate and edit images and create short videos inside Claude. Prepaid credits, no subscription.
