Ein Model Context Protocol (MCP)-Server für intelligente Multi-Provider-Bildgenerierung.
1. API-Schlüssel besorgen (mindestens einen):
Provider | Schlüssel erhalten unter | Umgebungsvariable |
OpenAI |
| |
Google Gemini |
|
Wenn Sie beide Schlüssel besitzen, erhalten Sie die besten Ergebnisse — der Server wählt automatisch den richtigen Provider für jeden Prompt aus. Mit nur einem Schlüssel funktionieren Prompts, die für den anderen Provider besser geeignet wären, zwar weiterhin, aber Sie erhalten einen Hinweis auf den Fallback.
2. Zum MCP-Client hinzufügen (einen auswählen):
claude mcp add -s user imagen \
-e OPENAI_API_KEY=sk-... \
-e GEMINI_API_KEY=AI... \
-- npx -y imagen-mcpÜberprüfen Sie, ob er registriert ist:
claude mcp listReferenz: Claude Code MCP-Dokumentation
Bearbeiten Sie die Konfigurationsdatei:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"imagen": {
"command": "npx",
"args": ["-y", "imagen-mcp"],
"env": {
"OPENAI_API_KEY": "sk-...",
"GEMINI_API_KEY": "AI..."
}
}
}
}Starten Sie Claude Desktop nach der Bearbeitung neu (Cmd+Q, dann erneut öffnen).
Referenz: Claude Desktop MCP-Dokumentation
Option A — CLI-Befehl:
codex mcp add imagen -- npx -y imagen-mcpOption B — Bearbeiten Sie ~/.codex/config.toml direkt:
[mcp_servers.imagen]
command = "npx"
args = ["-y", "imagen-mcp"]
[mcp_servers.imagen.env]
OPENAI_API_KEY = "sk-..."
GEMINI_API_KEY = "AI..."Referenz: Codex MCP-Dokumentation
Bearbeiten Sie ~/.gemini/settings.json:
{
"mcpServers": {
"imagen": {
"command": "npx",
"args": ["-y", "imagen-mcp"],
"env": {
"OPENAI_API_KEY": "sk-...",
"GEMINI_API_KEY": "AI..."
}
}
}
}Referenz: Gemini CLI MCP-Dokumentation
Einstellung | Wert |
Befehl |
|
Argumente |
|
Umgebung |
|
3. Bild generieren — fragen Sie Ihren KI-Assistenten:
"Erstelle ein professionelles Porträtfoto mit Studiobeleuchtung"
Das ist alles. Der Server wählt automatisch den besten Provider aus.
Related MCP server: ImageGen MCP Server
Automatische Provider-Auswahl — analysiert Prompts, um den besten Provider zu wählen
Multi-Provider-Unterstützung — OpenAI GPT-Image-1 und Google Gemini
Referenzbilder — bis zu 14 Bilder für Charakter-/Stilkonsistenz (Gemini)
Echtzeit-Daten — Google-Suche-Grounding für aktuelle Informationen (Gemini)
Konversationelle Verfeinerung — Bilder iterativ mit Kontext verfeinern
Hohe Auflösung — bis zu 4K-Ausgabe (Gemini)
Fallback-Hinweise — klare Warnungen, wenn ein Prompt von einem Provider profitieren würde, den Sie nicht konfiguriert haben
Der Server analysiert Ihren Prompt und leitet ihn an den besten Provider weiter:
"Create a menu card for an Italian restaurant" -> OpenAI (text rendering)
"Professional headshot with studio lighting" -> Gemini (photorealism)
"Infographic about climate change" -> OpenAI (diagram + text)
"Product shot of perfume on marble" -> Gemini (product photography)Was passiert, wenn der beste Provider nicht konfiguriert ist? Der Server greift auf den Provider zurück, den Sie konfiguriert haben, und informiert Sie:
Provider-Fallback: Gemini wäre für diesen Prompt besser geeignet (fotorealistischer Inhalt), ist aber nicht konfiguriert. Verwende stattdessen OpenAI. Setzen Sie
GEMINI_API_KEYfür bessere Ergebnisse.
Sie können die automatische Auswahl jederzeit mit dem Parameter provider überschreiben:
generate_image(prompt="...", provider="openai")
generate_image(prompt="...", provider="gemini")Funktion | OpenAI GPT-Image-1 | Gemini Nano Banana Pro |
Text-Rendering | Exzellent | Gut |
Fotorealismus | Gut | Exzellent |
Geschwindigkeit | ~60s | ~15s |
Max. Auflösung | 1536x1024 | 4K |
Größen | 3 Optionen | 1K, 2K, 4K |
Seitenverhältnisse | 3 | 10 |
Referenzbilder | Nein | Ja (bis zu 14) |
Echtzeit-Daten | Nein | Ja (Google-Suche) |
Verwenden Sie OpenAI für: textlastige Bilder, Menüs, Infografiken, Comics, Diagramme
Verwenden Sie Gemini für: Porträts, Produktfotografie, 4K-Ausgabe, Referenzbilder
Tool | Beschreibung |
| Haupt-Tool mit automatischer Provider-Auswahl |
| Mehrstufige Verfeinerung mit Dialog und Historie |
| Aktive Konversationen und deren Historie auflisten |
| Verfügbare Provider und Funktionen anzeigen |
| Verfügbare Gemini-Bildmodelle abfragen |
Bilder werden standardmäßig unter ~/Downloads/images/{provider}/ gespeichert (Unterverzeichnisse openai/ oder gemini/).
Anpassung mit:
# Save to a specific directory (auto-generated filename)
generate_image(prompt="...", output_path="~/Desktop/logos/")
# Save to a specific file
generate_image(prompt="...", output_path="~/Desktop/logos/my-logo.png")Setzen Sie OUTPUT_DIR, um das Basisverzeichnis global zu ändern. Protokolle werden unter {OUTPUT_DIR}/logs/ gespeichert.
# High resolution
generate_image(prompt="...", size="4K")
# Specific model
generate_image(prompt="...", gemini_model="gemini-2.0-flash-exp-image-generation")
# Reference images for style/character consistency (base64 encoded)
generate_image(prompt="...", reference_images=["base64..."])
# Real-time data via Google Search
generate_image(prompt="Current weather in NYC", enable_google_search=True)Modell-ID | Beschreibung |
| Dediziertes Bildgenerierungsmodell (Standard) |
| GPT-5 mit Bildgenerierungsfunktionen |
| Neuestes Reasoning-Modell (Konversations-Orchestrierung) |
Modell-ID | Beschreibung |
| Nano Banana Pro - höchste Qualität (Standard) |
| Schnelles experimentelles Modell |
| Alternatives Bildmodell |
flowchart TB
subgraph Clients["MCP Clients"]
CD[Claude Desktop]
CC[Claude Code CLI]
GC[Gemini CLI]
CX[Codex CLI]
end
subgraph Server["imagen-mcp Server"]
MCP[MCP Protocol Layer]
subgraph Tools["MCP Tools"]
GI[generate_image]
CI[conversational_image]
LP[list_providers]
LM[list_gemini_models]
end
subgraph Core["Core Components"]
PS[Provider Selector]
PR[Provider Registry]
end
subgraph Providers["Image Providers"]
OAI[OpenAI Provider<br/>GPT-Image-1]
GEM[Gemini Provider<br/>Nano Banana Pro]
end
end
subgraph APIs["External APIs"]
OAPI[OpenAI API]
GAPI[Google Gemini API]
end
subgraph Storage["Local Storage"]
DL[~/Downloads/images/]
end
CD & CC & GC & CX --> MCP
MCP --> Tools
GI & CI --> PS
PS --> PR
PR --> OAI & GEM
OAI --> OAPI
GEM --> GAPI
OAI & GEM --> DLVariable | Beschreibung | Erforderlich |
| OpenAI API-Schlüssel | Mindestens ein API-Schlüssel |
| Google Gemini API-Schlüssel | ist erforderlich |
| Alias für | |
| Basisverzeichnis für gespeicherte Bilder | Nein (Standard: |
| Standard-Provider erzwingen | Nein (Standard: |
| Standard-Bildgröße für OpenAI | Nein (Standard: |
| Standard-Bildgröße für Gemini | Nein (Standard: |
| Google-Suche-Grounding aktivieren | Nein (Standard: |
| Überschreibung des Log-Verzeichnisses | Nein |
| Log-Level (DEBUG, INFO, etc.) | Nein |
| Vollständige Prompts protokollieren | Nein (Standard: |
"No providers available"
Sie benötigen mindestens einen API-Schlüssel. Setzen Sie OPENAI_API_KEY oder GEMINI_API_KEY in Ihrer MCP-Client-Konfiguration (siehe Schnellstart oben).
Bilder werden generiert, aber die Qualität für Porträts/Produkte ist nicht gut
Wahrscheinlich fehlt GEMINI_API_KEY. Der Server ist auf OpenAI ausgewichen und hat eine Warnung angezeigt. Fügen Sie einen Gemini-Schlüssel für bessere fotorealistische Ergebnisse hinzu.
Bilder werden generiert, aber der Text sieht schlecht aus
Wahrscheinlich fehlt OPENAI_API_KEY. Fügen Sie einen OpenAI-Schlüssel für besseres Text-Rendering hinzu.
"npx: command not found" Installieren Sie Node.js (enthält npx): nodejs.org
Wo werden meine Bilder gespeichert?
Standard: ~/Downloads/images/openai/ oder ~/Downloads/images/gemini/. Überprüfen Sie die Tool-Ausgabe auf den genauen Pfad. Setzen Sie OUTPUT_DIR, um dies zu ändern.
Wie überprüfe ich, welche Provider aktiv sind?
Verwenden Sie das Tool list_providers oder führen Sie aus:
python3 -c "from src.providers import get_provider_registry; print(get_provider_registry().list_providers())"# Clone and install
git clone https://github.com/michaeljabbour/imagen-mcp.git
cd imagen-mcp
pip install -r requirements.txt
# Run tests
pip install pytest pytest-asyncio
pytest tests/ -v
# Verify server loads
python3 -c "from src.server import mcp; print('Server loads')"
# Check Claude Desktop logs (macOS)
tail -f ~/Library/Logs/Claude/mcp-server-imagen.logimagen-mcp/
├── src/
│ ├── server.py # MCP entry point
│ ├── config/
│ │ ├── constants.py # Provider constants
│ │ └── settings.py # Environment configuration
│ ├── providers/
│ │ ├── base.py # Abstract provider interface
│ │ ├── openai_provider.py # OpenAI implementation
│ │ ├── gemini_provider.py # Gemini implementation
│ │ ├── selector.py # Auto-selection logic
│ │ └── registry.py # Provider factory
│ └── models/
│ └── input_models.py # Pydantic input models
├── tests/
│ ├── test_selector.py # Provider selection tests
│ ├── test_providers.py # Provider unit tests
│ └── test_server.py # Server integration tests
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI
├── run.sh # Wrapper script for MCP clients
├── requirements.txt
├── CLAUDE.md
└── README.mdmcp>=1.16.0
fastmcp>=2.12.5
pydantic>=2.12.3
httpx>=0.24.0
google-genai>=1.52.0
pillow>=10.4.0MIT
Generate images conversationally with iterative refinement.
USE THIS TOOL when:
User gives a vague/incomplete prompt that needs refinement
User wants iterative refinement across multiple messages
User explicitly asks for guidance or suggestions
Dialogue Modes:
"quick": 1-2 questions, fast path
"guided": 3-5 questions, balanced (DEFAULT)
"explorer": Deep exploration with 6+ questions
"skip": Direct generation, no dialogue
Provider Selection: Same auto-selection logic as generate_image. Provider is locked for the duration of a conversation (cannot switch mid-conversation).
Usage Pattern:
Initial: "A cozy coffee shop" → System asks refinement questions
User answers questions
Image generated with refined prompt
Refine: "Add more plants" (with same conversation_id)
Continue refining as needed
Args: params: Conversational image parameters including prompt and dialogue options.
Returns: Either dialogue questions or generated image with metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false (mutation) and destructiveHint=false. The description adds behavioral traits beyond annotations: provider locking across conversations (cannot switch mid-conversation), dialogue modes impact on interaction depth, and the usage pattern for continuation via conversation_id. These details are useful but not exhaustive (e.g., no mention of output_path creation).
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 well-structured with clear sections (purpose, when-to-use, dialogue modes, provider selection, usage pattern, returns). It is concise and front-loaded with essential information. The usage pattern could be slightly shorter, but overall it efficiently conveys the tool's workflow.
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's complexity (conversational image generation with many parameters and multi-turn refinement), the description covers core concepts, when to use, dialogue modes, provider locking, and continuation pattern. The output schema exists, so return details are not needed. It lacks discussion of some advanced parameters (e.g., reference_images, input_image_file_id), but schema handles those. It is sufficient for an AI agent to select and invoke.
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 0% (main description does not detail individual parameters), but the schema itself has thorough descriptions for all parameters. The description adds some context for 'dialogue_mode' (enum values) but largely repeats schema info. Baseline is 3 due to high schema coverage, and no significant extra meaning is added.
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: 'Generate images conversationally with iterative refinement.' It specifies the resource (images) and the verb (generate with conversation), and distinguishes from sibling tools like 'generate_image' by emphasizing conversation and iterative refinement. The dialogue modes further clarify the scope.
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 explicitly lists 'USE THIS TOOL when:' conditions, such as vague prompts, iterative refinement, or user asking for guidance. It does not directly state when not to use it (e.g., when prompt is clear and no refinement needed), but the context effectively implies when alternatives like 'generate_image' are better. It also covers dialogue modes and provider selection, offering solid guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing image using OpenAI gpt-image-2's /images/edits endpoint.
This is the right tool for:
Image-to-image refinement (OpenAI's answer to reference images)
Inpainting with a mask (paint over regions while preserving the rest)
Sequential/cumulative edits that preserve unchanged pixels
Brand-accurate modifications to existing images
Key features of gpt-image-2 editing:
input_fidelity='high' (default) keeps unchanged pixels constant —
critical for multi-step refinement where each edit should build on
the last without drift.
Full control over quality, background, output_format, and compression.
Supports optional PNG mask (transparent pixels are the edit region).
Typical workflow:
Generate or obtain a base image (path on disk)
Call edit_image with prompt='change the sky to sunset'
Take the output path, call edit_image again with next instruction
Repeat — each step preserves pixels outside the described change
Args: params: Edit parameters including prompt, image_path, and options.
Returns: Formatted response with edited image path and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits: uses /images/edits endpoint, default high input fidelity to preserve pixels, mask support, sequential workflow. Annotations (readOnlyHint=false, destructiveHint=false) are consistent; description adds context about mutable but non-destructive behavior.
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?
Well-structured with bullet points and sections (key features, typical workflow). No fluff; each sentence adds valuable information. Appropriate length given tool complexity.
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?
Covers use cases, workflow, and key features comprehensively. With an output schema present, return value explanation is unnecessary. The description is self-contained for correct 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?
Although the tool has a single 'params' object with 0% description coverage at top level, the nested schema thoroughly documents all parameters. The description adds value by explaining key parameters like input_fidelity and mask_path in context, aiding interpretation beyond schema alone.
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 it edits existing images using OpenAI's gpt-image-2 endpoint. It lists specific use cases (image-to-image refinement, inpainting, sequential edits) that distinguish it from sibling tools like generate_image or conversational_image, which focus on generation or conversation.
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?
Explicit guidance under 'This is the right tool for:' with bullet points covering refinement, inpainting, sequential edits, and brand modifications. It implies not for from-scratch generation (handled by generate_image). The workflow description further clarifies when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate the cost of generating an image without generating it.
Runs the same provider auto-selection as generate_image (unless you
pin a provider) and looks up an approximate price from a local pricing
table. Useful for comparing providers/qualities before committing.
The figure is a ballpark — real cost depends on live provider pricing and, for OpenAI, actual image output tokens.
Args: params: Prompt plus optional provider/quality/size/n.
Returns: A formatted cost estimate.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint. The description adds behavioral details: it runs the same provider auto-selection as generate_image, uses a local pricing table, and notes the estimate is a ballpark. No contradictions.
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 well-structured: starts with purpose, then explanation, caveats, and finally Args/Returns. It is slightly verbose but front-loaded with key information. A bit more conciseness could improve it.
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 simplicity of the tool (cost estimation with no side effects), the description covers all essential aspects: what it does, how it works, caveats, and return format (via output schema). With annotations and output schema present, no 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?
The description's Args section briefly lists parameters but adds little new meaning beyond the schema's own descriptions. The schema already provides detailed descriptions for each parameter. Schema coverage is 0% by context definition, but the schema itself is informative, so the description does not compensate for missing schema details.
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: estimating the cost of generating an image without actually generating it. It uses specific verb 'estimate' and resource 'cost', and distinguishes it from siblings like generate_image by explicitly noting it does not generate.
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 explains when to use: before generating, for comparing providers/qualities. It implies not to use for actual generation, but does not explicitly state when not to use or list alternatives beyond the tool itself. However, the sibling list provides context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an image using the best available provider.
Automatic Provider Selection: The server analyzes your prompt and automatically selects the best provider:
OpenAI GPT-Image-1 is auto-selected for:
Text-heavy images (menus, posters, infographics)
Comics with dialogue or speech bubbles
Technical diagrams with labels
Marketing materials requiring precise text
Gemini Nano Banana Pro is auto-selected for:
Photorealistic portraits and headshots
Product photography
High resolution (4K) output
Images using reference images for consistency
Real-time data visualization (weather, stocks)
Examples:
"Create a menu card for an Italian restaurant" → OpenAI (text rendering)
"Professional headshot with studio lighting" → Gemini (photorealism)
"Infographic explaining photosynthesis" → OpenAI (diagram + text)
"Product shot of perfume floating on water" → Gemini (product photography)
Override Selection:
Set provider to 'openai' or 'gemini' to override auto-selection.
Args: params: Image generation parameters including prompt and optional settings.
Returns: Formatted response with image path and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations exist but are minimal (readOnlyHint=false, etc.). Description adds value by explaining auto-selection behavior and provider strengths. However, it does not disclose important behaviors like file saving (implied by output_path), potential latency, or cost implications. No contradiction with annotations.
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 well-structured with headings, lists, and examples. It is front-loaded with the main purpose. However, it is somewhat lengthy with provider comparisons that could be condensed. Overall, sentences earn their place.
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 complexity (multiple providers, many parameters, auto-selection), the description explains the selection logic and provides examples. It mentions override and return format. An output schema exists to handle return details. It is fairly complete for an agent to understand the tool's behavior.
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 for the top-level param 'params' is 0% (no description), and the description only repeats 'Image generation parameters including prompt and optional settings' – adding no new meaning. While nested properties have descriptions in the schema, the description fails to compensate for the top-level lack of detail.
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 an image using the best available provider, with specific verb 'Generate' and resource 'image'. It distinguishes from siblings by focusing on single image generation with auto-selection, while siblings like 'edit_image' and 'conversational_image' imply different operations.
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 detailed guidance on when to use each provider within the tool, but offers no guidance on when to choose this tool over sibling tools like 'edit_image' or 'generate_image_batch'. An agent would need to infer from the tool name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate many images concurrently from a list of prompts.
Each item runs through the same auto provider selection as generate_image,
bounded by max_concurrency. Per-item failures are isolated — one bad
prompt does not fail the whole batch. Returns every result (saved paths plus
any per-item errors).
Use this instead of calling generate_image in a loop: 8 prompts that
would take ~4 minutes serially complete in roughly one generation's time
(subject to max_concurrency and provider rate limits).
Args: params: The batch (items + concurrency + optional default provider).
Returns: A formatted summary of all results.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-readonly, non-destructive, non-idempotent, open-world. Description adds concurrency bounds, failure isolation, rate limit dependency, and result format, providing substantial behavioral context beyond annotations.
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?
Well-structured with summary, args, and returns. Every sentence adds value; no redundancy.
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?
Covers inputs, behavior, concurrency, error handling, and return format. With output schema present, it provides complete guidance for a batch image generation 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?
Top-level 'params' description is brief, but the nested schema for `BatchGenerationInput` has detailed field descriptions. Tool description adds context about batch structure and default provider, complementing the schema.
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?
Clearly states the tool generates many images concurrently from a list of prompts. Distinguishes from siblings like `generate_image` by mentioning batch processing and concurrency.
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?
Explicitly advises using this tool instead of calling `generate_image` in a loop, with a concrete performance example. Also describes per-item failure isolation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved image generation conversations.
Returns recent conversations that can be continued for refinement. Each conversation tracks the provider used and generation history.
Args: params: Options for filtering and formatting the list.
Returns: List of conversations with metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read and idempotent. The description adds that results are 'recent' and can be 'continued for refinement', which provides some behavioral context beyond the annotations. However, it doesn't detail behavior like empty results, ordering, or response structure.
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 concise: four sentences total, with the core purpose in the first sentence. No extraneous information. All sentences add value.
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?
For a simple list tool, the description covers purpose and key traits (recent, continuable, tracks provider/history). It lacks details on pagination behavior and ordering, and the output format is only implied via the parameter. Still, it is mostly sufficient given the annotations and schema.
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?
The description only says 'params: Options for filtering and formatting the list.' This is vague and does not add meaning beyond the input schema, which already describes each parameter. With 0% schema description coverage, the description fails to compensate, but the schema itself is sufficient.
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 lists saved image generation conversations, using specific verb 'list' and resource 'conversations'. It distinguishes from siblings as no other list tool exists. The purpose is unambiguous.
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 used to retrieve recent conversations for refinement, but provides no explicit guidance on when to use it versus other tools or when not to use it. No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available Gemini models that support image generation.
Queries the Gemini API to show which models are available for image generation with your API key. Useful for troubleshooting or choosing alternative models.
Returns: List of available Gemini image models with their capabilities.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds that it queries the Gemini API and returns capabilities, but does not provide additional behavioral details beyond 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear purpose, action, return description, and use case. Every sentence adds value.
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 zero parameters and presence of an output schema, the description fully covers the tool's purpose and typical use case without needing further elaboration.
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?
There are no parameters, so the baseline is 4. The description does not need to add parameter semantics, and it does not attempt to.
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 it lists available Gemini models that support image generation. This verb-noun pair is specific and distinguishes it from siblings like 'generate_image' or 'list_providers'.
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 mentions it is useful for troubleshooting or choosing alternative models, providing clear context. It does not explicitly state when not to use it, but the context of sibling tools offers implied guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available image generation providers and their capabilities.
Returns a comparison of available providers including:
Which providers have API keys configured
Best use cases for each provider
Feature comparison (text rendering, resolution, etc.)
Use this to understand which provider to choose for your task.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds value by detailing the return content: API key configuration, best use cases, and feature comparison. No contradictions.
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 concise, with a clear lead sentence and bullet points for output details. Every sentence adds value, and there is no redundancy.
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 description adequately explains the tool's purpose and what the output includes, even without needing to detail parameters. Given the presence of an output schema, the description is complete.
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?
There are no parameters, and schema coverage is 100%. With zero parameters, the baseline is 4, and the description does not need to add parameter details.
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 explicitly states 'List available image generation providers and their capabilities', clearly identifying the verb (list) and resource (providers with capabilities). This distinguishes it from sibling tools like generate_image or edit_image, which perform different operations.
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 advises 'Use this to understand which provider to choose for your task', providing clear context for when to use this tool. While it doesn't list explicit alternatives or when-not-to-use, the context of sibling tools makes the usage well implied.
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.
v0.3.0conversational_imageedit_imageestimate_costgenerate_imagegenerate_image_batchlist_conversationslist_gemini_modelslist_providersScored across 8 tools
Each tool has a clearly distinct purpose: direct generation, conversational refinement, editing, batch generation, cost estimation, and listing of conversations/models/providers. Overlaps are minimal and resolved by detailed descriptions.
Most tools follow verb_noun snake_case (e.g., edit_image, generate_image), but 'conversational_image' uses an adjective instead of a verb, creating a slight inconsistency.
With 8 tools covering generation, editing, batch processing, cost estimation, and listing functions, the count is well-scoped for an image generation server without being too many or too few.
The tool surface covers core generation, editing, batch, and estimation needs. Minor gaps exist (e.g., no deletion tool or detailed image metadata viewer), but the essential workflows are supported.
Generate images with your own ChatGPT subscription (Plus, Pro or Team), without spending API credits
AI visual generation agent: multi-pipeline rendering, prompt crafting, and image composition.
Image, video, music and text generation across 100+ models through one endpoint.
Generate images with any major model — one API key, one prepaid balance, one MCP.
