What can you do with this server?

This server exposes 14 Adobe Firefly tools — 10 credit-consuming media operations plus reference uploads, job reads and account reads — through an MCP interface. * Generate images: generate_image (Firefly Image 3/4, with size, style/structure references, seeds, negative prompt, custom models) and generate_image5 (Image 5, with natural-language reference-blob edits, aspect ratio, resolution level). * Create variations: generate_similar makes similar images from a source image URL or upload ID. * Edit with masks: generative_fill fills a masked region and generative_expand expands an image to a wider canvas using a mask or placement. * Composite: generate_object_composite builds a scene around a product, while precise_composite and adaptive_composite place a supplied object onto a supplied background with blend/harmonization/shadow controls. * Generate video: generate_video produces a five-second video from a prompt and/or keyframe images, with shot size, angle, style and camera-motion settings. * Upscale: upscale_image enlarges an image by 2x, 3x, 4x or 6x with one seed per output. * Upload references: upload_image sends a local JPEG/PNG/WebP/TIFF/JXL (max 15 MB) to Adobe and returns an upload ID valid for seven days. * Manage jobs: set wait=false to get an async job immediately, then read it with get_job_status; optionally download finished media with download. * Check the account: verify_credentials validates OAuth credentials or an access token, and list_custom_models pages through the project's available custom models. * Constraints: every generation/composite/video call spends Adobe credits and requires explicit confirmation; Adobe Firefly Services entitlement and OAuth Server-to-Server credentials are needed, and the server typically runs locally over stdio.

How do I use Firefly MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Firefly MCP Server make a square product photo of a ceramic mug and confirm before spending credits" 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.

Firefly MCP Server

by thenavidm

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Adobe Firefly MCP Server & CLI

npm License YouTube LinkedIn

Adobe Firefly MCP server and CLI for Claude Code, Codex and AI agents. 14 tools for Image 5 generation and editing, video, generative fill, expansion, composites, upscaling, reference uploads, jobs and custom models.

One package gives you two ways in: firefly-mcp connects the tools to your AI app, and firefly-cli makes the same tools shell commands. Claude Desktop also has a bundled .mcpb extension.

Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI. The complete setup guide is on navid.me.

The terminal illustrates shipped tool names and the confirmation flow. It is a presentation preview, not a recording of a paid Adobe job.

You need Adobe Firefly Services API entitlement, with OAuth Server-to-Server credentials from an Adobe Developer Console project. A consumer Firefly plan and your Adobe account password do not supply that access. Generation uses your Adobe credits.

Validation: builds, behavioral tests, clean package installation, real MCP discovery and desktop bundle discovery are checked. Live account generation is still unverified, and no generation success rate is claimed; section 7 has the measured token costs.

Two ways to use it

Command line

npm install -g @thenavidm/firefly-mcp-cli@latest
firefly-cli
firefly-cli generate-image5 --help
firefly-cli schema generate-image5
firefly-cli verify-credentials --agent
firefly-cli list-custom-models --limit 10 --agent
firefly-cli generate-image5 --prompt "A ceramic cup in warm morning light" --aspectRatio 1:1 --confirm --agent

--confirm is the terminal spelling of confirm: true. It authorizes the paid operation you requested. --agent and --yes do not authorize spending.

MCP server, for your AI app

claude mcp add --scope user firefly -- npx -y @thenavidm/firefly-mcp-cli@latest

Configure the credentials in private local settings first, then ask: "Make a square product image. Confirm the credit-spending operation before you run it."

All client configurations and operating-system steps are in INSTALL.md.

Which one

Where you work	What to use
Claude Code, Codex, Cursor or another agent with a terminal	MCP, CLI or both; use the CLI when a shell command fits the workflow
Claude Desktop chat	The local MCP server or desktop extension
Scripts, cron or CI	CLI commands, or MCP through an MCP client
A web client that accepts only a remote MCP URL	This package needs a local stdio-capable client; it does not host a public HTTP endpoint

Related MCP server: BudgetPixel MCP Server

Features

Capability	CLI command	MCP tool
Image 5 generation and reference editing	`firefly-cli generate-image5`	`generate_image5`
v3 image generation	`firefly-cli generate-image`	`generate_image`
Variations from a source image	`firefly-cli generate-similar`	`generate_similar`
Fill a masked region	`firefly-cli generative-fill`	`generative_fill`
Expand an image	`firefly-cli generative-expand`	`generative_expand`
Scene around a product	`firefly-cli generate-object-composite`	`generate_object_composite`
Background/object compositing	`firefly-cli precise-composite` / `adaptive-composite`	`precise_composite` / `adaptive_composite`
Upscale an image	`firefly-cli upscale-image`	`upscale_image`
Five-second video	`firefly-cli generate-video`	`generate_video`
Upload a reference image	`firefly-cli upload-image`	`upload_image`
Resume an existing job	`firefly-cli get-job-status`	`get_job_status`
Check authentication	`firefly-cli verify-credentials`	`verify_credentials`
Available custom models	`firefly-cli list-custom-models`	`list_custom_models`
Diagnose setup	`firefly-cli doctor`	CLI utility

Number	Section	What it covers
1	What you can ask it	Practical prompts
2	Quick install	MCP, CLI and desktop
3	Set up Adobe access	Entitlement, credentials and revocation
4	Connect your client	Every client and OS
5	Check it works	Doctor, authentication and first read
6	Output, flags and exit codes	Scripts and agent mode
7	MCP or CLI and token cost	Method, standing context and task cost
8	Every tool and argument	All 14 tools, grouped
9	Image, editing and video workflows	Real argument shapes
10	Jobs and local files	Polling, timeouts and downloads
11	Several Adobe projects	Separate configurations
12	Writing safely	Credit confirmation, read-only and audit
13	How it works	Shared schemas and handlers
14	Your data	Hosts, files and credentials
15	Environment variables	Credentials, safety and tuning
16	Updates and removal	npm, desktop and disconnecting
17	Troubleshooting	Symptoms and fixes
18	API coverage and comparisons	Official and community alternatives
19	Versions	Release history and migration
20	FAQ	Common questions

1. What you can ask it

Make a square product image with warm morning light. Show me the prompt before spending credits.
Change this reference image's background to soft blue with Image 5.
Fill this masked area without changing the rest of the image.
Expand this image to a wider canvas using the supplied mask and size.
Put this product into a generated scene, or use a background I supply.
Create a five-second video from this prompt and return the job immediately.
Check the job I already submitted; do not generate it again.
Upload this reference file and use its upload ID for the requested edit.
List the custom models available to this Adobe project.

The account needs permission for the relevant API. A successful OAuth check does not prove that it can run every generation model.

2. Quick install

Node 22 or newer is required for the CLI and manual MCP configuration. The desktop bundle carries the server's production dependencies.

Claude Code

claude mcp add --scope user firefly -- npx -y @thenavidm/firefly-mcp-cli@latest

Claude Desktop

Download the .mcpb from the latest GitHub release. In Claude Desktop, open Settings → Extensions → Advanced settings → Install Extension…, select the bundle and enter the two credential fields.

Terminal

npm install -g @thenavidm/firefly-mcp-cli@latest
firefly-cli --version
firefly-cli

Install the package first, configure Adobe credentials second, and connect your client third. INSTALL.md supplies copyable blocks for Claude Code, Claude Desktop, Codex, Cursor, Windsurf, VS Code, Gemini CLI, Zed, Cline and other stdio clients.

3. Set up Adobe access

Before the credential fields

Adobe documents a provisioned Firefly Services project and organization access. Follow Adobe's getting-started requirements or check entitlement with your organization administrator or Adobe representative.

Set it up yourself

Open Adobe Developer Console and select the organization with Firefly Services access.
Open the provisioned project containing the Firefly API.
Open its OAuth Server-to-Server credential.
Copy the Client ID and Client secret into your private client environment settings or local shell. Do not paste them into an issue, chat, repository or shared config.
Keep the scopes assigned to the project. Use FIREFLY_SCOPES if they differ from the tutorial defaults.
Run firefly-cli doctor --network, then the first read below.
Restart your AI client so its server process sees the updated environment.

For a temporary Unix shell, replace the placeholders locally:

export FIREFLY_CLIENT_ID='YOUR_FIREFLY_SERVICES_CLIENT_ID'
export FIREFLY_CLIENT_SECRET='YOUR_FIREFLY_SERVICES_CLIENT_SECRET'
firefly-cli doctor --network

PowerShell:

$env:FIREFLY_CLIENT_ID = 'YOUR_FIREFLY_SERVICES_CLIENT_ID'
$env:FIREFLY_CLIENT_SECRET = 'YOUR_FIREFLY_SERVICES_CLIENT_SECRET'
firefly-cli doctor --network

The CLI does not read .env files automatically. Set variables in the process that launches it. An MCP desktop client launched from the Dock may not inherit your terminal variables; use its private environment settings or the bundle's credential fields.

Let your AI help with setup

Set up the Adobe Firefly MCP server and CLI for me.

1. Verify the package installs and both firefly-cli and firefly-mcp report a version.
2. Guide me to the provisioned Adobe Developer Console project with Firefly API access.
3. Ask me to enter the client ID and secret in private local settings. Never ask me to paste credentials into chat or put them in a repository.
4. Configure my chosen MCP client with npx -y @thenavidm/firefly-mcp-cli@latest.
5. Run doctor, then doctor --network, and explain which check failed.
6. Try list-custom-models as a read-only account check.
7. Do not upload a file or generate media while checking setup.

Existing access token

FIREFLY_ACCESS_TOKEN replaces the client secret, but FIREFLY_CLIENT_ID is still needed. A supplied token is verified with a read from the custom-model API. OAuth Server-to-Server credentials are verified by exchanging them for a token. Neither path proves image/video generation entitlement.

Disconnect or rotate

Rotate or revoke credentials in Adobe Developer Console, then update private client settings and restart its MCP connection. Existing output files remain on your disk.

4. Connect your client

Client	Setup route
Claude Code	`claude mcp add --scope user firefly -- npx -y @thenavidm/firefly-mcp-cli@latest`
Claude Desktop	GitHub release `.mcpb` and the Extensions settings
Codex	`codex mcp add firefly -- npx -y @thenavidm/firefly-mcp-cli@latest`
Cursor	User `~/.cursor/mcp.json`, `mcpServers` and `type: "stdio"`
Windsurf	Private user `~/.codeium/windsurf/mcp_config.json`
VS Code / GitHub Copilot	`servers` configuration with `type: "stdio"`
Gemini CLI	User `~/.gemini/settings.json` and `mcpServers`
Zed	User `context_servers` configuration
Cline and other local MCP clients	The same command, args and private environment

For the full JSON blocks, paths on each OS, logs, restarting, Docker and remote-client limits, use INSTALL.md. No public HTTP endpoint is included.

5. Check it works

firefly-cli --version
firefly-cli doctor
firefly-cli doctor --network
firefly-cli verify-credentials --agent
firefly-cli list-custom-models --limit 1 --agent

doctor checks whether local credential settings are present. doctor --network verifies OAuth or performs a custom-model read for a supplied access token. It does not generate media or spend generation credits.

verify-credentials returns authenticated, validation and entitlementChecked. The last remains false because generation permissions are only tested when that operation runs.

An empty custom-model list can be a valid response. A 403 can be a project permission problem. To verify generation, request one small image deliberately and confirm that credit-spending action; the source has not yet been validated against a live entitled account.

6. Output, flags and exit codes

Tool results go to stdout. Errors are JSON on stderr. Reads and generation return structured JSON, so --select can retain nested fields.

firefly-cli get-job-status --jobId JOB_ID_FROM_ADOBE --agent --select status,result.outputs,outputs
firefly-cli list-custom-models --limit 10 --compact
firefly-cli schema generate-image5

Flag	What it does
`--json`	JSON output
`--compact`	Single-line JSON
`--agent`	Compact JSON and no prompts; never confirms a write
`--select a,b.c`	Keep selected fields; dotted paths descend and arrays are traversed
`--confirm`	Confirm the requested paid media operation
`--no-input`, `--no-color`, `--yes`	Automation switches; none overrides the spending guard
`--wait=false`	Return an accepted job instead of polling
`--download`	Save completed media locally; requires waiting for completion

Global output flags apply to tool commands. doctor has its own --network option, and doctor --json returns its checks as JSON.

Exit code	Meaning	What a script should do
0	Success	Read stdout
1	Unexpected error	Report it with the command that failed
2	Usage, invalid input, a refused write, an unknown command or a hidden write	Fix the input or confirm only the requested action
3	Job or local upload file not found	Check the ID/path
4	Authentication or entitlement rejected	Check private credential settings and permissions
5	API, network or polling failure	Inspect an accepted job before another paid submission
7	Rate limited	Wait; do not loop over paid submissions
10	Credentials not configured	Complete local setup

The underscore spelling also works. generate_image5 and generate-image5 call the same tool. Nested objects use quoted JSON. Arrays of objects use repeated flags, one JSON object at a time.

7. MCP or CLI and token cost

Both surfaces reach the same 14 tools. The comparison concerns model context and workflow, not a cheaper Adobe credit price.

Measured on 2026-10-05 against 2.0.1, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, the difference read from the API's own usage figures) and Codex 0.159.3 on gpt-6.1-sol:

Cost	2.0.1	3.0.0
Claude Code, every tool loaded, every message	18,530	16,786
Claude Code's default, tool search, every message	377	379
`SKILL.md`, read once	2,277	2,327
Codex over the CLI, one task, median of five	83,184	83,169
Codex over MCP, the same task, median of five	47,569	47,879

The task was "find the command that generates an image with Image Model 5, and the flags it requires". Every tool loaded costs less because the paid tools' repeated parts, such as a source image and its URL, are now written once and referred to. Over the CLI, every run read the general help first and carried it through each later step: 3.0.0's is 59 tokens longer, for which, install, the flags and the exit codes it now lists, and its which answer is shorter than the command list that every 2.0.1 run read next. Over MCP, Codex prints its own TypeScript rendering of the tool list and leaves out the argument comments of a tool whose schema is large: generative_expand's shared schema is now small enough to print with them, about 300 more tokens that each later request carries, while every other paid tool prints shorter. SKILL.md costs 50 more because it now says how approval works over MCP and lists every exit code.

Tool-list bytes or characters divided by four are not API usage, no other offering was measured, and no live Adobe generation ran.

