Run Workflow

Key rules

• Presigned URLs — copy url fields verbatim from all responses — HMAC-signed; one changed character → asset_download_failed.
• ASK-FIRST (assets) — draft/published workflows ONLY, NOT golden demos/interfaces — before running a draft or published workflow, ask the user whether to run with the existing/prior assets or supply their own, UNLESS their prompt already established it (they attached files or said "use the defaults"). Prefer to verify the prior assets are still hydratable (warm presigned URLs) before running; if an asset can't be hydrated, ask for a fresh one rather than submitting blind. A golden demo/interface/preset is the OPPOSITE default: submit inputs: [] directly, no confirmation, no pre-verification — its baked assets are curated and durable, not a stale leftover from a prior run. Only ask there when the user's own prompt is itself ambiguous about wanting their own assets.
• Fast rerun — to rerun a workflow with the same assets, submit workflowId ALONE (no actions/connections, inputs: []) so the client uploads/re-signs nothing and submit returns instantly. Only pass the inline graph for preset/inline sources with no published workflowId, and then reuse workflowJson's presigned input URLs verbatim (re-upload only [URL expired …] inputs). Passing the inline graph on a by_id rerun re-resolves every asset and stalls run_workflow_submit for minutes. Not for a first encounter (inspect_run → executionCount === 0, any source — never-run draft, freshly imported workflow, un-invoked preset): there is no prior run to reproduce, so its baked assets aren't "the same assets from last time." If they're all still resolvable (rerunAssets.status: "all_resolvable") tell the user it can run as-is and let them confirm; if some_missing, collect the real inputs for a first run instead of submitting the id alone. Interfaces/presets are a special case of the above, at every run count, not just the first: an interface always ships with its own baked defaults, so workflowId + inputs: [] uses them — regardless of how many times it's been run before, and regardless of what a PRIOR run happened to submit (a one-off custom asset from a previous run, including a failed one, is never silently reused). Per the ASK-FIRST (assets) rule above, this is the OPPOSITE default from a plain workflow — submit inputs: [] directly with no confirmation and no pre-verification; pass inputs only when the user's own prompt already asked to swap an asset. See references/diagnostics.md.
• session_id — compose_workflow and get_featured_workflow both return one. Retain it for the whole conversation; pass it to run_workflow_submit, publish_workflow, save_workflow instead of re-serializing actions/connections. The server holds it for 2 hours.
• Batch inputs — pass ALL images/assets into a SINGLE run_workflow_submit call (use the content array on the input node). Never make separate calls per image.
• publish vs save — publish_workflow creates a reusable API endpoint (workflowId + curl): use for "publish", "make it callable", "create an API". save_workflow (formerly save_workflow_to_acp) saves to the user's Adobe cloud for Workflow Builder: use for "save", "keep editing", "open in the UI". If ambiguous, ask before proceeding.
• History — inspect_run for a single item; list_all_workflows for any broad "list my workflows" intent; list_workflow_history only for filtered/date-ranged own-workflow queries. Never read local workflow.json/inputs.json. Details in references/diagnostics.md.
• Missing required input — never silently resolve it (no substituting a simpler action, no auto-generating a placeholder/mask, no scripted workaround). Stop and present options. See references/compose.md.

Anti-patterns

These traps are non-obvious and not clearly covered by the sections above:

• Conflating "tools" with "actions/nodes" — these are different vocabularies. "Show me the tools" / "what MCP tools do you have" asks about the MCP tool surface (list_actions, compose_workflow, run_workflow_submit, etc.) — answer directly from your own visible tool list, no tool call. "What actions are available" / "show me the nodes" asks about the workflow action/node catalog — call list_actions. Never answer one with the other.

• Running a draft/published workflow without first asking about assets — don't. Before running one, ask whether to use the existing/prior assets or the user's own, UNLESS their prompt already established the choice (they attached files or said "use the defaults"). Prefer to verify the prior assets are still hydratable (warm presigned URLs) before running; if one can't be hydrated, ask for a fresh asset rather than submitting blind. See the ASK-FIRST (assets) rule under Key rules. A golden demo/interface is the opposite case — don't ask, and don't call inspect_run first to "verify" its baked assets either: submit run_workflow_submit({workflowId, inputs: []}) directly. Its baked defaults are curated/durable, inspect_run inspects a prior execution (nothing to find for a never-run interface, and calling it first only risks an unrelated 404), and submit's own preflight already surfaces a real problem via needs_reattach if one exists.

