NexDoc Design

Create design

create_design

Destructive

Create a job (or reuse job_id) and start a generative run. Omitting job_id ALWAYS creates a NEW job — call at most ONCE per user request. If you already have a job_id (including from a prior create_design error), pass it or use update_design; never call create_design again without job_id for the same request. The API rejects a second run on a job while one is still queued or running (409) — if a run fails or stalls, report it and ask the user before cancelling or re-running. Always tell the user job_id and run_id as soon as this returns. If the result includes concurrency_notice, show that reminder (pay-as-you-go accounts run one design at a time). Do not set wait:true. If the user asked to be emailed (including in the original request), set notify_email:true here immediately — do not wait until after wait_for_run. After create, call wait_for_run ONCE (default ~45s). If still_running and they have not already asked for email, stop polling, show the IDs, and offer notify_run_email. Photos/logos: prefer request_file_upload (or upload_file on stdio) then pass file_ids — never compress or generate a replacement. asset_paths is stdio-only; asset_files base64 is a last resort for tiny files. After completion, return viewer_url and offer export (pdf/html/png) — do not publish unless the user asks.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	No	Job name when creating a new job
`wait`	No	Avoid. Prefer wait_for_run once after create so the user sees job_id first.
`format`	Yes	Format slug, e.g. landing-page, report, business-card
`job_id`	No	Existing job id to reuse. Required when retrying after a partial failure or continuing the same request — omitting this creates a duplicate job.
`content`	No	Source copy (markdown/text)
`file_ids`	No	file_… ids from request_file_upload / upload_file after status is ready. Preferred for photos and large files — do not also base64 them.
`asset_files`	No	Last-resort inline bytes for tiny files. Prefer request_file_upload + file_ids. On sandboxed clients whose PUT to storage is blocked, prefer the upload_data tool (it routes bytes through the API host) before using this.
`asset_paths`	No	Local filesystem paths to upload (stdio MCP only). Prefer upload_file then file_ids for large photos. Remote/OAuth MCP cannot read the client's disk — including /mnt/user-data/uploads/ — use request_file_upload + PUT + file_ids instead. Never omit a user photo or generate a replacement.
`timeout_sec`	No	Only with wait:true. Default 45 seconds, capped at 90.
`content_path`	No	Local path to a content file (stdio). Remote MCP: put copy in content instead.
`instructions`	Yes	Design direction / edit notes
`notify_email`	No	If true, email the account owner when the run finishes. Set this immediately when the user asks to be emailed (including at the start of the request). Do not wait until after wait_for_run.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`error`	No
`job_id`	No
`run_id`	Yes
`status`	Yes
`log_tail`	No
`next_step`	No
`charge_usd`	No
`created_at`	No
`viewer_url`	No
`commit_hash`	No
`completed_at`	No
`notify_email`	No
`summary_diff`	No
`still_running`	No
`concurrency_notice`	No
`previous_preview_stale`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 17, 2026

changedInput schema / properties / asset_files / description

Previous value: -"Last-resort inline bytes for tiny files. Prefer request_file_upload + file_ids."New value: +"Last-resort inline bytes for tiny files. Prefer request_file_upload + file_ids. On sandboxed clients whose PUT to storage is blocked, prefer the upload_data tool (it routes bytes through the API host) before using this."

changedInput schema / properties / asset_files / items / properties / data_base64 / description

Previous value: -"Base64-encoded file bytes. Last resort for tiny files on remote MCP. Prefer request_file_upload + PUT + file_ids so the original is not compressed. Do not generate a substitute image."New value: +"Base64-encoded file bytes. Last resort for tiny files on remote MCP. Prefer request_file_upload + PUT + file_ids so the original is not compressed. Do not generate a substitute image. If the PUT failed with a network/allowlist error, stop and tell the user — never silently switch to base64 for a logo or photo (corrupted inline bytes decode but render blank)."

Changed4 schema fields changedSep 17, 2026

changedOutput schema / properties / commit_hash / type

Previous value: -"string"New value: +[
+  "string",
+  "null"
+]

changedOutput schema / properties / error / type

Previous value: -"string"New value: +[
+  "string",
+  "null"
+]

changedOutput schema / properties / log_tail / type

Previous value: -"string"New value: +[
+  "string",
+  "null"
+]

addedOutput schema / properties / summary_diff

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

First observedSep 15, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Although annotations already signal destructiveness and non-readonly behavior, the description adds critical operational details: duplicate job creation on omitted job_id, 409 rejection while a run is queued/running, concurrency_notice handling, email notification timing, and the recommendation to avoid wait:true. This goes well beyond the annotations and meaningfully shapes agent 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 long but dense with operational directives, and the most critical constraint ('call at most ONCE per user request') is front-loaded. Every sentence carries behavioral weight. The main weakness is the single-wall-of-text format; bullet or section structure would improve parseability, but nothing is wasted.

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

Completeness5/5

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

For a complex, destructive creation tool with 12 parameters, the description covers the full lifecycle: creation, retry/reuse rules, file upload precedence, error/409 handling, wait_for_run handoff, email notification, and post-completion actions like returning viewer_url and offering export. With an output schema present, no critical information is missing for an agent to call this correctly.

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

Parameters5/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial cross-parameter meaning: wait:true should be avoided, asset_paths is stdio-only, asset_files is a last resort while file_ids is preferred, and notify_email should be set immediately when the user asks to be emailed. These constraints are not inferable from the schema alone.

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?

The description opens with a precise verb+resource statement: 'Create a job (or reuse job_id) and start a generative run.' It also differentiates from siblings by explicitly naming update_design and wait_for_run as related but distinct tools. An agent can immediately understand what create_design does and how it differs from other design-flow tools.

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?

The description gives explicit when-to-use and when-not-to-use guidance: call at most once per user request, always reuse an existing job_id rather than calling again, use update_design for continuations, prefer request_file_upload/upload_file for photos, and never set wait:true. This is strong routing and exclusion guidance that leaves little to inference.

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

All NexDoc Design tools Inspect

Try in Browser

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

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?