Claude Code can defer full tool definitions with MCP tool search. A client that eagerly loads everything behaves differently. A CLI skill also has a recurring description when installed.

For a complete task, use the same request, permissions, selected result fields and completion behavior. Report input/output tokens, latency, retries and Adobe credits separately. Schema overhead alone is not the full bill.

To reduce standing context, disconnect an unused MCP server, keep tool search enabled in clients that support it, or use FIREFLY_READ_ONLY=1 to expose only the three reading tools. --select reduces result text; it does not change Adobe's generation credit usage.

8. Every tool and argument

There are 14 tools: three reads, one upload and ten paid media operations. Every paid operation requires confirmation. The tables below come from the running server's input schemas, rather than a separately maintained tool list.

Image/source arguments that have a URL alias accept either the nested source object or that alias. The Adobe body still requires the image where its operation specifies one.

Images

MCP tool	CLI command	What it does	Kind
`generate_image`	`firefly-cli generate-image`	Generate images	Uses credits; confirmation required
`generate_image5`	`firefly-cli generate-image5`	Generate images with Image5	Uses credits; confirmation required
`generate_similar`	`firefly-cli generate-similar`	Generate similar images	Uses credits; confirmation required
`generative_fill`	`firefly-cli generative-fill`	Fill image	Uses credits; confirmation required
`generative_expand`	`firefly-cli generative-expand`	Expand image	Uses credits; confirmation required
`upscale_image`	`firefly-cli upscale-image`	Upscale image	Uses credits; confirmation required

`generate_image`

Generate images. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

Argument	Type	Required	What it does
`contentClass`	string	No	Directs the style of a generated image to be photographic or like fine art. Values: `photo`, `art`
`customModelId`	string	No	Include the specific custom model ID when a custom model type is designated in the `x-model-version` header parameter.
`negativePrompt`	string	No	A negative prompt of things Firefly will try to avoid generating in the image. Not supported for Firefly Custom Models on Image Model 3 or Firefly Custom Models on Image Model 4. Maximum length: 1024
`numVariations`	integer	No	The number of variations to generate. numVariations defaults to the number of seed images, or to 1 if you do not specify `seeds`. Minimum: 1. Maximum: 4
`prompt`	string	Yes	A text prompt to support the generation of an image. The longer the prompt the better Firefly performs. Minimum length: 1. Maximum length: 1024
`promptBiasingLocaleCode`	string	No	A hyphen-separated string combining the ISO 639-1 language code and the ISO 3166-1 region (like en-US). When a locale is set, the prompt will be biased to generate more relevant content for that region. If not specified, the locale will be auto-detected based on your profile and the accepted language header.
`seeds`	array of integer	No	An array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. For example, use the same seed to generate a similar image in different styles. If specified along with numVariations, the number of seeds provided must equal numVariations. Minimum items: 1. Maximum items: 4
`size`	object	No	The desired width and height for the final image, in pixels. Supported sizes for the output images with `image3` are: Square (1:1) - width 2048px, height 2048px Square (1:1) - width 1024px, height 1024px Landscape (4:3) - width 2304px, height 1792px Portrait (3:4) - width 1792px, height 2304px Widescreen (16:9) - width 2688px, height 1536px Widescreen (16:9) - width 2688px, height 1512px (7:4) - width 1344px, height 768px (7:4) - width 1344px, height 756px (9:7) - width 1152px, height 896px (7:9) - width 896px, height 1152px Supported sizes for the output images with `image4` are: (1:1) - width 2048px, height 2048px (4:3) - width 2304px, height 1792px (3:4) - width 1792px, height 2304px (16:9) - width 2688px, height 1536px (9:16) - width 1440px, height 2560px .
`structure`	object	No	An object with the reference image details for structure.
`style`	object	No	An object with the reference image details for style.
`upsamplerType`	string	No	Only supported with the model version `image4_custom`. The `default` setting upscales generated images to 2k. The `low_creativity` setting refines the image generation by removing distortions, smoothing textures, and sometimes adding details (like freckles to faces in close-up). This setting is recommended for generating images with human subjects. Values: `default`, `low_creativity`
`visualIntensity`	integer	No	Adjust the overall intensity of your photo's characteristics, such as contrast, shadow, and hue. This is not supported with the model version `image4_custom`. Minimum: 2. Maximum: 10
`confirm`	boolean	Yes	Must be true to spend Firefly Services credits for the operation the user requested.
`wait`	boolean	No	Wait for completion, default true. Set false to return the job immediately.
`download`	boolean	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`n`	integer	No	Compatibility alias for numVariations. Do not supply both. Minimum: 1. Maximum: 4
`width`	integer	No	Compatibility alias: provide together with height instead of size. Minimum: 1. Maximum: 4096
`height`	integer	No	Compatibility alias: provide together with width instead of size. Minimum: 1. Maximum: 4096

Exact schema: firefly-cli schema generate-image. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

`generate_image5`

Generate images with Image5. Image 5 supports natural-language edits through referenceBlobs. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

Argument	Type	Required	What it does
`prompt`	string	Yes	The prompt used to generate the image. The longer the prompt, the better. Minimum length: 1. Maximum length: 1500
`aspectRatio`	string	No	The aspect ratio of the requested generations. This controls the size of the generated image. When referenceBlobs is included in the request, this property should be omitted or set to auto. Values: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `auto`
`resolutionLevel`	string	No	The resolution level. Values: `1MP`, `2.4MP`, `4MP`
`modelId`	string	No	The specific model to use for image generation. Available options: 'firefly_image' for Firefly Image model. Values: `firefly_image`
`modelSpecificPayload`	object	No	Additional model-specific parameters for controlling the generation process.
`numVariations`	integer	No	The number of image variations to generate. Greater than 1 is not supported. Only one image per variation is allowed. For multiple variations, send separate requests. Maximum: 1
`referenceBlobs`	array of object	No	List of reference blobs that will be used as additional input for the generation process. Only one reference image is supported. When this array is not empty, aspectRatio must be omitted or set to auto. Pre-signed URLs can be used from supported domains. Maximum items: 1
`seeds`	array of integer	No	The seed value to vary the image generation. Only one seed per variation is allowed. If specified alongside with numVariations, the number of seeds must be equal to numVariations. Maximum items: 1
`confirm`	boolean	Yes	Must be true to spend Firefly Services credits for the operation the user requested.
`wait`	boolean	No	Wait for completion, default true. Set false to return the job immediately.
`download`	boolean	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`n`	integer	No	Compatibility alias for numVariations. Do not supply both. Maximum: 1

Exact schema: firefly-cli schema generate-image5. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

`generate_similar`

Generate similar images. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

Argument	Type	Required	What it does
`image`	object	No	Firefly will create similar variations. Use a URL or an uploadID as the source for the image. Firefly only allows these listed domains: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .
`numVariations`	integer	No	Generate this number of variations. numVariations defaults to the number of seed images, or to 1 if you do not specify `seeds`. Minimum: 1. Maximum: 4
`seeds`	array of integer	No	Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. If specified along with numVariations, the number of seeds must equal numVariations. Minimum items: 1. Maximum items: 4
`size`	object	No	The desired width and height for the final image in pixels. The supported sizes for the output images are: Square (1:1) - width 2048px, height 2048px Square (1:1) - width 1024px, height 1024px Landscape (4:3) - width 2304px, height 1792px Portrait (3:4) - width 1792px, height 2304px Widescreen (16:9) - width 2688px, height 1536px (7:4) - width 1344px, height 768px (9:7) - width 1152px, height 896px (7:9) - width 896px, height 1152px .
`confirm`	boolean	Yes	Must be true to spend Firefly Services credits for the operation the user requested.
`wait`	boolean	No	Wait for completion, default true. Set false to return the job immediately.
`download`	boolean	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`n`	integer	No	Compatibility alias for numVariations. Do not supply both. Minimum: 1. Maximum: 4
`width`	integer	No	Compatibility alias: provide together with height instead of size. Minimum: 1. Maximum: 4096
`height`	integer	No	Compatibility alias: provide together with width instead of size. Minimum: 1. Maximum: 4096
`imageUrl`	string	No	Compatibility URL alias for image.source.url. Format: uri

Exact schema: firefly-cli schema generate-similar. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

`generative_fill`

Fill image. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

Argument	Type	Required	What it does
`image`	object	No	The image to expand. Use a URL or an uploadID as the source for the image. Firefly only allows these listed domains for input URLs in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .
`mask`	object	No	Required. Selected areas of a background image that Firefly uses to fill the source image.
`negativePrompt`	string	No	An optional text prompt up to 1024 characters. Avoid these characteristics in the generated image. Not supported for Firefly Custom Models on Image Model 3 or Firefly Custom Models on Image Model 4. Maximum length: 1024
`numVariations`	integer	No	Generate this number of variations. numVariations defaults to the number of seed images, or to 1 if you do not specify seeds. Minimum: 1. Maximum: 4
`prompt`	string	No	An optional text prompt up to 1024 characters. The longer the prompt the better Firefly performs. Minimum length: 1. Maximum length: 1024
`promptBiasingLocaleCode`	string	No	A hyphen-separated string combining the ISO 639-1 language code and the ISO 3166-1 region, such as en-US. When a locale is set, the prompt will be biased to generate more relevant content for that region. The locale will be auto-detected if not specified based on your profile and the accepted language header.
`seeds`	array of integer	No	Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. For example, you can use the same seed to generate a similar image with different styles. If specified along with numVariations, the number of seeds must equal numVariations. Minimum items: 1. Maximum items: 4
`size`	object	No	The desired width and height for the final expanded image in pixels. The supported sizes for the output images are: Square (1:1) - width 2048px, height 2048px Square (1:1) - width 1024px, height 1024px Landscape (4:3) - width 2304px, height 1792px Portrait (3:4) - width 1792px, height 2304px Widescreen (16:9) - width 2688px, height 1536px (7:4) - width 1344px, height 768px (9:7) - width 1152px, height 896px (7:9) - width 896px, height 1152px .
`confirm`	boolean	Yes	Must be true to spend Firefly Services credits for the operation the user requested.
`wait`	boolean	No	Wait for completion, default true. Set false to return the job immediately.
`download`	boolean	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`n`	integer	No	Compatibility alias for numVariations. Do not supply both. Minimum: 1. Maximum: 4
`width`	integer	No	Compatibility alias: provide together with height instead of size. Minimum: 1. Maximum: 4096
`height`	integer	No	Compatibility alias: provide together with width instead of size. Minimum: 1. Maximum: 4096
`imageUrl`	string	No	Compatibility URL alias for image.source.url. Format: uri
`maskUrl`	string	No	Compatibility URL alias for mask.source.url. Format: uri

Exact schema: firefly-cli schema generative-fill. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

`generative_expand`

Expand image. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

Argument	Type	Required	What it does
`image`	object	No	The image to expand. Use a URL or an uploadID as the source for the image. Firefly only allows these listed domains for input URLs in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .
`mask`	object	No	Mask image which will be used to expand the given image.
`numVariations`	integer	No	Generate this number of variations. numVariations defaults to the number of seed images, or to 1 if you do not specify seeds. Minimum: 1. Maximum: 4
`placement`	object	No	The position of the source image after Firefly resizes it. The value describes the horizontal and vertical placement and dimensions of the image in the output. Note you cannot use placement for source images when you also apply a mask image.
`prompt`	string	No	An optional text prompt up to 1024 characters. The longer the prompt the better Firefly performs. Minimum length: 1. Maximum length: 1024
`seeds`	array of integer	No	Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. For example, you can use the same seed to generate a similar image with different styles. If specified along with numVariations, the number of seeds must equal numVariations. Minimum items: 1. Maximum items: 4
`size`	object	No	The desired width and height for the final expanded image in pixels. The maximum size for the output images is 3999px by 3999px.
`confirm`	boolean	Yes	Must be true to spend Firefly Services credits for the operation the user requested.
`wait`	boolean	No	Wait for completion, default true. Set false to return the job immediately.
`download`	boolean	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`n`	integer	No	Compatibility alias for numVariations. Do not supply both. Minimum: 1. Maximum: 4
`width`	integer	No	Compatibility alias: provide together with height instead of size. Minimum: 1. Maximum: 4096
`height`	integer	No	Compatibility alias: provide together with width instead of size. Minimum: 1. Maximum: 4096
`imageUrl`	string	No	Compatibility URL alias for image.source.url. Format: uri
`maskUrl`	string	No	Compatibility URL alias for mask.source.url. Format: uri

Exact schema: firefly-cli schema generative-expand. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

`upscale_image`

Upscale image. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

Argument	Type	Required	What it does
`image`	object	No	The input image for the upsampler (source uploadId or url).
`seeds`	array of integer	Yes	The seed for each variation. Provide one seed per output (1–4 seeds). Minimum items: 1. Maximum items: 4
`upscaleFactor`	integer	No	The upscale factor (2, 3, 4, or 6). Output dimensions are input dimensions multiplied by this factor. Values: `2`, `3`, `4`, `6`
`confirm`	boolean	Yes	Must be true to spend Firefly Services credits for the operation the user requested.
`wait`	boolean	No	Wait for completion, default true. Set false to return the job immediately.
`download`	boolean	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`imageUrl`	string	No	Compatibility URL alias for image.source.url. Format: uri

Exact schema: firefly-cli schema upscale-image. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

Composites

MCP tool	CLI command	What it does	Kind
`generate_object_composite`	`firefly-cli generate-object-composite`	Generate object composite	Uses credits; confirmation required
`precise_composite`	`firefly-cli precise-composite`	Generate precise composite	Uses credits; confirmation required
`adaptive_composite`	`firefly-cli adaptive-composite`	Generate adaptive composite	Uses credits; confirmation required

`generate_object_composite`

Generate object composite. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