• Answering a new listing intent from a PRIOR list result instead of a fresh tool call — don't. Each row in the Tool routing table above is a distinct tool over a distinct data source; a follow-up question that names a different entity — e.g. asking about golden demos right after listing plain workflows for the last week, or asking for interfaces right after a list_workflow_history query — is a NEW intent, not a filter over what is already in context. Route it through the table again and call the matching tool fresh. Never search, filter, or answer from a previously-returned list just because a similar-sounding request landed a moment ago — list_golden_workflows/list_interfaces/etc. are separate catalogs the prior call never fetched.

• Omitting csvData from a deterministic compose_workflow rewire when the user has a CSV — csvData is the only input that drives parse-data routing; without it all image ports direct-wire, causing item-count mismatches at runtime ("image" has 4, "Headline" has 16). The message parameter cannot override routing. See references/featured-and-templates.md.

• Rewiring a custom template (.indd/.psd) through the message/LLM path or a bare "swap" — leaves the featured base graph's lower-case merge ports (e.g. headline) in place, so InDesign data merge (case-sensitive) fails 107013 against a Headline placeholder after a long merge. Always use compose_workflow(customTemplateUrl=…), which rebinds each port to the template tag's exact case. Re-casing the CSV header does not fix this (the CSV header is discarded; the data-source header comes from the merge port name). On a custom-template + CSV run also run the case-insensitive tag ↔ CSV coverage check (every tag has a column; image columns keep @). See references/featured-and-templates.md.

• Placing a merge-data template in an input node's content[] — for merge-data / data-merge-psd workflows, the .indd or .psd template MUST be supplied via inputs[].template.presignedUrl on the merge node itself, not as a content[] item on input-files or any other input node. Placing it in content[] silently mis-routes it and the run fails with "merge-data requires at least one template file" (and a write-files cascade). run_workflow_submit now returns status:"missing_template" with misplacedOnNodeId when it detects this mistake. inspect_run surfaces required-but-empty template slots as reattachVia:"template" leaves so you know which node id to target before submitting.

• Passing a template as a workflowTemplateUrl / templateUrl / indesignTemplateUrl parameter — those are graph node-data authoring fields (often a non-presigned CloudFront reference) the backend never reads at runtime; the flattener strips them from execution parameters. A merge node whose only "template" is a *TemplateUrl still fails "requires at least one template file". The sole runtime source is parameters.templates[] (from inputs[].template.presignedUrl, or the composed template on a rewired session). See references/featured-and-templates.md.

• Supplying an image input without name — a missing name breaks per-row @image basename matching. (A rewired session_id now injects the composed template automatically — you no longer need useSessionDefaults: true just to get the template; that flag now only governs the broader non-template session defaults such as text fills.) See references/featured-and-templates.md.

• Swapping in a different template on a bare rerun and assuming it just runs — for a merge-data/data-merge-psd node, the input ports ARE the old template's tags, so a new template whose placeholders differ misroutes content and fails late with InDesign 107013. On a bare inputs[].template swap (no composed session_id), run_workflow_submit now describes the new template and diffs its tags against the node's current ports: an empty diff runs as-is; a non-empty diff returns needs_rewire (with the concrete diff) → route through compose_workflow; a mismatch on a source with no Matrix graph returns no_editable_graph (edit in Builder). Don't force-resubmit past needs_rewire/no_editable_graph. Read a node's expected tags up front via inspect_run's mergeTemplatePorts. See references/diagnostics.md.

• Submitting a graph with a wiring mistake — run_workflow_submit now structurally validates any locally-resolved graph (the same checks as validate_workflow) before the backend call and returns status:"invalid_workflow" with an errors[] list for the un-runnable faults: a required input port with no incoming connection, two connections into one port, a cycle, or a connection to a non-existent node. Fix the wiring (or re-run compose_workflow / validate_workflow) and resubmit — don't submit as-is. Orphaned/unreachable nodes are non-fatal: they ride along as a warnings[] array on a submitted result. See references/diagnostics.md.

