references/lifecycle-and-debugging.md
Workflow tool reference
The MCP tools for the workflows product, grouped by job. The lifecycle that strings them together (build → test → edit → enable → monitor) lives in SKILL.md; this is the catalog of which tool does what.
Tool inventory
Author & lifecycle
workflows-create— create a workflow. Always created as adraft.workflows-patch-graph— the way to edit a workflow's graph. An ordered, id-addressed op list (update_action,add_action,remove_action,add_edge,remove_edge,replace_action_edges) applied atomically;update_actiondeep-merges (anullleaf deletes a key). Returns the full updated graph, so no re-fetch. On an active workflow, patches stage a draft (published withworkflows-publish) instead of changing what's running.workflows-patch-action-email— the way to edit the email inside afunction_emailstep. The template patch's design ops (id-addressed Unlayer blocks) plus anemail_patchmerge for subject/preheader/text/recipients; HTML is re-rendered server-side so it can't go stale. Stages a draft on active workflows, same asworkflows-patch-graph.workflows-update— fallback editor. Top-level metadata a graph patch can't express (renaming), or an escape hatch to replace the whole workflow whenworkflows-patch-graphwon't land a change. On an active workflow, content fields stage a draft; name/description apply live.workflows-enable— draft →active. It starts running on real people, so test first and get the user's explicit approval before enabling. Later changes stage as drafts and take effect only on publish.workflows-publish— apply an active workflow's staged draft to its live config. Call withoutconfirmfirst: it echoesin_flight_runs+draft_updated_atand changes nothing. Get the user's go-ahead, then confirm with that exactdraft_updated_at(409 = draft changed under you; re-read).workflows-discard-draft— throw the staged draft away; live config untouched. Idempotent.workflows-archive— retire a workflow.workflows-get— full definition: trigger, edges, actions, exit condition, variables, stageddraft/draft_updated_at(null when nothing staged), and read-onlyschedules(any recurring schedules attached to the workflow; there's no separate list-schedules tool).workflows-list— all workflows with name, status, version, trigger, timestamps.
Test & inspect
workflows-test-run— runs one step at a time, it does not traverse the whole graph in one call. Omitcurrent_action_id(or set it to the trigger) to run the first step; the result gives younextActionId, which you pass ascurrent_action_idon the next call. Walk the workflow step by step this way; to test a specific branch, setcurrent_action_idto that node. Skipdelaynodes by jumping to the action after them (delays aren't simulated). Pass test data viaglobals({event, person, groups}), shaped like the trigger's real payload: aneventtrigger needs an event matching its filters, and aninternal-eventtrigger needs an event named in itsfilters.events(for the Slack trigger, a$slack_message_receivedevent with the Slack property bag) and no person (see graph-schema.md), best copied from a past run viaworkflows-get-invocation. The trigger step evaluates filters forevent,internal-event, and warehouse-row triggers;status=skippedmeans this payload would not fire the trigger. Fix a fabricated payload to match the trigger; treat a skip on a real, copied payload as a broken trigger filter instead. Other trigger types pass any payload through. Async actions (HTTP/email/SMS) mocked by default;mock_async_functions=falsefires real side effects. Returns the step's execution trace.use_draft=truetests an active workflow's staged draft instead of its live config — always do this beforeworkflows-publish.workflows-logs— execution log entries (timestamp, level DEBUG/LOG/INFO/WARN/ERROR, message). Filter by level, text, time range, limit.
Batch & schedules
workflows-run-batch— one-off broadcast to the batch audience (one run per matching person).workflows-schedule-create— attach a recurring schedule (RRULE) to a batch/schedule workflow.workflows-update-schedule— change a schedule's RRULE, start time, timezone, or variable overrides.workflows-list-batch-jobs— past batch runs (one-off + schedule-triggered), with the audience filters and variable overrides each used. No per-run status here — use logs/stats for outcomes.workflows-blast-radius— preview how many people a set of audience filters matches before dispatching.
Monitor & debug
workflows-global-stats— at-a-glance health across ALL workflows: per-workflow succeeded/failed over a window, most-failing first.workflows-stats— one workflow's success/failure time-series (hour/day/week), with breakdown by kind/name.workflows-list-invocations— per-recipient outcomes (one per person/event): status, error_kind/error_message, distinct_id, person_id, timings. Filterstatus=failed.workflows-get-invocation— a single invocation incl.invocation_globals(the raw triggering payload that ran). The broad→narrow drill-down (global-stats → stats → invocations → get-invocation → logs) is in SKILL.md.
Discover function templates (for function nodes)
cdp-function-templates-list— the live catalog of function templates (filtertype=destination). Source of truth for which integrations exist; don't hardcode template ids.cdp-function-templates-retrieve— one template's full detail including itsinputs_schema. Read this before building afunctionnode'sinputs.- Don't come here for
webhook/manual/tracking_pixeltriggers orfunction_email/function_sms/function_pushsteps — those take fixed literal template ids that this catalog never lists. See graph-schema.md.
Email templates (compose and edit with the designing-email-templates skill)
workflows-create-email-template— create a new template.workflows-patch-email-template— the way to edit an existing template's design. Id-addressed ops over the Unlayer blocks, applied atomically; same shape asworkflows-patch-graph. Use for any change to an existing design.workflows-update-email-template— full-replace, last resort (seeworkflows-updatevsworkflows-patch-graph).workflows-list-email-templates,workflows-get-email-template/workflows-show-email-template— list and read.