Argument	Type	Required	What it does
`contentClass`	string	No	The content class of the image. Values: `photo`, `art`
`image`	object	No	The image to expand. Use a URL or an uploadID as the source for the image. Firefly only allows these listed domains for input URLs in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .
`mask`	object	No	Selected areas of a background image that Firefly uses to fill the source image.
`numVariations`	integer	No	Generate this number of variations. Defaults to the number of seed images, or to 1 if you do not specify seeds. Minimum: 1. Maximum: 4
`placement`	object	No	The position of the source image after Firefly adjusts it. The value describes the horizontal and vertical placement and dimensions of the image in the output. Note you cannot use placement for source images when you also apply a mask image.
`prompt`	string	Yes	A text prompt up to 1024 characters. The longer the prompt the better Firefly performs. Minimum length: 1. Maximum length: 1024
`seeds`	array of integer	No	Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. If specified along with numVariations, the number of seeds must equal numVariations. Minimum items: 1. Maximum items: 4
`size`	object	No	The desired width and height for the final image in pixels. The supported sizes for the output images are: Square (1:1) - width 2048px, height 2048px Square (1:1) - width 1024px, height 1024px Landscape (4:3) - width 2304px, height 1792px Portrait (3:4) - width 1792px, height 2304px Widescreen (16:9) - width 2688px, height 1536px (7:4) - width 1344px, height 768px (9:7) - width 1152px, height 896px (7:9) - width 896px, height 1152px .
`style`	object	No	See the exact structure with schema for this command.
`confirm`	boolean	Yes	Must be true to spend Firefly Services credits for the operation the user requested.
`wait`	boolean	No	Wait for completion, default true. Set false to return the job immediately.
`download`	boolean	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`n`	integer	No	Compatibility alias for numVariations. Do not supply both. Minimum: 1. Maximum: 4
`width`	integer	No	Compatibility alias: provide together with height instead of size. Minimum: 1. Maximum: 4096
`height`	integer	No	Compatibility alias: provide together with width instead of size. Minimum: 1. Maximum: 4096
`imageUrl`	string	No	Compatibility URL alias for image.source.url. Format: uri
`maskUrl`	string	No	Compatibility URL alias for mask.source.url. Format: uri

Exact schema: firefly-cli schema generate-object-composite. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

`precise_composite`

Generate precise composite. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

Argument	Type	Required	What it does
`background`	object	Yes	Background image and fill area mask specifying object placement.
`object`	object	Yes	Object image to be placed on the background.
`numVariations`	integer	No	Number of output variations to generate. Minimum: 1. Maximum: 3
`seeds`	array of integer	No	Random seeds for each variation. Count must match numVariations if both are provided. Defaults: 1 variation → [333], 2 → [333, 222], 3 → [333, 222, 111]. Minimum items: 1. Maximum items: 3
`blend`	number	No	Controls blend between harmonized and original object appearance (0.0 = fully harmonized, 1.0 = original preserved). Minimum: 0. Maximum: 1. Format: float
`output`	object	No	Output format specification.
`confirm`	boolean	Yes	Must be true to spend Firefly Services credits for the operation the user requested.
`wait`	boolean	No	Wait for completion, default true. Set false to return the job immediately.
`download`	boolean	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`n`	integer	No	Compatibility alias for numVariations. Do not supply both. Minimum: 1. Maximum: 3

Exact schema: firefly-cli schema precise-composite. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

`adaptive_composite`

Generate adaptive composite. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

Argument	Type	Required	What it does
`background`	object	Yes	Background image and fill area mask.
`object`	object	Yes	Object image and optional mask.
`numVariations`	integer	No	Number of output variations to generate. Minimum: 1. Maximum: 3
`seeds`	array of integer	No	Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. If specified alongside numVariations, the number of seeds must equal numVariations. Defaults: 1 variation → [333], 2 → [333, 222], 3 → [333, 222, 111]. Minimum items: 1. Maximum items: 3
`harmonization`	number	No	Controls how much the object's colors and lighting are adjusted to match the background scene. Minimum: 0. Maximum: 1. Format: float
`shadowIntensity`	number	No	Controls shadow intensity in the composited result. Lower values reduce shadow. Minimum: 0. Maximum: 1. Format: float
`preserveBackground`	boolean	No	When true, preserves original background details within the masked area during compositing.
`output`	object	No	Output format specification.
`confirm`	boolean	Yes	Must be true to spend Firefly Services credits for the operation the user requested.
`wait`	boolean	No	Wait for completion, default true. Set false to return the job immediately.
`download`	boolean	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`n`	integer	No	Compatibility alias for numVariations. Do not supply both. Minimum: 1. Maximum: 3

Exact schema: firefly-cli schema adaptive-composite. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

Video

MCP tool	CLI command	What it does	Kind
`generate_video`	`firefly-cli generate-video`	Generate video	Uses credits; confirmation required

`generate_video`

Generate video. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

Argument	Type	Required	What it does
`bitRateFactor`	integer	No	The constant rate factor for encoding video. 0 indicates a lossless generation, with the highest quality and largest file size. 63 indicates the worst quality generation with the smallest file size. The suggested value range is 17-23. Minimum: 0. Maximum: 63
`image`	object	No	The details of the image used as a keyframe for the generated video. Provided images are used as a first frame or final frame to guide the video generation.
`prompt`	string	No	The prompt used to generate the video. The longer the prompt, the better.
`seeds`	array of integer	No	The seed reference value. Currently only 1 seed is supported. Minimum items: 1. Maximum items: 1
`sizes`	array of object	No	The dimensions of the generated video. Consult the supported aspect ratios in the usage notes for allowed values.
`videoSettings`	object	No	The camera and shot control settings.
`confirm`	boolean	Yes	Must be true to spend Firefly Services credits for the operation the user requested.
`wait`	boolean	No	Wait for completion, default true. Set false to return the job immediately.
`download`	boolean	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.

Exact schema: firefly-cli schema generate-video. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

References

MCP tool	CLI command	What it does	Kind
`upload_image`	`firefly-cli upload-image`	Upload a reference image	Uploads

`upload_image`

Upload a local JPEG, PNG, WebP, TIFF or JXL image, up to 15 MB. Returns an uploadId, valid for seven days. File content is sent to Adobe.

Argument	Type	Required	What it does
`filePath`	string	Yes	Local image path on the computer running this server. Minimum length: 1

Exact schema: firefly-cli schema upload-image. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

Jobs

MCP tool	CLI command	What it does	Kind
`get_job_status`	`firefly-cli get-job-status`	Read an async job	Reads

`get_job_status`

Read an existing Adobe async job by jobId. Use after a polling timeout instead of submitting generation again.

Argument	Type	Required	What it does
`jobId`	string	Yes	Job ID or URN returned by Adobe. Minimum length: 1

Exact schema: firefly-cli schema get-job-status. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

Account

MCP tool	CLI command	What it does	Kind
`verify_credentials`	`firefly-cli verify-credentials`	Verify authentication	Reads
`list_custom_models`	`firefly-cli list-custom-models`	List available custom models	Reads

`verify_credentials`

Check OAuth by exchanging credentials, or validate an existing access token through a custom-model API read. Does not generate media, prove generation entitlement or reveal tokens.

Argument	Type	Required	What it does
None	None	No	Run without tool arguments

Exact schema: firefly-cli schema verify-credentials. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

`list_custom_models`

Read custom models available to the Adobe project. FIREFLY_USER_TOKEN is optional for user-specific access. Returns a page; use start and limit to continue.

Argument	Type	Required	What it does
`sortBy`	string	No	Values: `assetName`, `createdDate`, `modifiedDate`, `-assetName`, `-createdDate`, `-modifiedDate`
`start`	integer	No	Minimum: 0
`limit`	integer	No	Minimum: 1. Maximum: 50
`publishedState`	string	No	Values: `all`, `ready`, `published`, `unpublished`, `queued`, `training`, `failed`, `cancelled`

Exact schema: firefly-cli schema list-custom-models. Nested objects use one quoted JSON object; arrays of objects use one repeated flag per object.

9. Image, editing and video workflows

Generate with Image Model 5

firefly-cli generate-image5 --prompt "A ceramic cup in warm morning light" --aspectRatio 1:1 --resolutionLevel 4MP --agent --confirm

Image 5 uses /v4/images/generate-async and x-model-version: image5. Its request differs from the v3 image endpoint: inspect firefly-cli schema generate-image5. The reviewed schema accepts one variation per request.

Upload a reference, then instruct an edit

firefly-cli upload-image --filePath /absolute/path/reference.png --agent
firefly-cli generate-image5 --prompt "Change the background to a soft blue studio wall" --referenceBlobs '{"source":{"uploadId":"UPLOAD_ID_FROM_PREVIOUS_RESULT"},"usage":"general"}' --agent --confirm

Replace the placeholder with the returned upload ID. An Image 5 reference edit requires aspectRatio omitted or auto. Upload IDs expire after seven days. Image URLs must use the storage providers Adobe accepts, described in its usage notes.

Fill a masked region

firefly-cli generative-fill --prompt "A small green plant" --image '{"source":{"uploadId":"SOURCE_UPLOAD_ID"}}' --mask '{"source":{"uploadId":"MASK_UPLOAD_ID"}}' --agent --confirm

image and mask describe separate sources. The corrected endpoint is /v3/images/fill-async. Keep the mask interpretation consistent with Adobe's current operation docs.

Submit video without waiting

firefly-cli generate-video --prompt "Slow camera movement through a sunlit forest" --wait=false --agent --confirm
firefly-cli get-job-status --jobId JOB_ID_FROM_RESULT --agent

The API generates a five-second video. Video uses x-model-version: video1_standard; sizes and keyframes follow the generated schema. A timeout can mean the operation is still running. Check its job before submitting again.

Upscale or composite

firefly-cli upscale-image --image '{"source":{"uploadId":"SOURCE_UPLOAD_ID"}}' --seeds 333 --upscaleFactor 2 --agent --confirm
firefly-cli precise-composite --help
firefly-cli adaptive-composite --help

Use precise_composite or adaptive_composite when you supply both a background and an object. generate_object_composite generates a scene around the product image and uses a different schema. Do not interchange their request structures.

Optional downloads

Pass --download on a media command to save completed outputs under FIREFLY_OUTPUT_DIR, defaulting to ~/outputs/images. Downloads default off and need wait=true. Each filename is unique, so multiple variations do not overwrite one another. URLs and optional downloaded_to paths are returned as data; images and videos are not printed as binary terminal output. Each downloaded output is limited to 250 MB.

Source object shapes

An uploaded image:

{"image":{"source":{"uploadId":"986e8b25-6d40-4c5c-b2e5-f0d0dbf8ac36"}}}

A presigned storage URL:

{"image":{"source":{"url":"https://YOUR_BUCKET.amazonaws.com/reference.png"}}}

Each source requires exactly one uploadId or HTTPS url. The UUID above is an example; use the real ID from your requested upload. Do not supply both source forms.

Image 5 reference editing uses a different wrapper:

firefly-cli generate-image5 --prompt "Change only the background to soft blue" --referenceBlobs '{"source":{"uploadId":"986e8b25-6d40-4c5c-b2e5-f0d0dbf8ac36"},"usage":"general"}' --aspectRatio auto --confirm --agent

Model and storage constraints

Operation/input	Constraint in the reviewed Adobe documentation
Image 5	One variation and at most one reference blob in the current operation schema
Image 5 with a reference	Omit aspectRatio or use auto
Image 5 request fields	Use its v4 fields; do not reuse v3-only negativePrompt or size
Video	Five-second output; provide a prompt or image conditions/keyframes
Seeds and variations	One seed per requested variation when both are supplied
Image upload	Nonempty JPEG, PNG, WebP, TIFF or JXL, at most 15 MB
Uploaded reference lifetime	Adobe documents seven days; upload again if expired
Presigned input URL	Use an Adobe-supported storage domain; a local path is not a URL
Local output download	Explicit opt-in, 250 MB cap, supported HTTPS storage host and no forwarded Adobe authorization

Some operations have narrower source-size requirements than the generic upload endpoint. Consult Adobe's usage notes and the specific operation before a composite.

Current documentation discrepancy

Adobe's Image 5 migration article and its current OpenAPI operation disagree about several fields. The reviewed v4 operation includes aspectRatio, resolutionLevel, modelId, modelSpecificPayload and referenceBlobs. This implementation validates against that operation and records its exact snapshot hash. The discrepancy still needs an authenticated live account test; see COMPARISON.md.

10. Jobs and local files

By default a media operation waits for completion and returns Adobe's JSON. --wait=false returns the accepted job immediately. Keep the job ID and read it with get-job-status.

firefly-cli generate-video --prompt "Slow movement through a sunlit forest" --wait=false --confirm --agent
firefly-cli get-job-status --jobId JOB_ID_FROM_ADOBE --agent

The client handles both statusUrl and links.result.href responses, plus outputs and result.outputs. Failed, cancelled and timed-out jobs are reported as failures.

A request timeout can occur after Adobe accepted a paid operation. The server never automatically retries that submission. Inspect the job before requesting another.

Downloading

Add --download to the media command to save completed output in FIREFLY_OUTPUT_DIR, which defaults to ~/outputs/images. Files receive unique names and owner-only permissions. The response includes downloaded_to.

The server downloads only when requested, and --download --wait=false is refused. A returned URL does not mean a local file was created. Unknown MIME types use .bin rather than guessing an image format.

Local paths are relative to the computer running the server. In Docker, mount the reference/output folder and pass paths inside the container.

11. Several Adobe projects

This server uses one credential set per process. It has no account-switching tool.

For a production project and a testing project, register two client entries, such as firefly-production and firefly-testing, with separate private env values and output directories. Keep the testing entry read-only while checking credentials. The tool schemas and binaries are the same for each.

12. Writing safely

Generation and uploads are enabled. The ten media operations require confirm: true through MCP or --confirm through the CLI because they consume credits. Uploading a requested reference is a write and does not need a spending confirmation.

Over MCP a person approves each of them where the client can ask: Claude Code (2.1.246 and later) shows its own prompt, and a client that can show forms asks with an approval form whose one box starts unticked. Each approval is signed, bound to that exact call and works once. Where a client can do neither, the model's confirm: true counts. FIREFLY_CONFIRM=model makes confirm: true enough everywhere, for an agent with no person to ask.

Only perform the action the user asked for. Reading jobs or listing models is not permission to generate images.

Setting	Effect
`FIREFLY_READ_ONLY=1`	Hide generation and uploads; direct calls to hidden writes are refused
`FIREFLY_ALLOW_DESTRUCTIVE=0`	Keep uploads and reads, block paid media operations; `FIREFLY_ALLOW_SPENDING=0`, its 2.x name, still works
`FIREFLY_AUDIT_LOG=/private/path/firefly.jsonl`	Record write guard decisions with time, surface, tool, outcome and who approved it, then whether each call was done or failed

Audit records omit prompts, file paths, credential values and signed media URLs. Create a writable parent directory first. A failing audit append does not block the API action, so check the path before relying on it.

