NexDoc Design

Update design

update_design

Destructive

Start an update run on an existing job with edit instructions (diff-style). NEVER start an update while a run on this job is still queued or running — the API rejects it with 409. If wait_for_run said still_running (or the user reports an issue mid-run), report status and WAIT until the run completes or fails before updating; only cancel or re-run if the user explicitly asks. Always tell the user job_id and the NEW run_id. Do not share the previous viewer_url — that preview is the old design. If the result includes concurrency_notice, show that reminder. Same wait policy as create_design: wait_for_run once on the new run_id, then offer email instead of looping. Only share viewer_url after THIS run's status is completed. New photos: request_file_upload (or upload_file on stdio) then file_ids. Do not base64 a large image. Do not generate a replacement.

Input Schema

TableJSON Schema

Name	Required	Description
`wait`	No	Avoid. Prefer wait_for_run once after this returns.
`format`	Yes	Keep the same format unless changing medium
`job_id`	Yes
`content`	No
`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	Edit instructions against the current design
`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).

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.6/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is covered. The description adds valuable behavioral context: the 409 rejection on concurrent runs, the need to report job_id and NEW run_id, not sharing the old viewer_url, the concurrency_notice reminder, and the wait-then-email policy. It doesn't detail failure modes beyond 409, but the annotations plus description cover the critical behaviors.

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 dense but every sentence carries operational guidance. It front-loads the core action and the most critical constraint (never update while running). It's longer than ideal, but for a complex mutation tool with 11 parameters and multiple sibling tools, the length is justified. The structure could be slightly improved by grouping related constraints, but it's well-organized.

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 mutation tool with 11 parameters, destructive annotations, and 15 sibling tools, the description covers the full decision tree: when to call, what to avoid, how to handle files, what to report, and what to do after. The output schema exists, so return values don't need explanation. The only minor gap is not detailing the exact 409 error handling flow, but the description explicitly says to wait and report.

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

Parameters4/5

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

Schema coverage is 82%, so the schema already documents most parameters. The description adds meaningful guidance beyond the schema: the diff-style nature of instructions, the file upload preference chain (request_file_upload → upload_file → asset_files → asset_paths), and the warning against base64 for large images. It doesn't explain every parameter, but the schema covers those, and the description adds the decision logic.

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 specific verb+resource: 'Start an update run on an existing job with edit instructions (diff-style).' This clearly distinguishes it from create_design (new job) and refresh_preview (preview refresh), and the diff-style qualifier adds precision. The title 'Update design' is generic, but the description fully compensates.

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 guidance: never update while a run is queued/running (409), wait for run completion, and only cancel/re-run on explicit user request. It also names sibling tools (wait_for_run, request_file_upload, upload_file, upload_data) and states the same wait policy as create_design. This is exemplary routing guidance.

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?