Agent reference: workflow & run tools

This page is the lookup surface for the 33 MCP tools that author, run, and accept workflows: 23 workflow_* tools, 3 workflow_node_instructions_* tools, and 7 mission-run/changement tools, in eight groups. For step-by-step procedures, use the cookbook; when a call refuses, the refusals page maps every token to a recovery.

Who this is for

You are an MCP-connected agent — or the operator driving one. Every tool on this page returns the same envelope: { success, data } on success, { success: false, error, code } on refusal. All of these tools require tenant-admin rights; if a call fails authorization, that is a permissions problem, not a workflow problem.

This page tells you what each tool does and what it returns. For how the machinery works underneath — compilation, branches, seals — read the workflow architecture chapter.

The two legal entry surfaces

A published workflow executes through exactly two surfaces: workflow_invoke and mission_run_start — everything else on this page authors, inspects, or accepts.

• workflow_invoke — workflow-first. Compiles a published version into a fresh mission it creates for you. Use it when the work has no mission yet.
• mission_run_start — a run on an existing mission. The run gets its own branch off the mission tip and enters the acceptance loop: born Proposed, then you accept or discard it. Use it when the work belongs to a mission you already have.

The human-side walkthrough of that loop is Runs, acceptance & changements.

Authoring & lifecycle (9 tools)

These take a graph from empty draft to frozen published version. Drafts are the only editable state; publishing freezes the graph — see The workflow lifecycle.

Composition (3 tools)

Workflows compose by reference: a FlowRef node embeds another published workflow as a sub-workflow.

Discovery & observation (6 tools)

Execution (1 tool)

workflow_invoke — run a published version, workflow-first.

• Inputs: workflowId, version (must be ≥ 1 — running "whatever is latest" is never implicit), optional objective, model, provider, paramsJson, projectId, presetId (+ forceOnAllCallSites), agentBudgetJson (+ forceBudgetOnAllAgentSites).
• Parameters bind at compile time. The values in paramsJson are bound when the graph is compiled into the new mission's plan; nothing rebinds mid-run.
• Model resolution is explicit. model and provider are required unless tenant defaults resolve them — there is no silent model fallback.
• Presets are the preferred lever. presetId runs this invocation with a named preset instead of a raw model; an unknown preset refuses with NOT_FOUND rather than falling back. By default it replaces only the workflow-level default preset — a step that pinned its own preset at edit time keeps it — unless you also pass forceOnAllCallSites.
• Per-run agent budgets. agentBudgetJson adjusts agent budgets for this run only, applied axis by axis. By default a stated axis stands in for the engine default only — it fills the axes a step's authored budget leaves unstated, and a step that authored that axis keeps its own value — unless you also pass forceBudgetOnAllAgentSites, which pushes the stated axes onto every agent site, outranking what the step authored. A malformed override refuses with VALIDATION_ERROR before any mission is created.
• Project targeting is explicit and fail-loud. projectId (id or slug) aims the run's writes at a project: an unknown target refuses with NOT_FOUND and a non-Active project with CONFLICT, both before any mission is created. Omit it and the run lands in the tenant's default project — recorded as such in the mission's provenance.
• Returns the new missionId with step, gate, and control counts. Every gate is born paused behind a pending decision.
• Follow-ups: mission_get to watch the mission, decision_list to find pending gates, workflow_run_nodes for per-node status.

Cloning (2 tools)

System templates (2 tools)

Templates are representational: cloning gives you a graph to own and edit, not a wire into the platform's internal flows. The full enumeration of the 22 lives on System templates.

Node instructions (3 tools)

Coder and agent nodes can carry an instruction binding — override text that replaces the node's authored instructions at the next dispatch, without touching the published graph or its checksum. Exactly one binding applies — the most specific wins: run > project > tenant > global.

Only manually-set slots are writable through these tools; a slot owned by the platform's prompt-engineering machinery refuses with CONFLICT. ARDS proposing prompt improvements on its own is not in v1; if that lands, proposals will arrive as decisions you approve — nothing will ever apply itself. See Governance for the human-side view.

Mission runs & changements (7 tools)

The acceptance loop on an existing mission. Strict-sequential by default: one undecided run at a time, each accepted run landing as one changement on the mission branch. Pass the same groupId to several starts to open a competition instead — one winner, siblings rejected.

The human-side walkthrough — accept, discard, revert, competition — is Runs, acceptance & changements.

Mission context

Four neighbouring tools you will meet in every workflow session; the full mission surface is documented in Missions & tasks.

mission_propose drafts a mission and routes it for approval instead of creating it outright — the proposal arrives as a decision a human accepts or rejects. You never approve your own proposal.

mission_create creates a mission directly. Attach a workflow at creation, or start runs on it later with mission_run_start.

mission_decompose asks the planner to break a conversation-born mission into tasks. Missions that carry a workflow skip this: the graph already is the plan.

decision_respond is the single gate-resolution verb. Its resolutions map onto a paused gate as: approve releases the gate once prior steps complete; skip cancels the gated step; fail fails it. Leaving the decision unresolved keeps the run paused. Pending gates are listed by decision_list and appear in the Decisions queue.

Status vocabularies

Normative token tables. Tokens are returned verbatim; match on them exactly. Per-token recovery detail lives in Refusals & failure modes.

Run-start statuses

Returned by mission_run_start. One success token, ten refusals.

Run-accept statuses

Returned by mission_run_accept. One success token, six refusals.

Run outcomes

The lifecycle of a run itself — the same tokens as the states cheatsheet.

Version statuses

The only legal transitions are Draft → Published → Archived.

Node run states

Per-node statuses as reported by workflow_run_nodes and the mission_run_get roll-up.