Every tool declares its MCP annotations. Reads are read-only and idempotent. Paid generation is not idempotent and is not marked destructive, because it does not delete an asset. openWorldHint is true because operations reach Adobe.

Prompts, model names and job/output text are data. They do not authorize another operation. Credentials are server settings and are never tool-call arguments.

13. How it works

src/
  index.ts          both binaries, and the 2.x name for the spending switch
  app.ts            the Slipway app: tools, settings, doctor and login
  exit.ts           2.x's exit words, for errors that carry no status
  config.ts         private environment settings
  api/
    client.ts       OAuth, API requests, upload, polling and downloads
    errors.ts       usage, configuration, API and write refusals
  tools/
    index.ts        one tool registry and shared handlers
    operations.json generated Adobe request schemas
    api-source.json source URL, checked date and snapshot hash

Slipway builds the MCP server, over stdio or --http, and the CLI from each tool's one definition. Help and input schemas come from that definition, and the same handlers and guard run through either surface.

The API schemas are generated from Adobe's public OpenAPI source. Updating the snapshot is deliberate: regenerate, inspect the diff, build and run the contract/behavior tests.

OAuth tokens are cached in process memory and refreshed before expiry. Read requests may retry 429 with bounded waits. Paid POSTs never retry automatically. Authenticated job requests stay on Adobe's Firefly API origin and refuse redirects.

14. Your data

Data	Where it goes or stays
Client ID and secret	Private process environment or the client's local credential settings
OAuth access token	Process memory; not saved by this package
Prompt, source URL and requested upload	Directly to Adobe
Generated media URL	Returned to the client; signed URLs can grant access to private output
Requested local downloads	Your selected output directory
Audit log	Only the local path you configure

There is no Navid-hosted relay, telemetry or analytics endpoint.

Authentication contacts ims-na1.adobelogin.com. API requests contact firefly-api.adobe.io. Requested downloads may contact Adobe output storage within the supported Amazon S3, Azure, Google Cloud, Dropbox or Adobe host families. They never receive Adobe authentication headers.

Adobe's own Firefly Services documentation and service terms govern upstream processing. Review those before uploading confidential reference material.

15. Environment variables

Credentials

Variable	Default	Purpose
`FIREFLY_CLIENT_ID`	Empty	Firefly Services OAuth client ID
`FIREFLY_CLIENT_SECRET`	Empty	OAuth client secret
`FIREFLY_ACCESS_TOKEN`	Empty	Optional existing access token, replacing the secret
`FIREFLY_USER_TOKEN`	Empty	Optional user-level custom-model access
`FIREFLY_SCOPES`	Adobe tutorial scopes	Scope string from the provisioned project
`FIREFLY_SERVICES_CLIENT_ID`	Empty	Adobe tutorial alias for client ID
`FIREFLY_SERVICES_CLIENT_SECRET`	Empty	Adobe tutorial alias for client secret
`FIREFLY_SERVICES_ACCESS_TOKEN`	Empty	Adobe tutorial alias for access token

Safety

Variable	Default	Purpose
`FIREFLY_READ_ONLY`	Off	`1` or `true` hides generation and uploads
`FIREFLY_ALLOW_DESTRUCTIVE`	On	`0` or `false` blocks paid media generation
`FIREFLY_ALLOW_SPENDING`	On	2.x's name for `FIREFLY_ALLOW_DESTRUCTIVE`, still read when that one is unset
`FIREFLY_CONFIRM`	`human`	`model` lets `confirm: true` alone approve over MCP, for an agent with no person to ask
`FIREFLY_AUDIT_LOG`	Empty	Append guard decisions to this local path

Tuning

Variable	Default	Purpose
`FIREFLY_OUTPUT_DIR`	`~/outputs/images`	Folder for explicitly requested downloads
`FIREFLY_REQUEST_TIMEOUT_MS`	30000	Per-request deadline
`FIREFLY_POLL_TIMEOUT_MS`	300000	Maximum job polling duration
`FIREFLY_POLL_INTERVAL_MS`	2000	Interval between polls
`FIREFLY_SURFACE`	`full`	`search` lists three tools that find, describe and run the rest
`FIREFLY_TOOL_TIMEOUT_MS`	None	Give up on any tool after this long
`FIREFLY_HTTP_PORT`, `FIREFLY_HTTP_HOST`, `FIREFLY_HTTP_TOKEN`	8787, 127.0.0.1, none	For `--http`; any host but 127.0.0.1 needs the bearer token
`FIREFLY_HTTP_ALLOWED_ORIGINS`	None	Comma-separated browser origins allowed to call `--http`; a page from any other site is refused
`FIREFLY_DEBUG`	`0`	`1` prints debug lines on stderr

The program reads the environment directly. It does not automatically load .env files. Never commit real values in an environment file, client JSON or a desktop manifest.

16. Updates and removal

npm and client updates

Configs using npx -y @thenavidm/firefly-mcp-cli@latest resolve the current published version when they launch. Reconnect or restart the MCP client after an update.

npm install -g @thenavidm/firefly-mcp-cli@latest
firefly-cli --version

Global installs need that command to update. Desktop bundles are separate downloads: install the new .mcpb from the latest release through Extensions settings. Do not assume a manually installed custom bundle updates itself.

Every release is recorded in CHANGELOG.md. Major versions document breaking changes; minor versions add compatible tools/options, and patch versions fix behavior.

Migrating from the old MCP-only server

Keep the old tool names where supported, but change the package to @thenavidm/firefly-mcp-cli@latest. Node 22 is required. Paid media calls now need confirmation. Downloads now require an explicit flag.

n maps to numVariations where supported. width and height must be supplied together. Fill uses the current async endpoint. Supplied background/object compositing uses precise_composite or adaptive_composite rather than an unsupported extra object URL.

Remove it

npm uninstall -g @thenavidm/firefly-mcp-cli
claude mcp remove --scope user firefly

In other clients, remove the Firefly entry you added. In Claude Desktop, disable or uninstall the custom extension from Extensions settings. Remove private credential settings and revoke/rotate Adobe credentials if they are no longer needed.

Output images and audit logs are your files and are kept. Remove them yourself if desired.

17. Troubleshooting

Start with firefly-cli doctor, then doctor --network.

What you see	Likely cause	What to do
Exit 10 / credentials not configured	The server process has no usable credential set	Enter private local values; restart the client
401	Invalid or expired credentials/token	Rotate or replace them in Adobe Console/private settings
403	API entitlement, scopes or project permissions	Check the provisioned organization and operation access
429	Adobe rate or quota limit	Wait; do not repeatedly resubmit paid operations
Image 5 argument refused	v3 field or invalid reference ratio/variation	Use `schema generate-image5`; one variation; auto/omitted ratio with a reference
Source refused	Missing/both source forms, invalid UUID or URL	Provide exactly one uploadId or HTTPS URL
Upload not found, exit 3	Path points to a different machine/container	Use a path visible to the server process
Upload too large or wrong format	Generic upload limit or unsupported extension	Use a nonempty supported image no larger than 15 MB
Polling timeout	A job may still be running	Keep the original job ID and read it; do not submit again
Submission timed out	The paid outcome is unknown	Inspect the original operation before another request
Tools missing	Read-only mode or stale client connection	Check settings and reconnect
Local file missing	Download was not requested, or waiting was disabled	Use `--download` with a completed operation
Audit log empty	Unwritable/missing parent folder	Fix the local path before relying on the log
Desktop extension fails to start	Runtime/configuration or organization extension policy	Check Extensions logs and approved custom-extension settings
Node not found in a GUI app	GUI PATH differs from your terminal	Use an absolute Node path in manual configuration
Invalid JSON in client config	Missing comma or wrong root key	Validate locally; use the exact client block in INSTALL

Do not attach credential-bearing configs, OAuth response bodies, private prompts or signed output URLs to an issue.

18. API coverage and comparisons

The current implementation covers the ten media operations in the reviewed Adobe Firefly OpenAPI snapshot, plus upload, job status, authentication and custom-model reads. It is Firefly-specific and does not expose the Photoshop or Lightroom APIs.

Adobe supplies official APIs and SDKs. A dedicated Adobe-published Firefly task MCP/CLI was not identified in the reviewed documentation; that is a dated finding, not a claim that one cannot exist.

Community MCPs can offer broader services or remote deployment. COMPARISON.md records the actual sources, checked versions/claims, scope differences and outstanding matched-task measurements. Tool count alone does not prove broader coverage, lower token use or faster completion.

19. Versions

Version	What changed	Status
3.0.0	Built on Slipway: a person approves each paid operation over MCP, exit codes from Adobe's status, `which`, `install` and `--http`	3.0.0 release
2.0.0	14 tools, current Adobe schema coverage, CLI, desktop bundle, spending guard and complete setup	2.0.0 release
1.0.0	Seven MCP-only tools in the legacy implementation	Historical source

The release history lives in CHANGELOG.md, and downloads in GitHub Releases.

20. FAQ

MCP is the standard an AI client uses to discover and call outside tools. This server exposes Adobe Firefly operations so the client can act on an explicit request.

The CLI is the same tool registry as shell commands. Agents with a terminal, scripts and people can run it. Tool names use dashes in the command form.

Use MCP in a local AI chat and the CLI for shell workflows. Both share schemas and handlers. In Claude Code the CLI costs nothing until it is used, plus about 2,330 tokens for SKILL.md once, where the server costs about 380 tokens a message with tool search and 16,800 with every tool loaded. In Codex, finding the Image Model 5 command and its flags took a median of 83,169 input tokens over the CLI and 47,879 over MCP. Section 7 has how each was measured.

No. Navid Moazzez maintains this independent package against Adobe’s official API documentation. It is not endorsed by Adobe.

The package source is available under AGPL-3.0-or-later. Adobe API access and generation credits have separate costs, so installing it does not provide free generation.

Use OAuth Server-to-Server credentials from a provisioned Firefly Services project. A consumer subscription is not proof of API entitlement. Your Adobe password is never a tool setting.

Yes. The release carries a self-contained .mcpb extension. Configure its client ID and sensitive secret field locally. npm, MCP and desktop packaging use the same version.

generate_image5 uses the v4 operation with referenceBlobs. The current schema allows one variation and one reference; with a reference use auto or omit the ratio. Live account generation validation is pending.

generate_video uses Adobe’s documented five-second video operation. It accepts a prompt or image conditions. The source handles asynchronous job responses without automatically resubmitting.

No. It covers Firefly image and video operations. The comparison explains where other implementations expose those separate services.

No publish/delete tool is exposed. It can spend credits and upload requested references, so those changes still deserve deliberate authorization.

Every paid media tool refuses without confirm: true or --confirm, and over MCP a person approves each one where the client can ask. READ_ONLY hides writes and ALLOW_DESTRUCTIVE=0 blocks paid actions. The agent should pass confirmation only for the user’s requested action.

Uploads read a local path on the server’s machine. Requested downloads go to FIREFLY_OUTPUT_DIR or ~/outputs/images. A returned output URL alone does not create a local file.

No. Source, Git history and bundle scans are checked before publication. Credential examples are placeholders; actual values belong in private local settings or encrypted publishing secrets.

Use separate MCP entries/processes with distinct credentials and output folders. There is no account-switching tool inside this server.

Read the accepted job if you have its ID. A submission timeout can have an unknown paid outcome, so do not automatically request the same generation again.

npx configurations use @latest when they start. Global CLI installations need an npm update/install command. A manually installed custom desktop bundle must be updated through Extensions settings.

Only if that client can reach a local stdio server through its own supported integration. This package does not supply a remote HTTP URL for web-only connectors.

Build/typecheck, behavioral tests, native MCP discovery, guard/refusal behavior, a clean npm tarball installation and an unpacked desktop bundle. Live Adobe generation remains unverified; section 7 has the measured token costs.

Questions

Run into a problem or have a question? Open an issue and I will help.

Found a security vulnerability? Report it privately. SECURITY.md explains the credential and spending boundaries.

See CONTRIBUTING.md for the contribution policy.

About the author

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.

Links

Personal website: navid.me
Link in bio: navid.bio
Navid Media: navid.media
YouTube: @thenavidm and @thenavidai
X: @thenavidm
Instagram: @thenavidm
LinkedIn: thenavidm

If this is useful, star the repo and come say hi on X.

Dependencies

Library/source	License	What it does
Slipway	Apache-2.0	The MCP server and the CLI from one definition of each tool
MCP TypeScript SDK	Apache-2.0	The MCP protocol and its transports, through Slipway
Ajv	MIT	Validate the official JSON Schema request shapes
ajv-formats	MIT	URI, UUID and other field formats
Adobe Firefly OpenAPI documentation	Apache-2.0	Upstream operation schemas; original notices ship in licenses/

TypeScript, Vitest, JSON Schema Ref Parser and MCPB are build/test tools. The desktop bundle carries production runtime dependencies. THIRD_PARTY_NOTICES.md records attribution.

License

AGPL-3.0-or-later. Use, modification and redistribution are subject to its terms. Adobe schema material retains its original Apache-2.0 notices.

Not affiliated with, endorsed by or connected to Adobe Inc.

Available Tools

14 tools

adaptive_compositeGenerate adaptive compositeB

Generate adaptive composite. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

ParametersJSON Schema

Name	Required	Description
`n`	No	Compatibility alias for numVariations. Do not supply both.
`wait`	No	Wait for completion, default true. Set false to return the job immediately.
`seeds`	No	Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. If specified alongside numVariations, the number of seeds must equal numVariations. Defaults: 1 variation → [333], 2 → [333, 222], 3 → [333, 222, 111].
`object`	Yes	Object image and optional mask.
`output`	No	Output format specification.
`confirm`	No	Set true only when the user asked for exactly this action.
`download`	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`background`	Yes	Background image and fill area mask.
`harmonization`	No	Controls how much the object's colors and lighting are adjusted to match the background scene.
`numVariations`	No	Number of output variations to generate.
`shadowIntensity`	No	Controls shadow intensity in the composited result. Lower values reduce shadow.
`preserveBackground`	No	When true, preserves original background details within the masked area during compositing.

TDQS

B3.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds genuinely new context beyond those: it consumes Firefly Services credits (cost), returns Adobe output URLs, and toggles sync/async via wait. It does not explain the cost magnitude or confirm-gating, but it is well above the annotation-only baseline.

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

Conciseness4/5

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

Three short sentences, front-loaded and waste-free apart from the opening sentence that merely repeats the tool title. Each remaining sentence carries distinct information (cost, return shape, async option).

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

