This server provides deterministic optical analysis and physical layer decomposition of images, plus tools for relighting, compositing, and generating AI image prompts.
Analyze optical profiles: Extract metrics like color temperature (Kelvin), lighting angles, luminance dynamics, contrast zones, and surface roughness; optionally decompose into 6 visual layers (highlights, shadows, ambient occlusion, edges, depth normals, chroma/saturation).
Generate relight variations: Create four physically grounded lighting presets (Ambient, Dramatic, Rim, Mood) as local image files with exposure and color adjustments.
Harmonize composites: Blend a foreground subject into a background scene using color transfer, temperature matching, and synthesized contact shadows.
Synthesize diffusion prompts: Produce dual-format generative prompts (detailed JSON specification + descriptive master prompt) tailored for universal image generators or GEMINI Nano Banana.
List cached variations: Inventory and retrieve previously generated relight images and composite files from the local cache directory.
Provides integration with Google's AI image generation models (e.g., GEMINI Nano Banana) via Google Antigravity, enabling direct application of relighting and harmonization through generated images.
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., "@mcp-relight-harmonize harmonize my subject with the new background"
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 production-grade, highly-deterministic Model Context Protocol (MCP) server engineered for optical profiling, physical decomposition into 6 visual layers, contact-aware composite harmonization, and dual-format generative prompt synthesis (Detailed JSON + Accurate Master Prompt).
Model Architecture Note: Fully compatible with Any Image Generator Model, with dedicated targets for Universal Image Generator and GEMINI Nano Banana.
Environment Recommendation: Preferred and optimized for use inside Google Antigravity, where native direct visual generation (generate_image) allows zero-friction, instantaneous application of the learned optical layers!
Python Role: Optical Extraction & Layer Decomposition Only:
Python executes purely deterministic mathematical and optical analysis.
Generates exactly 6 visual decomposition layers into the Layers/ directory.
Directory Invariant: The server exclusively uses the Layers/ directory. No Variations/ or generated_variations/ directories are ever created.
Python never creates the final modified image.
Mandatory Image-by-Image Vision Analysis (Analyze):
The AI Assistant must never trigger image generation until it inspects and analyzes the 6 images in Layers/ image-by-image (صورة صورة).
Zero canned or pre-written text: All observations and insights stem directly from visual inspection of the actual layer images.
Dual-Format Generative Prompts (Two Formats):
Format 1: Detailed JSON Specification (detailedJsonSpecification): Comprehensive structured optical physics (Kelvin, azimuth, elevation, contrast ratio, roughness, contact shadow) and layer-by-layer directives for the generator.
Format 2: Accurate General Descriptive Master Prompt (masterDescriptivePrompt): Photorealistic studio photographic narrative integrating the user's intent with physical lighting and an 85mm prime lens at f/2.0.
Direct Execution via AI Image Generator:
Once the user answers "ماذا تريد من تعديل؟", the modification is rendered directly through the Image Generator (such as generate_image / GEMINI Nano Banana in Antigravity).
Related MCP server: Enhanced Multimedia Analysis MCP
Layers/)# | Layer Image File | Physical Objective & Inspection Target |
1 |
| طبقة الألوان الفاتحة: Isolates specular highlights ($Y > 170/255$). Inspected for glint locations and clipping prevention. |
2 |
| طبقة الألوان الغامقة: Isolates low-key values ($Y < 85/255$). Inspected for shadow density and photometric roll-off. |
3 |
| طبقة الظل العالي والارتكاز: Isolates contact umbra ($Y < 35/255$). Inspected to anchor base plane and prevent floating subjects. |
4 |
| طبقة الحواف والتفاصيل: Sobel gradient magnitude ($M = \sqrt{G_x^2 + G_y^2}$). Inspected for micro-texture and surface roughness. |
5 |
| طبقة العمق والمتجهات: Tangent space normal map ($R=N_x, G=N_y, B=N_z$). Inspected for 3D light vector and volumetric volume. |
6 |
| طبقة الألوان والتشبع: HSV chroma purity distribution. Inspected for color casts and spectral balance. |
Tool Name | Key Inputs | Outputs |
|
| Mathematical optical metrics, 6 visual layers in |
|
| Dual Prompts: Detailed JSON Specification + Accurate General Descriptive Master Prompt. |
|
| Physical relit images saved into |
|
| Composited image with harmonized CCT, Reinhard color transfer, and contact shadow. |
|
| Inventory of generated layers and artifacts in the |
# Install dependencies
npm install
# Compile TypeScript
npm run build
# Run quality test suite
npm test
# Health check
npm run verifymcp_config.json)Add to your client's mcp_config.json:
{
"mcpServers": {
"mcp-relight-harmonize": {
"command": "node",
"args": [
"c:/Users/DKurdistan/Desktop/mcp-relight-harmonize/dist/index.js"
],
"env": {
"OUTPUT_CACHE_DIR": "./Layers"
}
}
}
}Or via npx:
{
"mcpServers": {
"mcp-relight-harmonize": {
"command": "npx",
"args": ["-y", "mcp-relight-harmonize@latest"]
}
}
}# Build image locally
docker build -t mcp-relight-harmonize .
# Run container over stdio
docker run -i --rm -e OUTPUT_CACHE_DIR=/app/Layers mcp-relight-harmonizeMIT © MarwanDevSpace
Extract physical optical metrics from an image, including Correlated Color Temperature (CCT in Kelvin), dominant 3D lighting vector (azimuth and elevation angles), photometric luminance dynamic range, contrast zones, surface normal roughness index, and optionally decompose into 6 analytical image layers in Layers/ directory.
• Purpose: Diagnostic optical extraction and 6-layer decomposition (Highlights, Shadows, Ambient Occlusion, Edges, Depth Normals, Chroma/Saturation). Unlike 'generate_relight_variations' which creates artistic relit renders, this tool extracts physical diagnostic metrics and visual analytical decomposition layers. • Behavior: Read-only by default; writes 6 analytical layer PNGs and Layer.md to the specified directory when 'extract_layers' is true. Unmetered local execution, zero network egress, zero external auth. • When to use: Use as the prerequisite first step to inspect baseline lighting conditions or generate the 6 diagnostic layers into Layers/ before relighting or prompting. • When NOT to use: Do NOT use if you need creative relighted styles (use 'generate_relight_variations'), if merging a cutout into a scene (use 'harmonize_composite'), or if you only need generative AI prompt synthesis (use 'synthesize_diffusion_prompt'). • Alternatives: Use 'generate_relight_variations' for creative lighting styles, or 'synthesize_diffusion_prompt' for model prompts.
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | Yes | Absolute or workspace-relative path to a local image file (.png, .jpg, or .jpeg). Must be an existing image under 50 MB. | |
| layers_dir | No | Optional target directory to store the 6 analytical layer images and Layer.md (defaults to 'Layers'). | |
| user_intent | No | Optional creative or corrective intent to dynamically tailor layer diagnostics, recommendations, and diffusion prompts. | |
| extract_layers | No | If true, decomposes image into 6 analytical layers (Highlights, Shadows, Ambient Occlusion, Edges, Depth Normals, Chroma/Saturation) saved to Layers/ directory and generates Layer.md. |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| status | Yes | Execution status. |
| summary | Yes | Human-readable executive summary of the operation. |
| evidence | Yes | |
| warnings | Yes | Non-fatal warnings if applicable. |
| nextActions | Yes | Actionable follow-up guidance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it succeeds: it states that the tool is read-only by default, writes six analytical PNGs and Layer.md only when 'extract_layers' is true, and confirms local unmetered execution with zero network egress and zero external auth. This is unusually thorough behavioral transparency.
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 labeled sections and front-loaded purpose. However, there is some redundancy: the 'Purpose' bullet largely repeats the opening sentence, and the 'Alternatives' section repeats the sibling names already given in 'When NOT to use'. This slight repetition keeps it from a perfect score.
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 availability of an output schema, 100% schema description coverage, and the tool's moderate complexity, the description covers the essential context: purpose, distinction from siblings, side-effect behavior, execution environment, and when to avoid the tool. There are no significant gaps that would prevent 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?
Schema coverage is 100%, so the input schema already documents all four parameters. The description adds useful high-level context about layer decomposition and the 'Layers/' directory, but it does not materially extend the meaning of parameters beyond what the schema already states. Thus the baseline score 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 opens with a specific verb and resource ('Extract physical optical metrics from an image') and enumerates concrete outputs such as CCT, lighting vector angles, luminance range, and contrast zones. It also explicitly contrasts itself with 'generate_relight_variations', making the tool's diagnostic vs. artistic purpose unmistakable.
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 a dedicated 'When to use' section, a 'When NOT to use' section naming three alternative sibling tools with their appropriate contexts, and an 'Alternatives' section. An agent can confidently route between this tool and its siblings without external inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate 4 physically-grounded relit image variations on disk (Ambient fill, Dramatic chiaroscuro, Rim light halo, Mood golden-hour) with mathematical adjustment logs detailing exposure compensation (EV stops) and color balance.
• Purpose: Visual image transformation. Unlike 'analyze_optical_profile' which is read-only, this tool renders and writes concrete image files to the destination directory. Unlike 'synthesize_diffusion_prompt', it produces immediate local image files. • Behavior: Mutates filesystem by creating up to 4 image files in the output directory. Deterministic, unmetered local compute, no network egress, no authentication required. Re-running overwrites previous variations with the same base name. • When to use: Use when you need tangible image alternatives of a photo or product render with alternative lighting schemes. • When NOT to use: Do NOT use if you only need optical metrics (use 'analyze_optical_profile'), if blending a cutout into a background (use 'harmonize_composite'), or if you need diffusion AI text prompts (use 'synthesize_diffusion_prompt'). • Alternatives: Use 'synthesize_diffusion_prompt' for your Image Generator (GEMINI Nano Banana / Universal), or 'list_cached_variations' to browse existing outputs.
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | Yes | Path to the input image (.png, .jpg, .jpeg) to relight. | |
| output_dir | No | Destination folder for output files. If omitted, defaults to the server's configured cache directory ('./Layers'). Only 'Layers/' is used. | |
| target_lighting | No | Lighting preset selection: 'Ambient' (+0.8 EV lifted shadows, 5500K daylight), 'Dramatic' (-1.5 EV shadow crush, chiaroscuro S-curve), 'Rim' (+1.2 EV normal curvature perimeter halo), 'Mood' (3200K tungsten amber shift, highlight bloom), or 'All' to generate all four simultaneously. Defaults to 'All'. | All |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| status | Yes | Execution status. |
| summary | Yes | Human-readable executive summary of the operation. |
| evidence | Yes | |
| warnings | Yes | Non-fatal warnings if applicable. |
| nextActions | Yes | Actionable follow-up guidance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses all relevant behavioral traits: 'Mutates filesystem by creating up to 4 image files', 'Deterministic, unmetered local compute, no network egress, no authentication required', and 'Re-running overwrites previous variations with the same base name.' It also mentions the output format (logs with EV stops and color balance). This is comprehensive and transparent.
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 longer than average but every section serves a purpose: purpose, behavior, when-to-use, when-not-to-use, alternatives. It is front-loaded with the main action and the scoping 'on disk' immediately. Some slight redundancy (e.g., 'produces immediate local image files' appears twice) but no filler. It earns a 4 rather than a 5 due to minor repetition.
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 writes files, has an output schema, and no annotations, the description covers all necessary context: mutation, overwrite, determinism, network/auth, parameter semantics, and usage alternatives. It even preempts common misuse. Nothing an agent needs to call it correctly is missing.
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%, but the description adds substantial meaning beyond the schema. For each lighting preset it provides specific EV adjustments and color temperatures (e.g., 'Ambient (+0.8 EV lifted shadows, 5500K daylight)'), which is not in the schema. It also clarifies the output_dir behavior: 'Only 'Layers/' is used', a constraint not evident from the schema. This far exceeds the baseline 3.
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 opens with a specific verb and resource: 'Generate 4 physically-grounded relit image variations on disk' with named lighting presets. It explicitly contrasts with siblings: 'Unlike analyze_optical_profile which is read-only, this tool renders and writes concrete image files' and 'Unlike synthesize_diffusion_prompt, it produces immediate local image files.' This unambiguously identifies the tool's role and differentiates it.
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 a dedicated 'When to use' and 'When NOT to use' section, naming exact alternatives for each exclusion: 'analyze_optical_profile' for metrics, 'harmonize_composite' for blending, 'synthesize_diffusion_prompt' for diffusion prompts. It also lists alternatives in a separate section. This is explicit, exhaustive guidance with zero ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Harmonize and composite a foreground subject cutout onto a background environment scene image using Reinhard color statistics transfer in decorrelated lαβ space, background color temperature matching, and synthesized ground contact shadows.
• Purpose: Two-image compositing and photometric harmonization. Distinct from 'generate_relight_variations' which operates on a single image, this tool resolves color mismatches and grounding between two separate image sources. • Behavior: Mutates filesystem by writing 1 composited PNG image to the output cache directory. Deterministic, local execution, no network egress, no authentication required. • When to use: Use when placing a cutout product, character, or object onto a new background environment scene, ensuring realistic color adaptation and floor shadows. • When NOT to use: Do NOT use to relight a single standalone image (use 'generate_relight_variations'), or to analyze metrics alone (use 'analyze_optical_profile'). • Alternatives: Use 'generate_relight_variations' to alter lighting on a single image, or 'synthesize_diffusion_prompt' to craft inpainting prompts for seam blending.
| Name | Required | Description | Default |
|---|---|---|---|
| blend_mode | No | Blending mode: 'seamless' (applies Reinhard color transfer + contact shadow + alpha blend) or 'alpha' (standard alpha composite with contact shadow only). Defaults to 'seamless'. | seamless |
| background_path | Yes | Path to target background scene image (.png, .jpg, .jpeg). | |
| foreground_path | Yes | Path to foreground subject image. Supports transparent PNG (with alpha channel) or solid background. |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| status | Yes | Execution status. |
| summary | Yes | Human-readable executive summary of the operation. |
| evidence | Yes | |
| warnings | Yes | Non-fatal warnings if applicable. |
| nextActions | Yes | Actionable follow-up guidance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and it does so: it declares the mutation (writes 1 composited PNG to the output cache directory), determinism, local execution, no network egress, and no authentication required. This is precisely the behavioral profile an agent needs for a filesystem-mutating 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?
Front-loaded with the one-line purpose, then well-organized labelled sections. It is somewhat long, and the bullet labels read a bit like documentation scaffolding, but every sentence earns its place and nothing is wasted.
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 two-image, filesystem-mutating tool with 100% schema coverage and an output schema, the description is complete: purpose, behavior, selection criteria, and alternatives are all present, and return-value explanation is unnecessary given the output 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?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by naming the algorithms (Reinhard transfer in decorrelated lαβ space, background color temperature matching, contact shadows), which explains what 'seamless' actually does and why the foreground can be either transparent PNG or solid background.
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?
States a specific verb (harmonize/composite) and resource (foreground cutout onto background scene), and the opening line names the actual technique. It explicitly distinguishes itself from the sibling 'generate_relight_variations' as a two-image tool versus a single-image tool.
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 'When to use', 'When NOT to use', and 'Alternatives' sections name three sibling tools and the exact conditions that select each. An agent can route correctly without opening any schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List and inspect all previously generated relight variation images and harmonized composite files stored in the output cache directory.
• Purpose: Cache inventory and artifact retrieval. Resolves pipeline completeness by allowing callers to discover, verify, and retrieve generated files without manual filesystem traversal. • Behavior: Completely read-only, queries local filesystem cache directory, no network calls, no authentication required. • When to use: Use after running 'generate_relight_variations' or 'harmonize_composite' to verify written artifacts, inspect file sizes, and obtain exact paths for downstream analysis. • When NOT to use: Do NOT use to generate new images (use 'generate_relight_variations') or to analyze optical metrics (use 'analyze_optical_profile'). • Alternatives: Use 'generate_relight_variations' to create new images, or 'harmonize_composite' to merge cutouts.
| Name | Required | Description | Default |
|---|---|---|---|
| cache_dir | No | Optional custom directory path to inspect. If omitted, uses server's default cache directory. |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| status | Yes | Execution status. |
| summary | Yes | Human-readable executive summary of the operation. |
| evidence | Yes | |
| warnings | Yes | Non-fatal warnings if applicable. |
| nextActions | Yes | Actionable follow-up guidance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description must carry the behavioral burden, and it does well: 'Completely read-only,' 'no network calls,' 'no authentication required,' and the filesystem-local scope are all stated. It stops short of describing pagination, ordering, or what happens on a missing/empty cache directory.
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 prose lead is front-loaded and each bulleted section is on-topic, though the Purpose/Behavior/When-to-use/When-NOT/Alernatives scaffolding is heavier than strictly needed for a one-parameter read-only lister. Nothing is redundant, but it is slightly 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?
For a simple read-only list tool with a fully documented single parameter and an output schema present, the description covers purpose, safety traits, triggering conditions, and sibling routing. An agent has everything needed to call it correctly.
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% and the single 'cache_dir' parameter is fully documented in the schema, including its default and fallback behavior, so the baseline is 3. The description adds no syntax or format detail beyond 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?
The opening sentence states a specific verb ('List and inspect') and resource ('relight variation images and harmonized composite files in the output cache'), and the 'Purpose' bullet reinforces it as 'Cache inventory and artifact retrieval.' It is clearly distinguishable from siblings that generate or analyze images.
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 'When to use' names the producing siblings ('generate_relight_variations', 'harmonize_composite') and the triggering condition; 'When NOT to use' names alternatives for generation and analysis with the correct sibling per rejected intent. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Synthesize precision enhancement and relighting diffusion prompts based on physical optical analysis of an image, compatible with Any Image Generator Model (optimized for GEMINI Nano Banana). Outputs photorealistic prompts with physical keywords (exact Kelvin CCT, 3D light angles, volumetric dust rays, contact shadows) and calibrated denoising parameters (0.35 - 0.45).
• Purpose: Generative AI prompt synthesis. Unlike 'generate_relight_variations' which creates image files locally, this tool translates optical geometry into targeted text prompts and hyperparameter sets for Any Image Generator (optimized for Antigravity). • Behavior: Completely read-only, deterministic, zero filesystem modifications, no network calls, and no authentication required. • When to use: Use when you want to feed photorealistic lighting directives or inpainting prompts into your Image Generator or Antigravity's generate_image. • When NOT to use: Do NOT use if you need local image rendering without an external AI model (use 'generate_relight_variations'), or if merging cutouts locally (use 'harmonize_composite'). • Alternatives: Use 'generate_relight_variations' for instant offline image files, or 'analyze_optical_profile' for raw numerical statistics.
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | Yes | Path to the local reference image (.png, .jpg, .jpeg) to extract optical geometry from. | |
| user_intent | No | Optional creative context or scenario description (e.g., 'golden sunset portrait', 'cyberpunk studio product'). | |
| target_model | No | Target generative engine format: 'universal' (outputs natural descriptive studio directives with 85mm prime lens and physical illumination compatible with Any Image Generator) or 'nano_banana' (outputs dense tokenized optical shaders for GEMINI Nano Banana). Defaults to 'universal'. | universal |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| status | Yes | Execution status. |
| summary | Yes | Human-readable executive summary of the operation. |
| evidence | Yes | |
| warnings | Yes | Non-fatal warnings if applicable. |
| nextActions | Yes | Actionable follow-up guidance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full disclosure burden. It explicitly states the tool is read-only, deterministic, performs zero filesystem modifications, makes no network calls, and requires no authentication. It also describes the output characteristics, such as exact Kelvin CCT, 3D light angles, volumetric dust rays, and denoising ranges.
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 uses structured bullets with clear labels and front-loads the core capability before enumerating use cases. Every sentence adds distinct value — purpose, behavior, when to use, when not to use, and alternatives — with no filler.
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 output schema exists, no annotations are present, and there are three sibling tools, the description covers everything an agent needs for correct invocation: purpose, behavior, parameter semantics, usage boundaries, and alternatives. No material gap is evident.
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% and the schema already documents all three parameters well. The description adds value by clarifying the functional meaning of the tool's outputs and by distinguishing target_model formats conceptually ('universal' vs 'nano_banana'), reinforcing how user_intent and image_path feed into the prompt synthesis. This exceeds the high-coverage baseline without duplicating 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?
The description uses a specific verb-resource pairing: 'Synthesize ... diffusion prompts' based on physical optical analysis, and states the exact output type (photorealistic prompts with physical keywords and denoising parameters). It also explicitly distinguishes itself from siblings like 'generate_relight_variations' and 'analyze_optical_profile'.
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?
Dedicated 'When to use', 'When NOT to use', and 'Alternatives' sections explicitly name sibling tools and the conditions that select them. An agent can clearly decide between this tool, 'generate_relight_variations', 'harmonize_composite', and 'analyze_optical_profile' without guesswork.
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.
v1.0.5analyze_optical_profile3 fields changedInput schema / properties / extract_layersAdded value: +{
+ "description": "If true, decomposes image into 6 analytical layers (Highlights, Shadows, Ambient Occlusion, Edges, Depth Normals, Chroma/Saturation) saved to Layers/ directory and generates Layer.md.",
+ "type": "boolean"
+}Input schema / properties / layers_dirAdded value: +{
+ "description": "Optional target directory to store the 6 analytical layer images and Layer.md (defaults to 'Layers').",
+ "type": "string"
+}Input schema / properties / user_intentAdded value: +{
+ "description": "Optional creative or corrective intent to dynamically tailor layer diagnostics, recommendations, and diffusion prompts.",
+ "type": "string"
+}generate_relight_variations1 field changedInput schema / properties / output_dir / descriptionPrevious value: -"Destination folder for generated variation image files. If omitted, defaults to the server's configured cache directory ('./generated_variations')."New value: +"Destination folder for output files. If omitted, defaults to the server's configured cache directory ('./Layers'). Only 'Layers/' is used."synthesize_diffusion_prompt7 fields changedInput schema / properties / target_model / defaultPrevious value: -"gpt_image"New value: +"universal"Input schema / properties / target_model / descriptionPrevious value: -"Target generative engine: 'gpt_image' (outputs natural descriptive studio directives with 85mm prime lens and physical illumination) or 'nano_banana' (outputs dense tokenized optical shaders, roughness index, raytraced bounce, and ground contact shadow). Defaults to 'gpt_image'."New value: +"Target generative engine format: 'universal' (outputs natural descriptive studio directives with 85mm prime lens and physical illumination compatible with Any Image Generator) or 'nano_banana' (outputs dense tokenized optical shaders for GEMINI Nano Banana). Defaults to 'universal'."Input schema / properties / target_model / enumPrevious value: -[
- "gpt_image",
- "nano_banana"
-]New value: +[
+ "universal",
+ "nano_banana"
+]Output schema / properties / data / properties / detailedJsonSpecificationAdded value: +{
+ "description": "Structured JSON optical specifications for layer-guided rendering.",
+ "type": "object"
+}Output schema / properties / data / properties / masterDescriptivePromptAdded value: +{
+ "description": "Accurate general descriptive master prompt for photorealistic generation.",
+ "type": "string"
+}Output schema / properties / data / properties / targetModel / enumRemoved value: -[
- "GPT Image",
- "Nano Banana"
-]Output schema / properties / data / requiredPrevious value: -[
- "targetModel",
- "userIntent",
- "enhancementPrompt",
- "relightingPrompt",
- "recommendedParameters",
- "opticalKeywordsUsed"
-]New value: +[
+ "targetModel",
+ "userIntent",
+ "detailedJsonSpecification",
+ "masterDescriptivePrompt",
+ "enhancementPrompt",
+ "relightingPrompt",
+ "recommendedParameters",
+ "opticalKeywordsUsed"
+]v1.0.2analyze_optical_profile2 fields changedInput schema / properties / image_path / descriptionPrevious value: -"Absolute or workspace-relative path to the image file."New value: +"Absolute or workspace-relative path to a local image file (.png, .jpg, or .jpeg). Must be an existing image under 50 MB."Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "colorTemperatureKelvin": {
+ "description": "Correlated Color Temperature (CCT) in Kelvin.",
+ "type": "number"
+ },
+ "contrastZones": {
+ "properties": {
+ "deepShadowsPct": {
+ "type": "number"
+ },
+ "midtonesPct": {
+ "type": "number"
+ },
+ "specularHighlightsPct": {
+ "type": "number"
+ }
+ },
+ "type": "object"
+ },
+ "dimensions": {
+ "description": "[width, height] in pixels.",
+ "items": {
+ "type": "number"
+ },
+ "type": "array"
+ },
+ "dominantLightDirectionVector": {
+ "description": "Normalized [X, Y, Z] vector.",
+ "items": {
+ "type": "number"
+ },
+ "type": "array"
+ },
+ "imagePath": {
+ "description": "Canonical resolved file path.",
+ "type": "string"
+ },
+ "lightingAngles": {
+ "properties": {
+ "azimuthDeg": {
+ "description": "Horizontal angle (0-360°).",
+ "type": "number"
+ },
+ "elevationDeg": {
+ "description": "Vertical elevation angle (0-90°).",
+ "type": "number"
+ }
+ },
+ "required": [
+ "azimuthDeg",
+ "elevationDeg"
+ ],
+ "type": "object"
+ },
+ "luminanceDynamics": {
+ "properties": {
+ "contrastRatio": {
+ "type": "number"
+ },
+ "max": {
+ "type": "number"
+ },
+ "median": {
+ "type": "number"
+ },
+ "min": {
+ "type": "number"
+ },
+ "p5": {
+ "type": "number"
+ },
+ "p95": {
+ "type": "number"
+ }
+ },
+ "type": "object"
+ },
+ "meanLuminance": {
+ "description": "Average photometric luminance (0-255).",
+ "type": "number"
+ },
+ "opticalProfileSummary": {
+ "description": "Executive summary sentence.",
+ "type": "string"
+ },
+ "surfaceNormalVariation": {
+ "description": "Roughness metric (std dev of normals).",
+ "type": "number"
+ }
+ },
+ "required": [
+ "imagePath",
+ "dimensions",
+ "colorTemperatureKelvin",
+ "dominantLightDirectionVector",
+ "lightingAngles",
+ "meanLuminance",
+ "luminanceDynamics",
+ "contrastZones",
+ "surfaceNormalVariation",
+ "opticalProfileSummary"
+ ],
+ "type": "object"
+ },
+ "evidence": {
+ "properties": {
+ "artifacts": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "inputsDigest": {
+ "description": "SHA-256 digest of input parameters.",
+ "type": "string"
+ },
+ "sources": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "nextActions": {
+ "description": "Actionable follow-up guidance.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "status": {
+ "description": "Execution status.",
+ "enum": [
+ "success",
+ "partial",
+ "blocked",
+ "failed"
+ ],
+ "type": "string"
+ },
+ "summary": {
+ "description": "Human-readable executive summary of the operation.",
+ "type": "string"
+ },
+ "warnings": {
+ "description": "Non-fatal warnings if applicable.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "data",
+ "warnings",
+ "evidence",
+ "nextActions"
+ ],
+ "type": "object"
+}generate_relight_variations5 fields changedInput schema / properties / image_path / descriptionPrevious value: -"Path to the source image."New value: +"Path to the input image (.png, .jpg, .jpeg) to relight."Input schema / properties / output_dir / defaultAdded value: +""Input schema / properties / output_dir / descriptionPrevious value: -"Custom output directory. If omitted, uses default cache directory."New value: +"Destination folder for generated variation image files. If omitted, defaults to the server's configured cache directory ('./generated_variations')."Input schema / properties / target_lighting / descriptionPrevious value: -"Lighting preset: 'Ambient', 'Dramatic', 'Rim', 'Mood', or 'All'."New value: +"Lighting preset selection: 'Ambient' (+0.8 EV lifted shadows, 5500K daylight), 'Dramatic' (-1.5 EV shadow crush, chiaroscuro S-curve), 'Rim' (+1.2 EV normal curvature perimeter halo), 'Mood' (3200K tungsten amber shift, highlight bloom), or 'All' to generate all four simultaneously. Defaults to 'All'."Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "originalImage": {
+ "type": "string"
+ },
+ "outputDir": {
+ "type": "string"
+ },
+ "totalVariations": {
+ "type": "number"
+ },
+ "variations": {
+ "items": {
+ "properties": {
+ "adjustmentsApplied": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "evShiftStops": {
+ "type": "number"
+ },
+ "fileSizeBytes": {
+ "type": "number"
+ },
+ "imagePath": {
+ "type": "string"
+ },
+ "presetName": {
+ "type": "string"
+ },
+ "targetCctKelvin": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "presetName",
+ "imagePath",
+ "fileSizeBytes",
+ "evShiftStops",
+ "targetCctKelvin",
+ "adjustmentsApplied"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "originalImage",
+ "outputDir",
+ "totalVariations",
+ "variations"
+ ],
+ "type": "object"
+ },
+ "evidence": {
+ "properties": {
+ "artifacts": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "inputsDigest": {
+ "description": "SHA-256 digest of input parameters.",
+ "type": "string"
+ },
+ "sources": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "nextActions": {
+ "description": "Actionable follow-up guidance.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "status": {
+ "description": "Execution status.",
+ "enum": [
+ "success",
+ "partial",
+ "blocked",
+ "failed"
+ ],
+ "type": "string"
+ },
+ "summary": {
+ "description": "Human-readable executive summary of the operation.",
+ "type": "string"
+ },
+ "warnings": {
+ "description": "Non-fatal warnings if applicable.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "data",
+ "warnings",
+ "evidence",
+ "nextActions"
+ ],
+ "type": "object"
+}harmonize_composite4 fields changedInput schema / properties / background_path / descriptionPrevious value: -"Path to the background environment image."New value: +"Path to target background scene image (.png, .jpg, .jpeg)."Input schema / properties / blend_mode / descriptionPrevious value: -"Blending algorithm ('seamless' or 'alpha')."New value: +"Blending mode: 'seamless' (applies Reinhard color transfer + contact shadow + alpha blend) or 'alpha' (standard alpha composite with contact shadow only). Defaults to 'seamless'."Input schema / properties / foreground_path / descriptionPrevious value: -"Path to the foreground subject cutout (PNG/JPG)."New value: +"Path to foreground subject image. Supports transparent PNG (with alpha channel) or solid background."Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "backgroundCctKelvin": {
+ "description": "Target background color temperature.",
+ "type": "number"
+ },
+ "backgroundPath": {
+ "type": "string"
+ },
+ "blendMode": {
+ "type": "string"
+ },
+ "compositeImagePath": {
+ "description": "Absolute path to the rendered composite file on disk.",
+ "type": "string"
+ },
+ "contactShadowApplied": {
+ "description": "True if contact shadow was synthesized at base.",
+ "type": "boolean"
+ },
+ "details": {
+ "type": "object"
+ },
+ "foregroundPath": {
+ "type": "string"
+ },
+ "luminanceScalingFactor": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "compositeImagePath",
+ "blendMode",
+ "foregroundPath",
+ "backgroundPath",
+ "backgroundCctKelvin",
+ "luminanceScalingFactor",
+ "contactShadowApplied"
+ ],
+ "type": "object"
+ },
+ "evidence": {
+ "properties": {
+ "artifacts": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "inputsDigest": {
+ "description": "SHA-256 digest of input parameters.",
+ "type": "string"
+ },
+ "sources": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "nextActions": {
+ "description": "Actionable follow-up guidance.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "status": {
+ "description": "Execution status.",
+ "enum": [
+ "success",
+ "partial",
+ "blocked",
+ "failed"
+ ],
+ "type": "string"
+ },
+ "summary": {
+ "description": "Human-readable executive summary of the operation.",
+ "type": "string"
+ },
+ "warnings": {
+ "description": "Non-fatal warnings if applicable.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "data",
+ "warnings",
+ "evidence",
+ "nextActions"
+ ],
+ "type": "object"
+}list_cached_variationssynthesize_diffusion_prompt5 fields changedInput schema / properties / image_path / descriptionPrevious value: -"Path to the reference image."New value: +"Path to the local reference image (.png, .jpg, .jpeg) to extract optical geometry from."Input schema / properties / target_model / descriptionPrevious value: -"Target engine: 'gpt_image' (GPT Image) or 'nano_banana' (Nano Banana)."New value: +"Target generative engine: 'gpt_image' (outputs natural descriptive studio directives with 85mm prime lens and physical illumination) or 'nano_banana' (outputs dense tokenized optical shaders, roughness index, raytraced bounce, and ground contact shadow). Defaults to 'gpt_image'."Input schema / properties / user_intent / defaultAdded value: +""Input schema / properties / user_intent / descriptionPrevious value: -"Creative intent (e.g. 'golden sunset', 'studio commercial')."New value: +"Optional creative context or scenario description (e.g., 'golden sunset portrait', 'cyberpunk studio product')."Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "enhancementPrompt": {
+ "description": "Prompt for micro-surface detail and lens clarity upgrade.",
+ "type": "string"
+ },
+ "opticalKeywordsUsed": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "recommendedParameters": {
+ "description": "Calibrated diffusion settings (denoising 0.35-0.45, etc.).",
+ "type": "object"
+ },
+ "relightingPrompt": {
+ "description": "Prompt for physical relighting with angles, CCT, and contact shadows.",
+ "type": "string"
+ },
+ "targetModel": {
+ "enum": [
+ "GPT Image",
+ "Nano Banana"
+ ],
+ "type": "string"
+ },
+ "userIntent": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "targetModel",
+ "userIntent",
+ "enhancementPrompt",
+ "relightingPrompt",
+ "recommendedParameters",
+ "opticalKeywordsUsed"
+ ],
+ "type": "object"
+ },
+ "evidence": {
+ "properties": {
+ "artifacts": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "inputsDigest": {
+ "description": "SHA-256 digest of input parameters.",
+ "type": "string"
+ },
+ "sources": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "nextActions": {
+ "description": "Actionable follow-up guidance.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "status": {
+ "description": "Execution status.",
+ "enum": [
+ "success",
+ "partial",
+ "blocked",
+ "failed"
+ ],
+ "type": "string"
+ },
+ "summary": {
+ "description": "Human-readable executive summary of the operation.",
+ "type": "string"
+ },
+ "warnings": {
+ "description": "Non-fatal warnings if applicable.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "data",
+ "warnings",
+ "evidence",
+ "nextActions"
+ ],
+ "type": "object"
+}v0.1.1analyze_optical_profilegenerate_relight_variationsharmonize_compositesynthesize_diffusion_promptScored across 5 tools
Each tool has a clearly distinct purpose: analyze_optical_profile is read-only diagnostics, generate_relight_variations creates local images, synthesize_diffusion_prompt generates AI prompts, harmonize_composite blends two images, and list_cached_variations lists artifacts. The descriptions explicitly cross-reference and differentiate each tool, leaving no ambiguity.
All tool names follow a consistent verb_noun snake_case pattern: analyze_, generate_, synthesize_, harmonize_, list_. The verbs are descriptive and match the action, and the objects are specific. No deviations or mixed conventions.
Five tools is well-scoped for this domain, covering analysis, generation, prompt synthesis, compositing, and artifact listing. Each tool earns its place and there is no bloat or unnecessary overlap.
The tool surface covers the full lifecycle of relighting and harmonization: analyze a source image, generate variations, synthesize prompts, composite cutouts, and list results. There are no obvious dead ends or missing operations for the stated purpose.
AI photoshoot studio: garments, avatars, locations, and art direction
AI visual generation agent: multi-pipeline rendering, prompt crafting, and image composition.
AI film lab for filmmakers: generate and review images/clips with input provenance, cost preflight
Design, save, and run outcome-aligned AI workflows and verifiers, with reliable image output.