• Forgetting to offer persist after a re-wired run — when a submit ran a rewired session_id, the submitted result carries a postRun block; once completed, offer save_workflow / publish_workflow / create_preset (keyed off postRun.sessionId) so the new wiring isn't lost. A plain input-swap rerun has no postRun — don't prompt there. See references/featured-and-templates.md.

• Rewriting a merge CSV's @image filename cells into presigned URLs — submit the CSV as-is; the runtime resolves filenames to wired assets by basename. Only edit the CSV when a diagnosed failure points to a filename↔asset mismatch, and only after telling the user.

• Setting interfaceRerun: true on an ordinary published/inline re-run — use it ONLY when reproducing a preset/interface run (rerun.method: "inline_exact" and isInterface: true). See references/diagnostics.md.

• Calling display_asset in Claude Desktop — the 1MB response cap makes inline display fail; present text URLs only and offer download_output with saveTo for local saving.

• Dropping createdBy/workflowId when a large list_all_workflows result gets grep/jq'd, or separately re-pasting the standalone typeSummary field before renderedTable — select and render the response's renderedTable field verbatim (it already contains, in order: golden demos, the type-count block, then a ready-to-paste markdown table with all 5 required columns) instead of reconstructing any part of it from individual per-row fields, and instead of also pasting the standalone typeSummary field separately (it's already embedded at the correct position inside renderedTable — pasting both duplicates the block). Pulling only nameDisplay/lastModifiedDisplay/statusDisplay and collapsing createdBy into prose ("all authored by you") is exactly the recurring failure renderedTable exists to prevent.

• Calling list_golden_workflows separately before list_all_workflows for a plain "give me my workflows" intent, or trimming/summarizing the golden-demo rows at the top of list_all_workflows's renderedTable into a one-line mention like "golden demos are also available" — see "Workflows-listing intent — ONE call, THREE sections" under Tool routing above: list_all_workflows is the ONLY call needed; its renderedTable already contains the golden rows, then typeSummary, then the own-workflows table, in that order. Present the whole string verbatim, top to bottom — do not split it, do not call list_golden_workflows too, and do not collapse any section into prose.

• Falling back to compose_workflow when a published workflow won't run — if "run this published workflow" fails at every submit shape with Workflow has no input actions / Workflow with actions and connections is required / invalid_input_target + empty validInputNodeIds: [] / Circular dependency … action: undefined, the published definition is corrupt (published from a raw React-Flow graph, not the executable contract). Diagnose in one line and STOP — never re-compose to rebuild it; the user asked to run an existing workflow, not author a new one. The fix is to re-publish it correctly (compose_workflow session_id or the Workflow Builder). For a correctly published first run, discover input node ids via the submit preflight (workflowId + inputs: [] → needs_reattach.rerunAssets.inputs[].nodeId), NOT from inspect_run (which reports rerunAssets: none for a never-run published workflow). See references/diagnostics.md.

• Overriding a 3D-scene node (input-3d) via inputs[] — that override is NOT wired on the MCP path; the ingestion layer used to silently drop it. run_workflow_submit now returns status:"unsupported_override" (with the nodeId/actionType) instead — route the user to the Workflow Builder for 3D-scene wiring rather than resubmitting. See references/diagnostics.md.

• Trusting resolvedVia without checking durabilityCoverage — every rerunAssets / needs_reattach envelope now carries durabilityCoverage: "authoritative" | "warmth-guessed". authoritative (CAS/preset — a real durability map) means the warm-url / durable-storage / unavailable verdict is backend-backed; warmth-guessed (draft/legacy/native — no durable store by design) means it's inferred from URL expiry alone, so a warm-url there can go cold without warning. Weight your ASK-FIRST re-attach nudges accordingly. See references/diagnostics.md.

• Assuming run_workflow_submit always prompts before reusing baked assets — the automatic needs_confirmation guard fires ONLY on a batch-anchored bare rerun (reusing that specific run's frozen assets). A never-run PUBLISHED workflow does NOT auto-prompt either — YOU still owe the ASK-FIRST question there. A getPresetDefinition-resolved INTERFACE also never auto-prompts, but for the opposite reason: its baked defaults are trustworthy, so no ASK-FIRST is owed there at all — submit inputs: [] directly. See references/diagnostics.md.

References

• Workflow Builder API docs — firefly-api-specs for direct Firefly REST calls
• On-demand: references/ — featured-and-templates, compose, diagnostics, asset-input, alert-rca