Completeness3/5

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

For a 12-parameter tool with deep nested objects and no output schema, the description usefully compensates on the return side ('returns Adobe output URLs'). However, it omits essential call-shaping context: that confirm must be true for this action, that download requires wait=true, and any hint about the required background/object/mask pairing.

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

Parameters3/5

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

With schema description coverage at 100%, the schema already documents all 12 parameters (wait, confirm, download, harmonization, shadowIntensity, etc.). The description only echoes the wait parameter and adds nothing about the required background/object structure or the n/numVariations alias rule. Baseline 3 is correct when the schema carries the full load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description restates the title ("Generate adaptive composite") and then adds three concrete behaviors: credit consumption, Adobe output URLs, and the wait=false async path. It does not distinguish this tool from close siblings like generate_object_composite or precise_composite, which is the main gap, so it lands at minimum-viable clarity rather than a 4.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance is given relative to the several compositing siblings (generate_object_composite, precise_composite, generative_fill). The only routing hint is 'Set wait=false to return an async job,' which is a mode switch, not tool selection. The confirm parameter's instruction to set true 'only when the user asked for exactly this action' lives in the schema, not the description.

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

generate_imageGenerate imagesB

Generate images. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

ParametersJSON Schema

Name	Required	Description	Default
`n`	No	Compatibility alias for numVariations. Do not supply both.
`size`	No	The desired width and height for the final image, in pixels. Supported sizes for the output images with `image3` are: Square (1:1) - width 2048px, height 2048px Square (1:1) - width 1024px, height 1024px Landscape (4:3) - width 2304px, height 1792px Portrait (3:4) - width 1792px, height 2304px Widescreen (16:9) - width 2688px, height 1536px Widescreen (16:9) - width 2688px, height 1512px (7:4) - width 1344px, height 768px (7:4) - width 1344px, height 756px (9:7) - width 1152px, height 896px (7:9) - width 896px, height 1152px Supported sizes for the output images with `image4` are: (1:1) - width 2048px, height 2048px (4:3) - width 2304px, height 1792px (3:4) - width 1792px, height 2304px (16:9) - width 2688px, height 1536px (9:16) - width 1440px, height 2560px .
`wait`	No	Wait for completion, default true. Set false to return the job immediately.
`seeds`	No	An array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. For example, use the same seed to generate a similar image in different styles. If specified along with numVariations, the number of seeds provided must equal numVariations.
`style`	No	An object with the reference image details for style.
`width`	No	Compatibility alias: provide together with height instead of size.
`height`	No	Compatibility alias: provide together with width instead of size.
`prompt`	Yes	A text prompt to support the generation of an image. The longer the prompt the better Firefly performs.
`confirm`	No	Set true only when the user asked for exactly this action.
`download`	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`structure`	No	An object with the reference image details for structure.
`contentClass`	No	Directs the style of a generated image to be photographic or like fine art.
`customModelId`	No	Include the specific custom model ID when a custom model type is designated in the `x-model-version` header parameter.
`numVariations`	No	The number of variations to generate. numVariations defaults to the number of seed images, or to 1 if you do not specify `seeds`.
`upsamplerType`	No	Only supported with the model version `image4_custom`. The `default` setting upscales generated images to 2k. The `low_creativity` setting refines the image generation by removing distortions, smoothing textures, and sometimes adding details (like freckles to faces in close-up). This setting is recommended for generating images with human subjects.	default
`negativePrompt`	No	A negative prompt of things Firefly will try to avoid generating in the image. Not supported for Firefly Custom Models on Image Model 3 or Firefly Custom Models on Image Model 4.
`visualIntensity`	No	Adjust the overall intensity of your photo's characteristics, such as contrast, shadow, and hue. This is not supported with the model version `image4_custom`.
`promptBiasingLocaleCode`	No	A hyphen-separated string combining the ISO 639-1 language code and the ISO 3166-1 region (like en-US). When a locale is set, the prompt will be biased to generate more relevant content for that region. If not specified, the locale will be auto-detected based on your profile and the accepted language header.

TDQS

B3.1/5.0

Behavior4/5

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

Annotations already declare non-read-only, open-world, non-idempotent behavior, so the description's added value is real: it discloses that the call consumes Firefly Services credits (a cost signal absent from the annotations) and that the return is Adobe output URLs. It also explains the async mode triggered by wait=false. It does not mention auth/credential requirements, which is the remaining gap.

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

Conciseness4/5

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

Four short sentences, front-loaded, and the cost and return-format facts appear early. The opening 'Generate images.' is pure name/title restatement and earns little, but nothing else is wasted.

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

Completeness3/5

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

With 18 parameters, nested objects, no output schema, and two enum-bearing params, the description covers the return shape and cost but omits the model-selection context that would separate this tool from generate_image5 and the other generation siblings. Adequate but with a clear routing gap.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already carries full parameter meaning (prompt, size, seeds, style, numVariations, upsamplerType, etc.). The description's only parameter-level contribution is restating wait=false async behavior, which the schema already documents. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Generate images'), but that is essentially a restatement of the name and title, and it does nothing to distinguish this tool from closely named siblings such as generate_image5, generate_similar, or generate_video. An agent cannot tell from the description which image-generation entry point is the right one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only usage direction is 'Set wait=false to return an async job.' There is no statement of when to choose this over generate_image5 or generate_similar, nor any prerequisite or exclusion guidance. For a toolbox with six image-generation siblings, this is a significant gap.

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

generate_image5Generate images with Image5B

Generate images with Image5. Image 5 supports natural-language edits through referenceBlobs. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

ParametersJSON Schema

Name	Required	Description	Default
`n`	No	Compatibility alias for numVariations. Do not supply both.
`wait`	No	Wait for completion, default true. Set false to return the job immediately.
`seeds`	No	The seed value to vary the image generation. Only one seed per variation is allowed. If specified alongside with numVariations, the number of seeds must be equal to numVariations.
`prompt`	Yes	The prompt used to generate the image. The longer the prompt, the better.
`confirm`	No	Set true only when the user asked for exactly this action.
`modelId`	No	The specific model to use for image generation. Available options: 'firefly_image' for Firefly Image model.
`download`	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`aspectRatio`	No	The aspect ratio of the requested generations. This controls the size of the generated image. When referenceBlobs is included in the request, this property should be omitted or set to auto.
`numVariations`	No	The number of image variations to generate. Greater than 1 is not supported. Only one image per variation is allowed. For multiple variations, send separate requests.
`referenceBlobs`	No	List of reference blobs that will be used as additional input for the generation process. Only one reference image is supported. When this array is not empty, aspectRatio must be omitted or set to auto. [Pre-signed URLs can be used from supported domains](https://developer.adobe.com/firefly-services/docs/firefly-api/getting-started/usage-notes/#image-api-usage).
`resolutionLevel`	No	The resolution level.	2.4MP
`modelSpecificPayload`	No	Additional model-specific parameters for controlling the generation process.

TDQS

B3.4/5.0

Behavior4/5

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

Beyond the annotations (readOnly=false, destructive=false, openWorld=true, idempotent=false), the description discloses three genuinely useful traits: it consumes Firefly Services credits, it returns Adobe output URLs, and wait=false produces an async job. Cost consumption and async semantics are exactly the kind of context annotations cannot convey, though rate limits or failure behavior are not covered.

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

Conciseness4/5

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

Four short sentences with no filler, and the core purpose is front-loaded. It is efficient, though the trailing sentences read as a compressed feature list rather than a prioritized statement.

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

Completeness3/5

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

For a 12-parameter tool with nested objects and no output schema, the description usefully notes that Adobe output URLs are returned and that async is available, partly compensating for the missing output schema. However, it is silent on most parameters (seeds, n, download, confirm, resolutionLevel, modelSpecificPayload) and on how the async job is later retrieved, leaving real gaps for a tool of this complexity.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 12 parameters including referenceBlobs, wait, and prompt. The description only restates the referenceBlobs editing capability and the wait flag, adding no syntax, constraints, or defaults beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Generate images with Image5') and adds a distinguishing capability note ('Image 5 supports natural-language edits through referenceBlobs'). It does not, however, differentiate itself from the sibling generate_image or generate_similar, so an agent must guess which generation tool to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description never states when to choose this tool over the ten sibling generation tools (generate_image, generate_similar, generative_fill, etc.). 'Set wait=false to return an async job' is an invocation detail, not a selection criterion, and no prerequisites or exclusions are given.

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

generate_object_compositeGenerate object compositeC

Generate object composite. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

ParametersJSON Schema

Name	Required	Description
`n`	No	Compatibility alias for numVariations. Do not supply both.
`mask`	No	Selected areas of a background image that Firefly uses to fill the source image.
`size`	No	The desired width and height for the final image in pixels. The supported sizes for the output images are: Square (1:1) - width 2048px, height 2048px Square (1:1) - width 1024px, height 1024px Landscape (4:3) - width 2304px, height 1792px Portrait (3:4) - width 1792px, height 2304px Widescreen (16:9) - width 2688px, height 1536px (7:4) - width 1344px, height 768px (9:7) - width 1152px, height 896px (7:9) - width 896px, height 1152px .
`wait`	No	Wait for completion, default true. Set false to return the job immediately.
`image`	No	The image to expand. Use a URL or an uploadID as the source for the image. Firefly only allows these listed domains for input URLs in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .
`seeds`	No	Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. If specified along with numVariations, the number of seeds must equal numVariations.
`style`	No
`width`	No	Compatibility alias: provide together with height instead of size.
`height`	No	Compatibility alias: provide together with width instead of size.
`prompt`	Yes	A text prompt up to 1024 characters. The longer the prompt the better Firefly performs.
`confirm`	No	Set true only when the user asked for exactly this action.
`maskUrl`	No	Compatibility URL alias for mask.source.url.
`download`	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`imageUrl`	No	Compatibility URL alias for image.source.url.
`placement`	No	The position of the source image after Firefly adjusts it. The value describes the horizontal and vertical placement and dimensions of the image in the output. Note you cannot use placement for source images when you also apply a mask image.
`contentClass`	No	The content class of the image.
`numVariations`	No	Generate this number of variations. Defaults to the number of seed images, or to 1 if you do not specify seeds.

TDQS

C2.8/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false but say nothing about cost or response shape. The description adds two genuinely useful facts beyond that: it consumes Firefly Services credits, and it returns Adobe output URLs, plus the async escape hatch via wait=false. It does not contradict the annotations, but it omits auth/rate-limit context.

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

Conciseness4/5

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

Four short, front-loaded sentences with no padding or repetition. It is efficient, though its brevity is partly under-specification rather than disciplined concision.

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

Completeness2/5

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

For a 17-parameter composite tool with deep nesting, a credits cost, an async mode, and three near-identical composite siblings, the description is far too thin. It does not explain what distinguishes 'object composite' from precise/adaptive compositing, nor how placement/mask interact, which is left entirely to the schema.

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

Parameters3/5

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

Schema description coverage is 94%, so all 17 parameters (including the many compatibility aliases, size presets, and the deprecated image.mask) are already documented in the schema. The description mentions only wait=false, adding nothing further. Baseline 3 is appropriate when the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence 'Generate object composite' is a verbatim restatement of the tool title/name, adding no distinguishing detail. With siblings like precise_composite and adaptive_composite in the same family, the description gives an agent no basis to tell them apart. This is essentially tautological.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 precise_composite, adaptive_composite, or generative_fill. The only operational note ('Set wait=false to return an async job') is a behavior hint, not a usage condition. The agent must infer routing entirely from the name and schema.

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

generate_similarGenerate similar imagesB

Generate similar images. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

ParametersJSON Schema

Name	Required	Description
`n`	No	Compatibility alias for numVariations. Do not supply both.
`size`	No	The desired width and height for the final image in pixels. The supported sizes for the output images are: Square (1:1) - width 2048px, height 2048px Square (1:1) - width 1024px, height 1024px Landscape (4:3) - width 2304px, height 1792px Portrait (3:4) - width 1792px, height 2304px Widescreen (16:9) - width 2688px, height 1536px (7:4) - width 1344px, height 768px (9:7) - width 1152px, height 896px (7:9) - width 896px, height 1152px .
`wait`	No	Wait for completion, default true. Set false to return the job immediately.
`image`	No	Firefly will create similar variations. Use a URL or an uploadID as the source for the image. Firefly only allows these listed domains: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .
`seeds`	No	Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. If specified along with numVariations, the number of seeds must equal numVariations.
`width`	No	Compatibility alias: provide together with height instead of size.
`height`	No	Compatibility alias: provide together with width instead of size.
`confirm`	No	Set true only when the user asked for exactly this action.
`download`	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`imageUrl`	No	Compatibility URL alias for image.source.url.
`numVariations`	No	Generate this number of variations. numVariations defaults to the number of seed images, or to 1 if you do not specify `seeds`.

TDQS

B3.2/5.0

Behavior3/5

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false — so the agent knows this is a non-destructive, non-idempotent, open-world write. The description adds that it consumes credits and returns Adobe output URLs, which is helpful context beyond annotations. However, it lacks details on rate limits, required permissions, or error behavior.

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

Conciseness4/5

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

The description is four short sentences, front-loaded with the purpose, and each sentence adds some value (credit consumption, output URLs, async option). It's efficient but could be more structured by grouping related behavioral notes.

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

Completeness3/5

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

For a complex tool with 11 parameters (nested objects, compatibility aliases) and no output schema, the description is minimal. It omits critical context: that an input image is required (despite no required parameters in schema), how the output is delivered, and the implications of async vs. wait. An agent could call it incorrectly without knowing an image source is mandatory in practice.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all 11 parameters thoroughly, including defaults and constraints. The description only adds one parameter hint ('Set wait=false'), which is redundant with the schema's description of 'wait'. Baseline 3 is appropriate when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Generate similar images') that distinguishes it from siblings like generate_image and generative_expand. However, it doesn't clarify the crucial distinction that this tool *requires* an input image to create variations, whereas generate_image likely creates from scratch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions 'Set wait=false to return an async job' which is a parameter instruction, not usage guidance. There's no indication of when to use this versus generate_image or generative_expand, no prerequisites (like needing an uploaded image), and no alternatives named.

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

generate_videoGenerate videoA

Generate video. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

ParametersJSON Schema

