This server provides DreamLayer image generation, editing, and sprite animation tools for MCP clients, with credit-aware paid operations and recovery support.
Read API capabilities and operation availability without spending credits.
Check promotional, purchased, and available credit balance before paid work.
Upload local PNG, JPEG, WebP, or RAW images up to 200 MB to get an input asset ID.
Generate or edit images: text-to-image, image-to-image, background removal, and 2× upscale.
Create beta sprite-sheet animations from a reference image using presets or custom prompts, with configurable frame count, frame size, and transparency/background behavior.
Quote and cap sprite spending with sprite_pricing and max_credits.
Inspect execution status, resume event streams after drops, and download completed outputs without regenerating.
Use idempotency keys and structured errors for safe retries and failure recovery.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DreamLayer image tools generate an image of a cozy cabin in a snowy forest"
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.
Image generation and editing tools for MCP-compatible AI clients, backed by the DreamLayer Agent API.
Use it for raster logo concepts, product imagery, marketing visuals, print artwork concepts and game assets. Inspect output quality and task-specific requirements. See the installable agent workflows for task guidance and Godot/Unity import examples.
The full workflow below uses the published sprite-capable beta. Stable latest
remains 0.3.0; use the explicit version shown here.
Add it to your client. Claude Code:
claude mcp add dreamlayer --env DREAMLAYER_API_KEY=dlr_live_your_key -- npx -y @dreamlayer/mcp@0.4.0-beta.5Codex:
codex mcp add dreamlayer --env DREAMLAYER_API_KEY=dlr_live_your_key -- npx -y @dreamlayer/mcp@0.4.0-beta.5Cursor, or any other stdio MCP client:
{
"mcpServers": {
"dreamlayer": {
"command": "npx",
"args": ["-y", "@dreamlayer/mcp@0.4.0-beta.5"],
"env": { "DREAMLAYER_API_KEY": "dlr_live_your_key" }
}
}
}The key must be in the server's own environment. MCP clients spawn this as a subprocess, so a key exported in your shell does not reach it. That is the most common setup failure, and the server exits with an explanation rather than starting up broken.
Get a key at platform.dreamlayer.io. A new account starts at zero credits. Ordinary image operations cost one credit each; sprite bundles use the frame-count quote described below.
Related MCP server: imagengen
Tool | What it does |
| Read the contract and the operations this key may run. Spends nothing. |
| Read this API key's promotional, purchased, and total available credits. Spends nothing. |
| Upload PNG, JPEG, WebP, or camera RAW (up to 200 MB) and get an |
| Generate or edit. Returns the event stream. |
| Read canonical state for one execution. |
| Resume a stream after a drop, from a last event id. |
| Save a completed execution to a new local path without generating again. |
Omit operation and DreamLayer reads the prompt, which may come back asking a
clarifying question. Name it and that inference is skipped entirely.
| Needs an image | Result |
| No | A new image from the prompt |
| Yes | The reference, edited as described |
| Yes | The subject on transparency |
| Yes | Twice the width and height |
upscale doubles each side and finished images are capped at 4096 per side, so the
longest side of your input must be 2048 or less. A larger one is refused before it
costs a credit.
A question is not a failure. An ambiguous prompt returns a question event ending
in needs_input. Answer it by calling dreamlayer_generate again with respond and
the conversation_id.
Retries are safe if you reuse the key. An idempotency_key is generated for you.
Pass the same one back to retry after an uncertain response and the original result
replays rather than paying twice.
Long runs are truncated, not lost. A stream over 256 events returns what it has,
marks truncated, and gives you the execution_id and last event id to resume from.
Errors are stable and provider-neutral. Error tool results include code, reason,
message, retryable, and request_id, matching REST and the CLI. A model should branch
on reason and retryable, never message text. The response excludes prompts, local
filenames, asset URLs, provider details, credentials, and raw upstream responses.
Node.js 22.12 or later.
MIT. See LICENSE and NOTICE.
Sprite requests accept exactly one of options.animation_prompt (1–4000 characters) or an options.action preset (walk, run, idle). Custom prompts can describe characters, creatures, objects, effects or 360° turntables. animation_mode is loop or once; presets default to loop, custom prompts to once. For a turntable, request a stationary camera and rotating subject. Broad requests do not guarantee correct motion, unseen details or successful effect transparency.
Request integer frame_count 7–100 (default 12) and frame_size 32, 64, 128, 256, 512, 720 or 1080 (default 512). These are square export canvases; a larger export does not guarantee additional detail. Aspect ratio and shared alignment are preserved with transparent padding. A bundle contains transparent PNG frames, sheet, atlas, preview and import instructions, including each frame's playback duration. Send background: "keep" in options when transparency is not needed: the frames ship with the generated background in place, plain rather than cut out, and cost the flat plain rate. A frame that cannot be cut out is retried at nearby moments of the same clip, and a single stubborn frame ships with its background rather than failing the sheet; atlas.json lists any such frame in kept_background_frames. Choose a repeating loop or a one-time action with a beginning and ending. If the requested number of distinct frames cannot be delivered, the job fails and held credits are returned. Translucent effects can lose detail or fail; small exports are not automatically pixel art.
Pricing is unchanged across sizes: frames 1–14 cost $0.14 each; additional frames $0.07 each. With background: "keep" every frame is a flat $0.07 with no tier, roughly half a transparent sheet (12 frames: 5.0 credits instead of 9.9). One credit is $0.17. Round the complete order upward once to a tenth of a credit. Check sprite_pricing in capabilities and approve the quote with max_credits. Credits are held during processing, settled after complete delivery and restored on failure/timeout. There is no customer cancellation. Keep the execution ID to resume status. Custom requests need the matching broad-animation server release; older servers reject them. New live generation quality, 100-frame duration and actual cost remain unverified.
Call dreamlayer_upload_image, then dreamlayer_generate with operation: "sprite_sheet", the uploaded input_asset_id, options: {action: "walk", frame_count: 12}, and max_credits set to your approved limit.
Each tool call waits for a bounded interval. If the result remains active, pass its execution_id and last_event_id to dreamlayer_events. When completed, use dreamlayer_download with execution_id and an absolute path ending in .zip. Existing files are never overwritten.
For affordability, compare the complete rounded quote in credits with available. One tenth of a credit is $0.017. Promotional and purchased amounts are displayed rounded down separately, so their displayed sum can be 0.1 credit below available; stored fractions are preserved. Compare against the combined total, not that sum. The order charge rounds only once, never per frame or per tier.
Read tools/list for descriptions, input schemas, and operation availability. Read-only
calls are marked with readOnlyHint; upload, generation, and local download are not.
These annotations describe effects, not permission grants. Generation starts paid work.
Every tool returns structuredContent plus the same JSON serialized in a text block for
older clients. Failures set isError: true. Generation results and errors include the
idempotency key, including when the server generated it for you. Choose and save your own
key before calling when you need recovery even after the MCP process itself is lost.
After interruption, call dreamlayer_execution with the saved execution ID, then
dreamlayer_events with the last processed event ID. Retrieve completed work with
dreamlayer_download. Never start a replacement generation merely because the stream
closed. Keep the same uploaded asset ID and identical arguments when replaying a key.
MCP setup · API overview · Execution recovery
Abrupt stream failures trigger a canonical status read. If state is still uncertain,
the error is temporarily_unavailable with recovery guidance and the known execution
ID, cursor and retry key. local_output_failed means a completed output could not be
written: fix the path and retry dreamlayer_download, not dreamlayer_generate.
Client-side input validation uses invalid_request; other unclassified client failures
use client_error and are not evidence that generation failed.
options.background selects what the frames look like. remove, the default, cuts every frame out for transparent frames. keep leaves the generated background in place: the frames are plain rather than cut out, and every frame costs the flat sprite_pricing.plain_frame_cents with no tier, about half the transparent price. Twelve frames quote 5 credits kept against 9.9 transparent.
beta.4 and earlier reject this field: their options schema set additionalProperties: false, so a request naming a background never reached the service. Pin beta.5 or later to use it.
A spelled-out background: "remove" is normalised away before the request is sent, because it is exactly what an absent field already means and the service fingerprints the options it receives; sending it would otherwise split one job into two idempotency identities.
Every input parameter in tools/list now states what it accepts, including the nested sprite options fields: prompt, conversation_id, max_credits (image operations require exactly 1; sprite jobs at or above the quoted price), aspect_ratio, execution_id and last_event_id. Tool names, arguments and results are unchanged from beta.3.
Malformed event payloads return response_contract_error with retryable: false, preserving the execution ID, last event ID and idempotency key when known. Check client compatibility or contact support; do not submit replacement work. Interrupted network streams still reconcile canonical state.
Use before paid image work to check available credits for this API key. Returns promotional, purchased, available and credit_usd. Compare the complete rounded quote against available; separately rounded buckets may sum to 0.1 less. Costs no credits and does not buy credits. Resolve authentication or balance errors before generation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| error | No | |
| available | No | |
| purchased | No | |
| credit_usd | No | |
| promotional | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds the rounding nuance ('separately rounded buckets may sum to 0.1 less') and the no-cost/no-purchase clarification, which provide modest extra context but the bulk of safety disclosure is carried by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero waste: purpose+returns, a genuinely useful rounding caveat, and cost/error guidance. Every sentence earns its place and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with an output schema, the description is complete. It covers when to use it, what it returns, a subtle numerical gotcha, and error-handling guidance—nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds value by enumerating the return values, which gives the agent advance knowledge of what to expect beyond the parameter schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('check available credits for this API key') and names the exact return fields (promotional, purchased, available, credit_usd). It clearly distinguishes itself from generation/download siblings by framing itself as a pre-flight balance check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use before paid image work' gives explicit when-to-use context. It also states what it does not do ('does not buy credits') and advises resolving authentication/balance errors before generation, giving clear operational context without naming a specific alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use before choosing an image operation or quoting a sprite job. Read supported operations, input limits and sprite_pricing for this API key. Returns the current API contract; no image input, generation or credits required. Do not use this to create an asset.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| error | No | |
| operations | No | |
| api_version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that it requires no image input, generation, or credits and returns the current contract, which reinforces the read-only nature and clarifies that it is a prerequisite query. This is useful context beyond the annotations, though it could specify the exact response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the 'use before' guidance and ending with a clear negative use case. No redundancy or filler; every sentence adds distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameter-less informational tool with a rich annotation set and an output schema, the description covers purpose, timing, and exclusions. An agent knows exactly when and why to call it, and the output schema presumably details the return structure. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the schema already documents everything about the parameters. The baseline for zero-param tools is 4, and the description appropriately focuses on usage rather than parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear, specific purpose: reading the API contract (supported operations, input limits, sprite_pricing) for the key. It names the exact resource and distinguishes itself from generation/download tools, so an agent can tell what it is and is not for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use before choosing an image operation or quoting a sprite job, and states 'Do not use this to create an asset.' This gives both a clear trigger and a clear exclusion, leaving no ambiguity about when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when an existing execution completed or a previous download failed. Requires execution_id and an absolute new local path. Saves the finished image or sprite ZIP and returns path/bytes; starts no generation and spends no new credits. Never overwrites. For output_not_ready check status; for local_output_failed repair the path and download the same execution.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute destination path; an existing file is never overwritten. | |
| execution_id | Yes | UUID of a completed execution, as returned by dreamlayer_generate. |
| Name | Required | Description |
|---|---|---|
| path | No | |
| bytes | No | |
| error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds key behavioral details: it spends no new credits, never overwrites files, returns path/bytes, and does not start generation. These are important operational traits not inferable from readOnlyHint=false or destructiveHint=false, and there is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences pack in the trigger condition, required inputs, behavior, return type, safety guarantee, and error-handling branches. The description is front-loaded with the most important usage signal and contains no filler or repetition of schema text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with full schema coverage and an output schema, the description covers all essential operational context: when to use, what to provide, what it returns, what it does not do, and how to handle the two main failure modes. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents both parameters, so the baseline is 3. The description adds meaningful context by specifying the path must be 'absolute' and 'new', and that the execution_id refers to a completed execution and can be reused for re-downloads after a failure. This is modest but genuine added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('download') and resource ('finished image or sprite ZIP' from an existing execution), and clearly distinguishes itself from generation tools by noting it 'starts no generation'. This is more than a tautology and uniquely identifies the tool's role among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('when an existing execution completed or a previous download failed') and provides concrete guidance for common failure cases ('output_not_ready' vs 'local_output_failed'). It also implies when not to use it by noting it does not generate, effectively routing agents away from dreamlayer_generate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use to resume running work or a dropped stream without another generation charge. Requires execution_id; pass the last_event_id actually processed. Returns bounded events, status and recovery cursor. If still running or rate-limited, back off before polling again. Do not repeatedly call in a tight loop or submit replacement work.
| Name | Required | Description | Default |
|---|---|---|---|
| execution_id | Yes | UUID of the execution, as returned by dreamlayer_generate. | |
| last_event_id | No | Id of the last event you processed; events after it are returned. Omit to replay from the start. |
| Name | Required | Description |
|---|---|---|
| asset | No | |
| error | No | |
| events | No | |
| status | No | |
| question | No | |
| execution_id | No | |
| last_event_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only, idempotent, and non-destructive. The description adds valuable behavioral context: no generation charge, bounded events, status and recovery cursor, backoff requirements, and polling prohibitions. This goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, then requirements, then behavioral constraints. Every sentence earns its place, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only two parameters and an output schema, the description covers purpose, invocation requirements, return behavior, rate-limit handling, and anti-abuse guidance. Nothing an agent needs to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful nuance by specifying that last_event_id should be the last event actually processed, and it clarifies the recovery-cursor relationship. This is more than a restatement of the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific purpose: resuming running work or a dropped stream without incurring another generation charge. It clearly identifies the resource (events) and distinguishes itself from generation by emphasizing no extra charge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use the tool, what to pass (execution_id and last_event_id actually processed), and when to back off (still running or rate-limited). It also gives a clear exclusion: do not call repeatedly in a tight loop or submit replacement work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use after a timeout, rate limit or uncertain result to read the existing execution's canonical status. Requires execution_id; costs no credits. Returns state and result details, not a newly generated image. If running, wait and resume events; if completed, download. Do not replace an uncertain paid job.
| Name | Required | Description | Default |
|---|---|---|---|
| execution_id | Yes | UUID of the execution, as returned by dreamlayer_generate. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| image_job | No | |
| execution_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/idempotent hints, but the description adds valuable behavioral context: 'costs no credits,' the distinction between status/result versus generated image, and conditional follow-up behavior. This goes well beyond the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five short sentences, each earning its place: trigger context, requirement/cost, return semantics, conditional actions, and a caution. The most important usage guidance is front-loaded. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with rich annotations and an output schema, the description covers everything an agent needs: when to call, what it requires, what it returns, what to do next, and what to avoid. No meaningful gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is already described as 'UUID of the execution, as returned by dreamlayer_generate.' The description reiterates 'Requires execution_id' but adds no new meaning beyond the schema. Baseline 3 applies because the schema fully carries parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'read the existing execution's canonical status.' The description explicitly contrasts with generating an image ('not a newly generated image'), distinguishing it from dreamlayer_generate and dreamlayer_download. An agent can immediately tell what this tool does and what it does not do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with explicit trigger conditions: 'Use after a timeout, rate limit or uncertain result.' It also provides condition-specific next steps ('If running, wait and resume events; if completed, download') and an explicit negative instruction ('Do not replace an uncertain paid job'). Clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user needs an original image, raster logo concept, product or marketing visual, an edit, transparent cutout, upscale, or reference-based sprite animation. Starts paid work within the user's authorized scope and budget. Text-to-image needs a prompt; other operations need input_asset_id. Select operation explicitly. Image operations cost one credit; sprite beta accepts 7–100 frames and returns a ZIP. Read sprite_pricing, round the whole quote upward once to 0.1 credit and set max_credits. Returns execution_id, status, asset, question and last_event_id. needs_input is a question; running work must be resumed, not replaced. No sprite cancellation; failed/expired holds are restored. Not a vector-logo, print-validation, product-fidelity or animation-quality guarantee.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | What to generate, or how to change the reference, in plain language (1–4000 characters). Required unless respond is used; text_to_image needs it, and a short statement of intent is enough for background_remove or upscale. | |
| options | No | Sprites: supply exactly one of action (legacy preset) or animation_prompt (any subject/action, including turntables). animation_mode defaults to loop for presets, once for custom prompts. Broad requests do not guarantee quality; partial transparency depends on background removal. | |
| respond | No | Answer a previous question. Requires conversation_id. | |
| operation | No | Name it to run deterministically and skip interpretation, so the request cannot come back as a question. Omit it to let DreamLayer read the prompt. | |
| max_credits | No | Spending cap for this request in credits (0.1–100, default 1). Image operations require exactly 1. Sprite jobs must be capped at or above the sprite_pricing quote rounded up to one decimal. | |
| aspect_ratio | No | Output aspect ratio (default 1:1). | |
| input_asset_id | No | From dreamlayer_upload_image. Required for every operation except text_to_image. | |
| conversation_id | No | UUID of an existing conversation to continue, as returned by an earlier dreamlayer_generate call. Required with respond; omit to start a new conversation. | |
| idempotency_key | No | Choose and save one key per logical request before calling. Reuse that key AND identical arguments after an uncertain response. If omitted, a generated key is returned for recovery. |
| Name | Required | Description |
|---|---|---|
| asset | No | |
| error | No | |
| events | No | |
| status | No | |
| question | No | |
| execution_id | No | |
| last_event_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: paid work and credit costs, sprite ZIP output, round-up-to-0.1-credit rule, returned fields (execution_id, status, asset, question, last_event_id), 'needs_input' as a question, requirement to resume rather than replace running work, and the no-cancellation/restore policy for sprite holds. This is far richer than the minimal annotation hints and contains no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured: it front-loads the primary use cases, then systematically covers prerequisites, costs, response fields, and caveats. Every sentence serves a purpose; there is minimal fluff, though the length is warranted by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with nested options and an output schema, the description covers operational context (when to use), financial impact (credits and rounding), input requirements (prompt vs asset), output shape (ZIP for sprites, key return fields), and exception handling (questions, resume, cancellation/restore). The presence of an output schema reduces the need to explain return values, and the description still goes beyond that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds valuable cross-parameter relationships: it pairs prompt with text_to_image, input_asset_id with all other operations, and explains how max_credits must be computed from sprite_pricing (round up to 0.1). These semantics are not present in the input schema and materially help correct parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly names a wide but specific set of deliverables (original image, raster logo concept, product or marketing visual, edit, transparent cutout, upscale, sprite animation) and states the start-up action 'Starts paid work.' This clearly distinguishes it from siblings like upload/download/execution, which handle transport and status rather than generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It opens with 'Use when the user needs...' which provides a clear trigger. It also gives conditional prerequisites ('Text-to-image needs a prompt; other operations need input_asset_id') and explicit exclusions ('Not a vector-logo, print-validation, product-fidelity or animation-quality guarantee'). It does not name sibling tools as alternatives, but the usage context is sufficiently clear for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when an edit, background removal, upscale or sprite animation needs a local reference. Requires an absolute path to PNG, JPEG, WebP or supported camera RAW, up to 200 MB. Uploads that file and returns input_asset_id; starts no paid work. Reuse the asset ID for recovery. Not needed for text-to-image. If upload fails, fix the input or retry upload only.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to a PNG, JPEG, WEBP, or camera RAW. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| expires_at | No | |
| input_asset_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry hints, and the description adds meaningful context: no paid work is started, the returned ID can be reused for recovery, and retry behavior on failure is scoped. It does not contradict annotations and adds cost/safety behavior beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place: opening use case, input constraints, behavior/result, and error handling. The most important decisions (when to use, path constraints) are front-loaded, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter upload tool, the description covers prerequisites, limits, cost impact, return value, reuse, and failure handling. The output schema exists, so return-value details don't need to be spelled out further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is a 3, but the description adds the 200 MB size cap and reinforces absolute path and accepted formats. These constraints are useful for validating input before invocation beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('upload') on a concrete resource (local image file) with a clear outcome (returns input_asset_id). It distinguishes itself from generate by saying it is not needed for text-to-image, making the tool's role unmistakable among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it (edits, background removal, upscale, sprite animation needing a local reference) and when not (text-to-image). Also gives failure-mode guidance ('fix the input or retry upload only'), so an agent knows exactly how to proceed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
dreamlayer_balancedreamlayer_canceldreamlayer_capabilities1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "properties": {
+ "api_version": {
+ "type": "string"
+ },
+ "error": {
+ "properties": {
+ "execution_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "idempotency_key": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "request_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "retryable": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "reason",
+ "retryable"
+ ],
+ "type": "object"
+ },
+ "operations": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+}dreamlayer_downloaddreamlayer_events3 fields changedInput schema / properties / execution_id / descriptionAdded value: +"UUID of the execution, as returned by dreamlayer_generate."Input schema / properties / last_event_id / descriptionAdded value: +"Id of the last event you processed; events after it are returned. Omit to replay from the start."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "properties": {
+ "asset": {
+ "type": [
+ "object",
+ "null"
+ ]
+ },
+ "error": {
+ "properties": {
+ "execution_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "idempotency_key": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "request_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "retryable": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "reason",
+ "retryable"
+ ],
+ "type": "object"
+ },
+ "events": {
+ "items": {
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "execution_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "last_event_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "question": {
+ "type": [
+ "object",
+ "null"
+ ]
+ },
+ "status": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+}dreamlayer_execution2 fields changedInput schema / properties / execution_id / descriptionAdded value: +"UUID of the execution, as returned by dreamlayer_generate."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "properties": {
+ "error": {
+ "properties": {
+ "execution_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "idempotency_key": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "request_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "retryable": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "reason",
+ "retryable"
+ ],
+ "type": "object"
+ },
+ "execution_id": {
+ "type": "string"
+ },
+ "image_job": {
+ "type": [
+ "object",
+ "null"
+ ]
+ },
+ "status": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+}dreamlayer_generate8 fields changedInput schema / properties / aspect_ratio / descriptionPrevious value: -"One of 1:1, 16:9, 9:16, 4:3, 3:4."New value: +"Output aspect ratio (default 1:1)."Input schema / properties / aspect_ratio / enumAdded value: +[
+ "1:1",
+ "16:9",
+ "9:16",
+ "4:3",
+ "3:4"
+]Input schema / properties / conversation_id / descriptionAdded value: +"UUID of an existing conversation to continue, as returned by an earlier dreamlayer_generate call. Required with respond; omit to start a new conversation."Input schema / properties / idempotency_key / descriptionPrevious value: -"Optional. Generated automatically. Supply the SAME one to retry safely."New value: +"Choose and save one key per logical request before calling. Reuse that key AND identical arguments after an uncertain response. If omitted, a generated key is returned for recovery."Input schema / properties / max_creditsAdded value: +{
+ "description": "Spending cap for this request in credits (0.1–100, default 1). Image operations require exactly 1. Sprite jobs must be capped at or above the sprite_pricing quote rounded up to one decimal.",
+ "maximum": 100,
+ "minimum": 0.1,
+ "type": "number"
+}Input schema / properties / optionsAdded value: +{
+ "additionalProperties": false,
+ "description": "Sprites: supply exactly one of action (legacy preset) or animation_prompt (any subject/action, including turntables). animation_mode defaults to loop for presets, once for custom prompts. Broad requests do not guarantee quality; partial transparency depends on background removal.",
+ "oneOf": [
+ {
+ "required": [
+ "action"
+ ]
+ },
+ {
+ "required": [
+ "animation_prompt"
+ ]
+ }
+ ],
+ "properties": {
+ "action": {
+ "description": "Legacy motion preset. Use either action or animation_prompt, not both.",
+ "enum": [
+ "walk",
+ "run",
+ "idle"
+ ],
+ "type": "string"
+ },
+ "animation_mode": {
+ "description": "loop for a seamless cycle, once for a single pass. Defaults to loop for presets and once for custom prompts.",
+ "enum": [
+ "loop",
+ "once"
+ ],
+ "type": "string"
+ },
+ "animation_prompt": {
+ "description": "The motion to animate, in plain language (1–4000 characters), e.g. a jump or a turntable.",
+ "maxLength": 4000,
+ "minLength": 1,
+ "type": "string"
+ },
+ "frame_count": {
+ "default": 12,
+ "description": "Number of frames in the sheet (7–100). The sprite price depends only on this value.",
+ "maximum": 100,
+ "minimum": 7,
+ "type": "integer"
+ },
+ "frame_size": {
+ "default": 512,
+ "description": "Square export canvas, not source detail. Larger exports may be enlarged. Pricing depends only on frame count.",
+ "enum": [
+ 32,
+ 64,
+ 128,
+ 256,
+ 512,
+ 720,
+ 1080
+ ],
+ "type": "integer"
+ }
+ },
+ "type": "object"
+}Input schema / properties / prompt / descriptionAdded value: +"What to generate, or how to change the reference, in plain language (1–4000 characters). Required unless respond is used; text_to_image needs it, and a short statement of intent is enough for background_remove or upscale."Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "properties": {
+ "asset": {
+ "type": [
+ "object",
+ "null"
+ ]
+ },
+ "error": {
+ "properties": {
+ "execution_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "idempotency_key": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "request_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "retryable": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "reason",
+ "retryable"
+ ],
+ "type": "object"
+ },
+ "events": {
+ "items": {
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "execution_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "last_event_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "question": {
+ "type": [
+ "object",
+ "null"
+ ]
+ },
+ "status": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+}dreamlayer_upload_image1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "properties": {
+ "error": {
+ "properties": {
+ "execution_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "idempotency_key": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "request_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "retryable": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "reason",
+ "retryable"
+ ],
+ "type": "object"
+ },
+ "expires_at": {
+ "type": "string"
+ },
+ "input_asset_id": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+}v0.2.0dreamlayer_canceldreamlayer_capabilitiesdreamlayer_eventsdreamlayer_executiondreamlayer_generatedreamlayer_upload_imageScored across 7 tools
Most tools are clearly distinct: balance, capabilities, generate, upload_image, and download each have a single obvious purpose. The only potential confusion is between execution and events, since both take an execution_id and serve post-generation recovery, but their descriptions separate status checking from stream resumption well.
All tools share the dreamlayer_ prefix and snake_case style, but the naming pattern is inconsistent: balance, capabilities, events, and execution are nouns, while download, generate, and upload_image are verbs or verb_noun. It remains readable and predictable in prefix, but not a uniform verb_noun convention.
Seven tools is a well-scoped set for a paid async image generation workflow. Each tool covers a necessary stage—checking credits, reading contract terms, uploading inputs, generating, checking status, resuming streams, and downloading results—without bloat.
The lifecycle is well covered: billing check, capability discovery, upload, generation, status retrieval, event resumption, and download. Minor gaps exist around asset management and cancellation, but the descriptions indicate these are either unnecessary or unsupported rather than critical missing operations.
Generate AI images and videos from any compatible MCP client.
Generate AI images, video, music, and sound effects, and upscale them, from any MCP client.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Generate on-brand images from your AI agent: design, edit, and render templates over MCP.