Name	Required	Description
`wait`	No	Wait for completion, default true. Set false to return the job immediately.
`image`	No	The details of the image used as a keyframe for the generated video. Provided images are used as a first frame or final frame to guide the video generation.
`seeds`	No	The seed reference value. Currently only 1 seed is supported.
`sizes`	No	The dimensions of the generated video. Consult the [supported aspect ratios in the usage notes](https://developer.adobe.com/firefly-services/docs/firefly-api/getting-started/usage-notes/#supported-aspect-ratios) for allowed values.
`prompt`	No	The prompt used to generate the video. The longer the prompt, the better.
`confirm`	No	Set true only when the user asked for exactly this action.
`download`	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`bitRateFactor`	No	The constant rate factor for encoding video. 0 indicates a lossless generation, with the highest quality and largest file size. 63 indicates the worst quality generation with the smallest file size. The suggested value range is 17-23.
`videoSettings`	No	The camera and shot control settings.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare the mutation/open-world profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false). The description adds genuinely useful behavior the annotations don't carry: the credit cost, that output is returned as Adobe URLs, and the async return behavior. It does not describe failure modes, credit quantities, or how the returned URLs expire.

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

Conciseness5/5

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

Four short sentences, zero filler, front-loaded with the core action and followed by cost, return format, and the key async flag. Every sentence earns its place.

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

Completeness4/5

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

With no output schema, the description usefully discloses that Adobe output URLs are returned and that the call can be async. Given nine parameters, nested objects, and a credit-consuming mutation, it is close to complete, though it omits credit cost magnitude and any precondition on the confirm flag.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all nine parameters in detail (including wait, download, sizes, and videoSettings). The description only restates the wait=false semantic that is already in the schema, adding no meaning beyond it; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Generate video'), which distinguishes it from the image-generation siblings in the list. However, it does not name or contrast with the closest alternatives (e.g., generate_similar, generate_image), so the differentiation comes only from the resource noun.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives one concrete usage instruction — 'Set wait=false to return an async job' — which tells the agent how to switch between synchronous and async modes. It offers no guidance on when to prefer this tool over the sibling generation tools or when video generation is appropriate.

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

generative_expandExpand imageB

Expand image. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

ParametersJSON Schema

Name	Required	Description
`n`	No	Compatibility alias for numVariations. Do not supply both.
`mask`	No	Mask image which will be used to expand the given image.
`size`	No	The desired width and height for the final expanded image in pixels. The maximum size for the output images is 3999px by 3999px.
`wait`	No	Wait for completion, default true. Set false to return the job immediately.
`image`	No	The image to expand. Use a URL or an uploadID as the source for the image. Firefly only allows these listed domains for input URLs in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .
`seeds`	No	Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. For example, you can use the same seed to generate a similar image with different styles. If specified along with numVariations, the number of seeds must equal numVariations.
`width`	No	Compatibility alias: provide together with height instead of size.
`height`	No	Compatibility alias: provide together with width instead of size.
`prompt`	No	An optional text prompt up to 1024 characters. The longer the prompt the better Firefly performs.
`confirm`	No	Set true only when the user asked for exactly this action.
`maskUrl`	No	Compatibility URL alias for mask.source.url.
`download`	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`imageUrl`	No	Compatibility URL alias for image.source.url.
`placement`	No	The position of the source image after Firefly resizes it. The value describes the horizontal and vertical placement and dimensions of the image in the output. Note you cannot use placement for source images when you also apply a mask image.
`numVariations`	No	Generate this number of variations. numVariations defaults to the number of seed images, or to 1 if you do not specify seeds.

TDQS

B3.1/5.0

Behavior4/5

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds genuinely new context beyond them: it consumes Firefly Services credits (a cost signal), returns Adobe-hosted output URLs, and that wait=false yields an async job. It stops short of mentioning the confirm gating or that download requires wait=true, so it is strong but not exhaustive.

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

Conciseness4/5

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

Four short sentences, front-loaded with the action and followed by cost, return, and async behavior. Nothing is wasted, though the opening sentence duplicates the title rather than earning its place.

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

Completeness3/5

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

For a 15-parameter tool with nested objects, no required fields, no output schema, and heavy alias/deprecation surface, this description is thin. It covers the return value (Adobe output URLs) and async mode, but omits the confirm safety gate and the wait=true prerequisite for download, leaving important cross-parameter behavior to the schema alone.

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

Parameters3/5

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

Schema description coverage is 100% across 15 parameters, so the schema already carries parameter meaning; baseline 3 applies. The description only reinforces the wait parameter and says nothing about the alias pairs (n/numVariations, width+height/size), deprecated image.mask, or the confirm flag. No added semantic value over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence 'Expand image' essentially restates the tool title, adding no scope detail (outpainting vs. fill vs. similar-generation). It does not distinguish this tool from closely related siblings like generative_fill or generate_similar, so an agent must infer the boundary. The subsequent sentences add operational facts but not purpose differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance and no routing to alternatives such as generative_fill (which also expands images) or generate_similar. The only directive is the tactical 'Set wait=false to return an async job,' which is a parameter hint rather than selection guidance.

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

generative_fillFill imageC

Fill image. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

ParametersJSON Schema

Name	Required	Description
`n`	No	Compatibility alias for numVariations. Do not supply both.
`mask`	No	Required. Selected areas of a background image that Firefly uses to fill the source image.
`size`	No	The desired width and height for the final expanded image in pixels. The supported sizes for the output images are: Square (1:1) - width 2048px, height 2048px Square (1:1) - width 1024px, height 1024px Landscape (4:3) - width 2304px, height 1792px Portrait (3:4) - width 1792px, height 2304px Widescreen (16:9) - width 2688px, height 1536px (7:4) - width 1344px, height 768px (9:7) - width 1152px, height 896px (7:9) - width 896px, height 1152px .
`wait`	No	Wait for completion, default true. Set false to return the job immediately.
`image`	No	The image to expand. Use a URL or an uploadID as the source for the image. Firefly only allows these listed domains for input URLs in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .
`seeds`	No	Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. For example, you can use the same seed to generate a similar image with different styles. If specified along with numVariations, the number of seeds must equal numVariations.
`width`	No	Compatibility alias: provide together with height instead of size.
`height`	No	Compatibility alias: provide together with width instead of size.
`prompt`	No	An optional text prompt up to 1024 characters. The longer the prompt the better Firefly performs.
`confirm`	No	Set true only when the user asked for exactly this action.
`maskUrl`	No	Compatibility URL alias for mask.source.url.
`download`	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`imageUrl`	No	Compatibility URL alias for image.source.url.
`numVariations`	No	Generate this number of variations. numVariations defaults to the number of seed images, or to 1 if you do not specify seeds.
`negativePrompt`	No	An optional text prompt up to 1024 characters. Avoid these characteristics in the generated image. Not supported for Firefly Custom Models on Image Model 3 or Firefly Custom Models on Image Model 4.
`promptBiasingLocaleCode`	No	A hyphen-separated string combining the ISO 639-1 language code and the ISO 3166-1 region, such as en-US. When a locale is set, the prompt will be biased to generate more relevant content for that region. The locale will be auto-detected if not specified based on your profile and the accepted language header.

TDQS

C2.6/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so safety is covered structurally. The description adds genuinely useful context beyond that: it consumes Firefly Services credits (cost) and returns Adobe output URLs. It still omits failure/retry behavior and what the async job returns, so it lands at a solid but not rich 3.

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

Conciseness4/5

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

Four short sentences with no filler and the core action front-loaded. It is efficient, though the terseness verges on under-specification for a tool of this complexity rather than trimming redundant content.

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

Completeness2/5

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

With 16 parameters, zero required fields, nested objects, and no output schema, the description is too thin: it never states that a mask and source image are effectively needed, nor how fill differs from expand or composite. The credit and URL notes are helpful but do not cover what an agent needs to call this correctly.

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

Parameters3/5

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

Schema description coverage is 100% and the schema already documents wait, mask vs image, aliases, and sizing in detail, so baseline is 3. The description's only parameter note (wait=false) merely repeats the schema and clarifies nothing about the mask requirement or the 16-parameter/alias surface.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Fill image" essentially restates the title with no verb+resource specificity and gives no differentiation from close siblings like generative_expand, generate_similar, or generate_object_composite. The remaining sentences describe side effects (credit consumption, output format) rather than what filling actually does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only usage instruction is "Set wait=false to return an async job," which is a parameter note, not guidance on when to pick this tool over generative_expand or the composite tools. No when-not, no prerequisites, no workflow context for the mask/image pairing an agent must reason about.

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

get_job_statusRead an async jobA

Read-onlyIdempotent

Read an existing Adobe async job by jobId. Use after a polling timeout instead of submitting generation again.

ParametersJSON Schema

Name	Required	Description	Default
`jobId`	Yes	Job ID or URN returned by Adobe.

TDQS

A4.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety and repeat-call semantics are covered structurally. The description adds useful operational context (this is the recovery path after a polling timeout rather than a re-submit), but says nothing about what a returned job state looks like or how to interpret it while no output schema exists.

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

Conciseness5/5

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

Two short sentences with zero filler, and the purpose is front-loaded ahead of the usage condition. Every clause carries information an agent needs to act.

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

Completeness4/5

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

For a one-parameter read tool with full annotation coverage, purpose and usage are complete. The one remaining gap is return semantics: with no output schema, the description could say what job states/progress it surfaces, which an agent polling a job would want to know.

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

Parameters3/5

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

Schema description coverage is 100% and the single jobId parameter is already documented as 'Job ID or URN returned by Adobe.' The description only restates that lookup is by jobId and adds no format, provenance, or error-handling detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Read an existing Adobe async job by jobId.' The contrast with 'submitting generation again' implicitly separates it from the generation-heavy sibling set (generate_image, generate_video, etc.), so an agent can tell this is the read-status tool without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the trigger condition ('after a polling timeout') and the alternative to avoid ('instead of submitting generation again'), which is exactly the anti-pattern an agent would otherwise fall into. Nothing about when to reach for this tool 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.

list_custom_modelsList available custom modelsB

Read-onlyIdempotent

Read custom models available to the Adobe project. FIREFLY_USER_TOKEN is optional for user-specific access. Returns a page; use start and limit to continue.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`start`	No
`sortBy`	No
`publishedState`	No

TDQS

B3.4/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the optional token changes the result scope (user-specific vs project-wide) and the call returns a single page requiring start/limit iteration — neither is derivable from 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.

Conciseness4/5

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

Three short sentences, zero filler, with the core purpose front-loaded and pagination guidance last. It is tight, though the auth note could be a touch more explicit about what happens without the token.

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

Completeness3/5

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

No output schema, and the page-return note covers the return shape minimally. For a 4-parameter filter tool with 0% schema coverage, the description omits sortBy and publishedState entirely, which are the main levers an agent would need to use.

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

Parameters2/5

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

Schema description coverage is 0% across 4 parameters, so the description must carry the burden. It covers start and limit for pagination but says nothing about sortBy (6 enum values) or publishedState (8 enum values), leaving half the parameters' semantics to inference from enum names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read custom models available to the Adobe project') with a clear scope qualifier. It is readily distinguishable from the generation-oriented siblings, though the description never explicitly contrasts itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides concrete operational guidance: FIREFLY_USER_TOKEN is optional for user-specific access, and 'use start and limit to continue' for pagination. However, it never states when to call this versus alternatives (e.g., verify_credentials, get_job_status) or any preconditions.

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

precise_compositeGenerate precise compositeB

Generate precise composite. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

ParametersJSON Schema

Name	Required	Description
`n`	No	Compatibility alias for numVariations. Do not supply both.
`wait`	No	Wait for completion, default true. Set false to return the job immediately.
`blend`	No	Controls blend between harmonized and original object appearance (0.0 = fully harmonized, 1.0 = original preserved).
`seeds`	No	Random seeds for each variation. Count must match numVariations if both are provided. Defaults: 1 variation → [333], 2 → [333, 222], 3 → [333, 222, 111].
`object`	Yes	Object image to be placed on the background.
`output`	No	Output format specification.
`confirm`	No	Set true only when the user asked for exactly this action.
`download`	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`background`	Yes	Background image and fill area mask specifying object placement.
`numVariations`	No	Number of output variations to generate.

TDQS

B3.1/5.0

Behavior4/5

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds genuinely new context beyond them: it consumes Firefly Services credits (a cost implication), returns Adobe output URLs, and can run asynchronously. This is useful operational detail an agent would not get from the structured fields alone, though it omits the non-idempotency/cost-per-variation qualification.

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

Conciseness4/5

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

Three short sentences with no filler, and the async-mode hint is placed last where it is easy to scan. It is appropriately sized for the tool, though the first sentence spends a slot restating the title without adding information.

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

Completeness3/5

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

With 10 parameters, nested objects, and no output schema, the tool is complex, and the description partially compensates by stating that Adobe output URLs are returned and that an async job is possible. However, it says nothing about the confirmation requirement implied by the 'confirm' parameter, the credit cost per variation, or how to retrieve async results, leaving notable gaps for a high-complexity generation tool.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all ten parameters in detail, including defaults, ranges, seed counts, and the url-vs-uploadId choice. The description's only parameter-related contribution ('Set wait=false to return an async job') repeats what the schema's wait description already says, so it does not meaningfully add value. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens by restating the title verbatim ('Generate precise composite'), which is close to tautology, though the supporting sentences do reveal that it produces image output URLs. Critically, it never distinguishes this tool from its near-identical siblings generate_object_composite or adaptive_composite, which an agent could easily confuse with it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only usage guidance is 'Set wait=false to return an async job,' which is a parameter hint rather than when-to-use guidance. There is no statement about when this tool is preferable to generate_object_composite or adaptive_composite, nor any prerequisite or exclusion conditions.

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

upload_imageUpload a reference imageA

Upload a local JPEG, PNG, WebP, TIFF or JXL image, up to 15 MB. Returns an uploadId, valid for seven days. File content is sent to Adobe.

ParametersJSON Schema

Name	Required	Description	Default
`filePath`	Yes	Local image path on the computer running this server.

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare the non-read-only, open-world, non-idempotent profile, so the description needn't restate safety. It adds genuinely new behavioral facts: the 15 MB ceiling, the accepted formats, that the returned uploadId expires after seven days, and that file content leaves the system to Adobe — a privacy-relevant disclosure not present in any structured field.

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

Conciseness5/5

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

Two sentences, no filler. Constraints (formats, size) come first, then the outcome and expiry, then the external-transmission caveat — front-loaded and every clause earns its place.

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

Completeness4/5

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

With no output schema, the description usefully covers the return value and its seven-day lifetime, plus size/format limits and the external data flow. What's missing is any tie-in to how the uploadId is consumed by sibling tools, which would complete the picture for a single-param upload tool.

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

Parameters3/5

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

Only one parameter exists and schema description coverage is 100%, so the schema fully documents filePath as a local path. The description's format and size constraints apply to the file but add no syntax or path-resolution detail beyond the schema; baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Upload) and resource (local image), enumerates accepted formats and the 15 MB cap, and names the return value (uploadId). An agent can distinguish this from siblings like generate_image or upscale_image without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the upload produces a reference image usable downstream, but never states when to use it versus the generative siblings or that the returned uploadId is the input to them. Usage is inferable from context only, which matches the 'implied usage' level.

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

upscale_imageUpscale imageA

Upscale image. Consumes Firefly Services credits. Returns Adobe output URLs. Set wait=false to return an async job.

ParametersJSON Schema

Name	Required	Description
`wait`	No	Wait for completion, default true. Set false to return the job immediately.
`image`	No	The input image for the upsampler (source uploadId or url).
`seeds`	Yes	The seed for each variation. Provide one seed per output (1–4 seeds).
`confirm`	No	Set true only when the user asked for exactly this action.
`download`	No	Download completed media to FIREFLY_OUTPUT_DIR, default false. Requires wait=true.
`imageUrl`	No	Compatibility URL alias for image.source.url.
`upscaleFactor`	No	The upscale factor (2, 3, 4, or 6). Output dimensions are input dimensions multiplied by this factor.

TDQS

A3.5/5.0

Behavior4/5

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

Annotations cover the safety profile (not read-only, open-world, non-idempotent, non-destructive), so the bar is lower. The description adds genuinely useful context beyond them: it consumes Firefly Services credits, it returns Adobe output URLs, and wait=false yields an async job — all things an agent needs to plan cost and flow.

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

Conciseness4/5

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

Four short, front-loaded sentences with no filler; cost, return value, and async behavior each get one line. The opening 'Upscale image' mildly restates the title, which is the only waste.

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

Completeness4/5

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

With no output schema, the description usefully names the return shape (Adobe output URLs) and covers cost and async behavior. Remaining gaps are minor since the rich schema documents source URL domains, uploadId, seeds, and upscaleFactor.

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

Parameters3/5

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

Schema coverage is 100%, so all seven parameters including the wait/download/upscaleFactor semantics are already documented. The description only restates the wait=false behavior and adds no new parameter meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Upscale image') that clearly separates it from sibling generators like generate_image or generative_fill. It does not explicitly name siblings or scope, but the action is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only usage guidance is 'Set wait=false to return an async job,' which is a mode flag rather than a when-to-use rule. Nothing tells the agent when to pick this over generate_similar, generative_expand, or the other image siblings, nor any prerequisite conditions.

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

verify_credentialsVerify authenticationA

Read-onlyIdempotent

Verify OAuth credentials or a supplied access token without generating media. A supplied token is checked through a custom-model API read. Does not prove generation entitlement or reveal tokens.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real context beyond that: it discloses the mechanism (token is checked via a custom-model API read) and explicit negative guarantees (no entitlement proof, no token disclosure), which is meaningful behavioral disclosure.

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

Conciseness4/5

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

Three short sentences, none wasted: purpose, mechanism, then scope limits. Front-loaded and readable, though the mechanism sentence is slightly terse for the concept it conveys.

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

Completeness4/5

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

No output schema and no parameters, but the rich annotations plus the description's stated mechanism and negative guarantees give enough to call it correctly. It stops short of saying how failure surfaces or what a success result looks like, which is the only meaningful gap.

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

Parameters3/5

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

With zero parameters the baseline is 4, but the description references 'a supplied access token' while the schema exposes no properties at all, creating a mismatch an agent could act on. The mechanism note is useful, but the phantom-input reference costs a point.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Verify OAuth credentials or a supplied access token') and immediately differentiates from the generate_* siblings by noting it operates 'without generating media'. An agent can identify this as the auth-check tool without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is only implied - one would infer this is a pre-flight check before calling generation tools, but there is no explicit 'use this when...' or reference to sibling alternatives. The limitations ('does not prove generation entitlement') hint at scope but do not guide selection.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

10 tool updatesv3.0.0Oct 6, 2026

Changedadaptive_composite18 fields changed

addedInput schema / $defs

Added value: +{
+  "source": {
+    "description": "The image source. Exactly one of `url` or `uploadId` must be provided in the request.",
+    "properties": {
+      "uploadId": {
+        "description": "If this object represents a file in our S3 temp storage system, the ID for that file.",
+        "format": "uuid",
+        "type": "string"
+      },
+      "url": {
+        "description": "Pre-signed URL of the image from a supported domain. [See Allowed storage domains](https://developer.adobe.com/firefly-services/docs/firefly-api/getting-started/usage-notes/) for the current list.",
+        "format": "uri",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  }
+}

addedInput schema / properties / background / properties / fillAreaMask / properties / source / $ref
```
Added value: +"#/$defs/source"
```
removedInput schema / properties / background / properties / fillAreaMask / properties / source / description
```
Removed value: -"The image source. Exactly one of `url` or `uploadId` must be provided in the request."
```

removedInput schema / properties / background / properties / fillAreaMask / properties / source / properties

Removed value: -{
-  "uploadId": {
-    "description": "If this object represents a file in our S3 temp storage system, the ID for that file.",
-    "format": "uuid",
-    "type": "string"
-  },
-  "url": {
-    "description": "Pre-signed URL of the image from a supported domain. [See Allowed storage domains](https://developer.adobe.com/firefly-services/docs/firefly-api/getting-started/usage-notes/) for the current list.",
-    "format": "uri",
-    "type": "string"
-  }
-}

removedInput schema / properties / background / properties / fillAreaMask / properties / source / type
```
Removed value: -"object"
```
addedInput schema / properties / background / properties / image / properties / source / $ref
```
Added value: +"#/$defs/source"
```

removedInput schema / properties / background / properties / image / properties / source / description

Removed value: -"The image source. Exactly one of `url` or `uploadId` must be provided in the request."

removedInput schema / properties / background / properties / image / properties / source / properties

Removed value: -{
-  "uploadId": {
-    "description": "If this object represents a file in our S3 temp storage system, the ID for that file.",
-    "format": "uuid",
-    "type": "string"
-  },
-  "url": {
-    "description": "Pre-signed URL of the image from a supported domain. [See Allowed storage domains](https://developer.adobe.com/firefly-services/docs/firefly-api/getting-started/usage-notes/) for the current list.",
-    "format": "uri",
-    "type": "string"
-  }
-}

removedInput schema / properties / background / properties / image / properties / source / type
```
Removed value: -"object"
```

changedInput schema / properties / confirm / description

Previous value: -"Must be true to spend Firefly Services credits for the operation the user requested."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / object / properties / image / properties / source / $ref
```
Added value: +"#/$defs/source"
```

removedInput schema / properties / object / properties / image / properties / source / description

Removed value: -"The image source. Exactly one of `url` or `uploadId` must be provided in the request."

removedInput schema / properties / object / properties / image / properties / source / properties

Removed value: -{
-  "uploadId": {
-    "description": "If this object represents a file in our S3 temp storage system, the ID for that file.",
-    "format": "uuid",
-    "type": "string"
-  },
-  "url": {
-    "description": "Pre-signed URL of the image from a supported domain. [See Allowed storage domains](https://developer.adobe.com/firefly-services/docs/firefly-api/getting-started/usage-notes/) for the current list.",
-    "format": "uri",
-    "type": "string"
-  }
-}

removedInput schema / properties / object / properties / image / properties / source / type
```
Removed value: -"object"
```
addedInput schema / properties / object / properties / mask / properties / source / $ref
```
Added value: +"#/$defs/source"
```

removedInput schema / properties / object / properties / mask / properties / source / description

Removed value: -"The image source. Exactly one of `url` or `uploadId` must be provided in the request."

removedInput schema / properties / object / properties / mask / properties / source / properties

Removed value: -{
-  "uploadId": {
-    "description": "If this object represents a file in our S3 temp storage system, the ID for that file.",
-    "format": "uuid",
-    "type": "string"
-  },
-  "url": {
-    "description": "Pre-signed URL of the image from a supported domain. [See Allowed storage domains](https://developer.adobe.com/firefly-services/docs/firefly-api/getting-started/usage-notes/) for the current list.",
-    "format": "uri",
-    "type": "string"
-  }
-}

removedInput schema / properties / object / properties / mask / properties / source / type
```
Removed value: -"object"
```

Changedgenerate_image8 fields changed

addedInput schema / $defs

Added value: +{
+  "imageReference": {
+    "properties": {
+      "source": {
+        "properties": {
+          "uploadId": {
+            "description": "The `uploadId` from the storage API response.",
+            "format": "uuid",
+            "type": "string"
+          },
+          "url": {
+            "description": "The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .",
+            "format": "uri",
+            "maxLength": 2083,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "type": "object"
+      }
+    },
+    "type": "object"
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Must be true to spend Firefly Services credits for the operation the user requested."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / structure / properties / imageReference / $ref
```
Added value: +"#/$defs/imageReference"
```

removedInput schema / properties / structure / properties / imageReference / properties

Removed value: -{
-  "source": {
-    "properties": {
-      "uploadId": {
-        "description": "The `uploadId` from the storage API response.",
-        "format": "uuid4",
-        "type": "string"
-      },
-      "url": {
-        "description": "The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .",
-        "format": "uri",
-        "maxLength": 2083,
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "type": "object"
-  }
-}

removedInput schema / properties / structure / properties / imageReference / type
```
Removed value: -"object"
```
addedInput schema / properties / style / properties / imageReference / $ref
```
Added value: +"#/$defs/imageReference"
```

removedInput schema / properties / style / properties / imageReference / properties

Removed value: -{
-  "source": {
-    "properties": {
-      "uploadId": {
-        "description": "The `uploadId` from the storage API response.",
-        "format": "uuid4",
-        "type": "string"
-      },
-      "url": {
-        "description": "The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .",
-        "format": "uri",
-        "maxLength": 2083,
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "type": "object"
-  }
-}

removedInput schema / properties / style / properties / imageReference / type
```
Removed value: -"object"
```

Changedgenerate_image51 field changed

changedInput schema / properties / confirm / description

Previous value: -"Must be true to spend Firefly Services credits for the operation the user requested."New value: +"Set true only when the user asked for exactly this action."

Changedgenerate_object_composite30 fields changed
- addedInput schema / $defs
```
Added value: +{
+  "url": {
+    "description": "The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .",
+    "format": "uri",
+    "maxLength": 2083,
+    "minLength": 1,
+    "type": "string"
+  }
+}
```
- changedInput schema / properties / confirm / description
```
Previous value: -"Must be true to spend Firefly Services credits for the operation the user requested."New value: +"Set true only when the user asked for exactly this action."
```
- changedInput schema / properties / image / properties / mask / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```
- addedInput schema / properties / image / properties / mask / properties / url / $ref
```
Added value: +"#/$defs/url"
```
- removedInput schema / properties / image / properties / mask / properties / url / description
```
Removed value: -"The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com ."
```
- removedInput schema / properties / image / properties / mask / properties / url / format
```
Removed value: -"uri"
```
- removedInput schema / properties / image / properties / mask / properties / url / maxLength
```
Removed value: -2083
```
- removedInput schema / properties / image / properties / mask / properties / url / minLength
```
Removed value: -1
```
- removedInput schema / properties / image / properties / mask / properties / url / type
```
Removed value: -"string"
```
- changedInput schema / properties / image / properties / source / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```
- addedInput schema / properties / image / properties / source / properties / url / $ref
```
Added value: +"#/$defs/url"
```
- removedInput schema / properties / image / properties / source / properties / url / description
```
Removed value: -"The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com ."
```
- removedInput schema / properties / image / properties / source / properties / url / format
```
Removed value: -"uri"
```
- removedInput schema / properties / image / properties / source / properties / url / maxLength
```
Removed value: -2083
```
- removedInput schema / properties / image / properties / source / properties / url / minLength
```
Removed value: -1
```
- removedInput schema / properties / image / properties / source / properties / url / type
```
Removed value: -"string"
```
- changedInput schema / properties / mask / properties / source / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```
- addedInput schema / properties / mask / properties / source / properties / url / $ref
```
Added value: +"#/$defs/url"
```
- removedInput schema / properties / mask / properties / source / properties / url / description
```
Removed value: -"The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com ."
```
- removedInput schema / properties / mask / properties / source / properties / url / format
```
Removed value: -"uri"
```
- removedInput schema / properties / mask / properties / source / properties / url / maxLength
```
Removed value: -2083
```
- removedInput schema / properties / mask / properties / source / properties / url / minLength
```
Removed value: -1
```
- removedInput schema / properties / mask / properties / source / properties / url / type
```
Removed value: -"string"
```
- changedInput schema / properties / style / properties / imageReference / properties / source / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```
- addedInput schema / properties / style / properties / imageReference / properties / source / properties / url / $ref
```
Added value: +"#/$defs/url"
```
- removedInput schema / properties / style / properties / imageReference / properties / source / properties / url / description
```
Removed value: -"The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com ."
```
- removedInput schema / properties / style / properties / imageReference / properties / source / properties / url / format
```
Removed value: -"uri"
```
- removedInput schema / properties / style / properties / imageReference / properties / source / properties / url / maxLength
```
Removed value: -2083
```
- removedInput schema / properties / style / properties / imageReference / properties / source / properties / url / minLength
```
Removed value: -1
```
- removedInput schema / properties / style / properties / imageReference / properties / source / properties / url / type
```
Removed value: -"string"
```

Changedgenerate_similar2 fields changed

changedInput schema / properties / confirm / description

Previous value: -"Must be true to spend Firefly Services credits for the operation the user requested."New value: +"Set true only when the user asked for exactly this action."

changedInput schema / properties / image / properties / source / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```

Changedgenerate_video2 fields changed

changedInput schema / properties / confirm / description

Previous value: -"Must be true to spend Firefly Services credits for the operation the user requested."New value: +"Set true only when the user asked for exactly this action."

changedInput schema / properties / image / properties / conditions / items / properties / source / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```

Changedgenerative_expand23 fields changed
- addedInput schema / $defs
```
Added value: +{
+  "url": {
+    "description": "The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .",
+    "format": "uri",
+    "maxLength": 2083,
+    "minLength": 1,
+    "type": "string"
+  }
+}
```
- changedInput schema / properties / confirm / description
```
Previous value: -"Must be true to spend Firefly Services credits for the operation the user requested."New value: +"Set true only when the user asked for exactly this action."
```
- changedInput schema / properties / image / properties / mask / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```
- addedInput schema / properties / image / properties / mask / properties / url / $ref
```
Added value: +"#/$defs/url"
```
- removedInput schema / properties / image / properties / mask / properties / url / description
```
Removed value: -"The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com ."
```
- removedInput schema / properties / image / properties / mask / properties / url / format
```
Removed value: -"uri"
```
- removedInput schema / properties / image / properties / mask / properties / url / maxLength
```
Removed value: -2083
```
- removedInput schema / properties / image / properties / mask / properties / url / minLength
```
Removed value: -1
```
- removedInput schema / properties / image / properties / mask / properties / url / type
```
Removed value: -"string"
```
- changedInput schema / properties / image / properties / source / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```
- addedInput schema / properties / image / properties / source / properties / url / $ref
```
Added value: +"#/$defs/url"
```
- removedInput schema / properties / image / properties / source / properties / url / description
```
Removed value: -"The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com ."
```
- removedInput schema / properties / image / properties / source / properties / url / format
```
Removed value: -"uri"
```
- removedInput schema / properties / image / properties / source / properties / url / maxLength
```
Removed value: -2083
```
- removedInput schema / properties / image / properties / source / properties / url / minLength
```
Removed value: -1
```
- removedInput schema / properties / image / properties / source / properties / url / type
```
Removed value: -"string"
```
- changedInput schema / properties / mask / properties / source / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```
- addedInput schema / properties / mask / properties / source / properties / url / $ref
```
Added value: +"#/$defs/url"
```
- removedInput schema / properties / mask / properties / source / properties / url / description
```
Removed value: -"The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com ."
```
- removedInput schema / properties / mask / properties / source / properties / url / format
```
Removed value: -"uri"
```
- removedInput schema / properties / mask / properties / source / properties / url / maxLength
```
Removed value: -2083
```
- removedInput schema / properties / mask / properties / source / properties / url / minLength
```
Removed value: -1
```
- removedInput schema / properties / mask / properties / source / properties / url / type
```
Removed value: -"string"
```
Changedgenerative_fill23 fields changed
- addedInput schema / $defs
```
Added value: +{
+  "url": {
+    "description": "The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com .",
+    "format": "uri",
+    "maxLength": 2083,
+    "minLength": 1,
+    "type": "string"
+  }
+}
```
- changedInput schema / properties / confirm / description
```
Previous value: -"Must be true to spend Firefly Services credits for the operation the user requested."New value: +"Set true only when the user asked for exactly this action."
```
- changedInput schema / properties / image / properties / mask / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```
- addedInput schema / properties / image / properties / mask / properties / url / $ref
```
Added value: +"#/$defs/url"
```
- removedInput schema / properties / image / properties / mask / properties / url / description
```
Removed value: -"The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com ."
```
- removedInput schema / properties / image / properties / mask / properties / url / format
```
Removed value: -"uri"
```
- removedInput schema / properties / image / properties / mask / properties / url / maxLength
```
Removed value: -2083
```
- removedInput schema / properties / image / properties / mask / properties / url / minLength
```
Removed value: -1
```
- removedInput schema / properties / image / properties / mask / properties / url / type
```
Removed value: -"string"
```
- changedInput schema / properties / image / properties / source / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```
- addedInput schema / properties / image / properties / source / properties / url / $ref
```
Added value: +"#/$defs/url"
```
- removedInput schema / properties / image / properties / source / properties / url / description
```
Removed value: -"The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com ."
```
- removedInput schema / properties / image / properties / source / properties / url / format
```
Removed value: -"uri"
```
- removedInput schema / properties / image / properties / source / properties / url / maxLength
```
Removed value: -2083
```
- removedInput schema / properties / image / properties / source / properties / url / minLength
```
Removed value: -1
```
- removedInput schema / properties / image / properties / source / properties / url / type
```
Removed value: -"string"
```
- changedInput schema / properties / mask / properties / source / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```
- addedInput schema / properties / mask / properties / source / properties / url / $ref
```
Added value: +"#/$defs/url"
```
- removedInput schema / properties / mask / properties / source / properties / url / description
```
Removed value: -"The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: amazonaws.com windows.net dropboxusercontent.com storage.googleapis.com ."
```
- removedInput schema / properties / mask / properties / source / properties / url / format
```
Removed value: -"uri"
```
- removedInput schema / properties / mask / properties / source / properties / url / maxLength
```
Removed value: -2083
```
- removedInput schema / properties / mask / properties / source / properties / url / minLength
```
Removed value: -1
```
- removedInput schema / properties / mask / properties / source / properties / url / type
```
Removed value: -"string"
```

Changedprecise_composite14 fields changed

addedInput schema / $defs

Added value: +{
+  "source": {
+    "description": "The image source. Exactly one of `url` or `uploadId` must be provided in the request.",
+    "properties": {
+      "uploadId": {
+        "description": "If this object represents a file in our S3 temp storage system, the ID for that file.",
+        "format": "uuid",
+        "type": "string"
+      },
+      "url": {
+        "description": "Pre-signed URL of the image from a supported domain. [See Allowed storage domains](https://developer.adobe.com/firefly-services/docs/firefly-api/getting-started/usage-notes/) for the current list.",
+        "format": "uri",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  }
+}

addedInput schema / properties / background / properties / fillAreaMask / properties / source / $ref
```
Added value: +"#/$defs/source"
```
removedInput schema / properties / background / properties / fillAreaMask / properties / source / description
```
Removed value: -"The image source. Exactly one of `url` or `uploadId` must be provided in the request."
```

removedInput schema / properties / background / properties / fillAreaMask / properties / source / properties

Removed value: -{
-  "uploadId": {
-    "description": "If this object represents a file in our S3 temp storage system, the ID for that file.",
-    "format": "uuid",
-    "type": "string"
-  },
-  "url": {
-    "description": "Pre-signed URL of the image from a supported domain. [See Allowed storage domains](https://developer.adobe.com/firefly-services/docs/firefly-api/getting-started/usage-notes/) for the current list.",
-    "format": "uri",
-    "type": "string"
-  }
-}

removedInput schema / properties / background / properties / fillAreaMask / properties / source / type
```
Removed value: -"object"
```
addedInput schema / properties / background / properties / image / properties / source / $ref
```
Added value: +"#/$defs/source"
```

removedInput schema / properties / background / properties / image / properties / source / description

Removed value: -"The image source. Exactly one of `url` or `uploadId` must be provided in the request."

removedInput schema / properties / background / properties / image / properties / source / properties

Removed value: -{
-  "uploadId": {
-    "description": "If this object represents a file in our S3 temp storage system, the ID for that file.",
-    "format": "uuid",
-    "type": "string"
-  },
-  "url": {
-    "description": "Pre-signed URL of the image from a supported domain. [See Allowed storage domains](https://developer.adobe.com/firefly-services/docs/firefly-api/getting-started/usage-notes/) for the current list.",
-    "format": "uri",
-    "type": "string"
-  }
-}

removedInput schema / properties / background / properties / image / properties / source / type
```
Removed value: -"object"
```

changedInput schema / properties / confirm / description

Previous value: -"Must be true to spend Firefly Services credits for the operation the user requested."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / object / properties / image / properties / source / $ref
```
Added value: +"#/$defs/source"
```

removedInput schema / properties / object / properties / image / properties / source / description

Removed value: -"The image source. Exactly one of `url` or `uploadId` must be provided in the request."

removedInput schema / properties / object / properties / image / properties / source / properties

Removed value: -{
-  "uploadId": {
-    "description": "If this object represents a file in our S3 temp storage system, the ID for that file.",
-    "format": "uuid",
-    "type": "string"
-  },
-  "url": {
-    "description": "Pre-signed URL of the image from a supported domain. [See Allowed storage domains](https://developer.adobe.com/firefly-services/docs/firefly-api/getting-started/usage-notes/) for the current list.",
-    "format": "uri",
-    "type": "string"
-  }
-}

removedInput schema / properties / object / properties / image / properties / source / type
```
Removed value: -"object"
```

Changedupscale_image2 fields changed

changedInput schema / properties / confirm / description

Previous value: -"Must be true to spend Firefly Services credits for the operation the user requested."New value: +"Set true only when the user asked for exactly this action."

changedInput schema / properties / image / properties / source / properties / uploadId / format
```
Previous value: -"uuid4"New value: +"uuid"
```

14 tool updatesv2.0.0Oct 2, 2026
- First observedadaptive_composite
- First observedgenerate_image
- First observedgenerate_image5
- First observedgenerate_object_composite
- First observedgenerate_similar
- First observedgenerate_video
- First observedgenerative_expand
- First observedgenerative_fill
- First observedget_job_status
- First observedlist_custom_models
- First observedprecise_composite
- First observedupload_image
- First observedupscale_image
- First observedverify_credentials

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-10-06 23:55 across 14 tools

Disambiguation4/5

Most tools target distinct operations: generate_image, generate_similar, generate_video, generative_expand, generative_fill, upscale_image, and the utility tools (upload_image, get_job_status, list_custom_models, verify_credentials) are clearly separable. The three compositing tools (generate_object_composite, precise_composite, adaptive_composite) have terse, near-parallel descriptions that give an agent little basis for choosing among them, though they are genuinely different operations.

Naming Consistency3/5

All names use snake_case, which is good, but verb/prefix conventions are mixed: 'generate_', 'generative_', 'precise_', 'adaptive_', 'upscale_', plus utility verbs 'get_', 'list_', 'upload_', 'verify_'. The composite tools omit a verb entirely, and 'generate_image5' uses an unexplained numeric suffix that breaks the pattern.

Tool Count5/5

Fourteen tools is well-scoped for a media-generation API surface, with each tool mapping to a distinct Firefly capability (generation, editing, compositing, video, upscaling, upload, job polling, models, auth). No obvious redundancy or padding.

Completeness4/5

The set covers the full generation/edit lifecycle plus async job polling, uploads, model listing, and credential verification. Minor gaps exist: no explicit job cancel/delete or asset download/retrieval tool, and no batch or clear error-recovery path beyond get_job_status, but core workflows are covered.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

MorphedOAuth
app.morphed
Create AI images and videos, manage projects and credits, and use workspace campaign context.
AI & Machine Learning Image & Video Processing
1
FreeVideoGeneratorOAuth
io.github.horace68
Generate AI images and videos, quote credit costs, manage media and track batch jobs with OAuth.
AI & Machine Learning Image & Video Processing
1
ImgEdify: AI Image Editor, AI Image Generator, AI Video Generator, AI Video Editor & AI Video Maker
io.github.andida
Generate and edit images, create videos, quote credit costs, and retrieve private results.
AI & Machine Learning Image & Video Processing Multimedia Processing
1
Euphronios Media GenerationOAuth
me.euphronios
Generate and edit images, video, voice, lip-sync and 3D models from your AI agent.
Image & Video Processing Audio Processing Multimedia Processing
1

Related MCP Servers

nano-banana-mcp
AI & Machine Learning Image & Video Processing
petrkindlmann
A
license
A
quality
C
maintenance
Enables AI image generation and editing using Google's Gemini models via natural language, supporting multi-turn editing, search grounding, storyboards, icon sets, and video-to-image.
Updated 17 days ago (2026-10-06 01:44 UTC)
5
5 npm
1
MIT
BudgetPixel MCP Serverofficial
AI & Machine Learning Image & Video Processing Multimedia Processing
budgetpixel-ai
A
license
Not graded
quality
C
maintenance
Enables MCP-compatible clients to generate and upscale AI images, videos, music, and sound effects, manage generation jobs, access model catalogs, and track credits.
Updated 2 months ago (2026-08-29 04:37 UTC)
3
MIT
mcp-media-orchestrator
AI & Machine Learning Image & Video Processing Audio Processing
rolan86
A
license
A
quality
C
maintenance
Enables generating images, video, and audio through a single capability-oriented interface, with server-side routing, safety screening, job lifecycle management, concurrency limits, and retention.
Updated 2 months ago (2026-09-01 12:11 UTC)
5
MIT
Bina MCP Server
Image & Video Processing AI & Machine Learning
seyed-ali-002
A
license
Not graded
quality
B
maintenance
Enables image and video generation and editing through MCP tools, including image editing, upscaling, background removal, video generation, image-to-video, and video extension. Video generation runs asynchronously with job status and result retrieval.
Updated a month ago (2026-09-09 14:33 UTC)
MIT

Adobe Firefly MCP Server & CLI

Two ways to use it

Command line

MCP server, for your AI app

Which one

Features

Contents

1. What you can ask it

2. Quick install

3. Set up Adobe access

Before the credential fields

Set it up yourself

Let your AI help with setup

Existing access token

Disconnect or rotate

4. Connect your client

5. Check it works

6. Output, flags and exit codes

7. MCP or CLI and token cost

8. Every tool and argument

Images

generate_image

generate_image5

generate_similar

generative_fill

generative_expand

upscale_image

Composites

generate_object_composite

precise_composite

adaptive_composite

Video

generate_video

References

upload_image

Jobs

get_job_status

Account

verify_credentials

list_custom_models

9. Image, editing and video workflows

Generate with Image Model 5

Upload a reference, then instruct an edit

Fill a masked region

Submit video without waiting

Upscale or composite

Optional downloads

Source object shapes

Model and storage constraints

Current documentation discrepancy

10. Jobs and local files

Downloading

11. Several Adobe projects

12. Writing safely

13. How it works

14. Your data

15. Environment variables

Credentials

Safety

Tuning

16. Updates and removal

npm and client updates

Migrating from the old MCP-only server

Remove it

17. Troubleshooting

18. API coverage and comparisons

19. Versions

20. FAQ

Questions

About the author

Dependencies

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

BudgetPixel MCP Serverofficial

`generate_image`

`generate_image5`

`generate_similar`

`generative_fill`

`generative_expand`

`upscale_image`

`generate_object_composite`

`precise_composite`

`adaptive_composite`

`generate_video`

`upload_image`

`get_job_status`

`verify_credentials`

`list_custom_models`