add_playbook_step
Add one step to a RUNNING playbook (a playbook that has already been started). The playbook template it came from is not changed. The new step is a normal step of the running playbook: same visibility, project and category as its other steps, stage Accepted, counted in its progress and picked up by generate_cycle_content.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
team_id | integer | Yes | — | Team id to act in (from initialize instructions or get_current_user_info). Required on external MCP; optional in bound sessions. |
run_id | integer | Yes | — | The running playbook to add the step to (run_id from list_playbook_cycles or instantiate_playbook). |
title | string | Yes | — | The step's title. |
description | string | No | — | What the step is for. |
prompt | string | No | — | Content steps: the generation prompt. {Variables} are filled from the running playbook's own values. |
blueprint_uuid | string (uuid) | No | — | Content steps: blueprint to write from (from list_blueprints). |
kind | string | No | — | content (default), checklist or action. An action step needs action: { instruction } and an owner_user_id (the owner's in-app agent does it with their connected apps when they press Run in Marcora, not over MCP). |
use_cycle_source | boolean | No | — | Content steps only: true so this step's generation also sees a live snapshot of the cycle (topic/details, variables, anchor, and team-visible steps' title, owner, dates, status); private steps are omitted and the generated document footer states how many were left out, not other steps' text. |
draft_lead_days | integer | No | — | Content steps only: whole calendar days (0-365) before due_date when scheduled auto-generate starts (rejects non-integers and null; defaults to 3 when do_on_date is newly enabled, 0 on existing schedules). Note: later sending draft_lead_days (or schedule_time_zone, title, description, prompt, blueprint_id, project_id, reference_document_ids (even []), builds_on_plan_ids when any link/doc remains, context_collection_ids, targeting_dimension_ids, or generation_settings) via update_plan turns an enabled auto-generate schedule off; MCP cannot turn auto-generate on (stored lead only; when the owner turns it back on in the app, an unset lead resets to 3, so pick the intended lead there). |
action | object | null | No | — | Required for kind "action": { instruction }, one or two plain sentences saying what to do (up to 12,000 characters, {Variable} allowed). |
owner_user_id | integer | No | — | Team member who owns the step. Defaults to you. Do not send together with owner_name. |
owner_name | string | No | — | A typed owner (an agent, or anyone who is not a team member) instead of owner_user_id. Not for an action step. See list_playbook_owner_names. |
due_date | string | No | — | YYYY-MM-DD deadline the step is due. |
due_time | string | No | — | Optional time of day it is due, "HH:MM" 24-hour, no time zone. Needs due_date. |
goes_out_date | string | No | — | Content steps: YYYY-MM-DD the finished content goes out. |
goes_out_time | string | No | — | Content steps: optional time of day it goes out, "HH:MM". Needs goes_out_date. |
reviewer | string | No | — | Deprecated and ignored (not written or returned by MCP; existing values are kept). |
after_plan_uuid | string (uuid) | No | — | Place the step right after this step (plan_uuid from get_playbook_cycle). Omit to add it at the end. |
builds_on | array of string | No | — | plan_uuids of EARLIER steps of this running playbook whose finished content this step draws on. A later step is refused. |
targeting_dimension_ids | array | null | No | — | Content steps only (ignored on checklist/action steps): targeting dimension option IDs (list_targeting_dimensions) to attach to this step. Omit, [], or null starts empty (nothing inherits from the cycle); unavailable IDs are refused. |
context_collection_ids | array | null | No | — | Content steps only (ignored on checklist/action steps): context collection IDs (list_context_collections) to attach to this step. Omit, [], or null starts empty (nothing inherits from the cycle); unavailable/unreadable IDs are refused. |
Input Schema
{
"type": "object",
"required": [
"team_id",
"run_id",
"title"
],
"properties": {
"kind": {
"enum": [
"content",
"checklist",
"action"
],
"type": "string",
"description": "content (default), checklist or action. An action step needs action: { instruction } and an owner_user_id (the owner's in-app agent does it with their connected apps when they press Run in Marcora, not over MCP)."
},
"title": {
"type": "string",
"description": "The step's title."
},
"action": {
"type": [
"object",
"null"
],
"required": [
"instruction"
],
"properties": {
"instruction": {
"type": "string",
"description": "What to do, in plain language; {Variable} allowed."
}
},
"description": "Required for kind \"action\": { instruction }."
},
"prompt": {
"type": "string",
"description": "Content steps: the generation prompt. {Variables} are filled from the running playbook's own values."
},
"run_id": {
"type": "integer",
"description": "The running playbook to add the step to (run_id from list_playbook_cycles or instantiate_playbook)."
},
"team_id": {
"type": "integer",
"minimum": 1,
"description": "Team id to act in (from initialize instructions or get_current_user_info). Required on external MCP; optional in bound sessions."
},
"due_date": {
"type": "string",
"description": "YYYY-MM-DD deadline the step is due."
},
"due_time": {
"type": "string",
"description": "Optional time of day it is due, \"HH:MM\" 24-hour, no time zone. Needs due_date."
},
"reviewer": {
"type": "string",
"deprecated": true,
"description": "Deprecated and ignored (not written or returned by MCP; existing values are kept)."
},
"builds_on": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "plan_uuids of EARLIER steps of this running playbook whose finished content this step draws on. A later step is refused."
},
"owner_name": {
"type": "string",
"description": "A typed owner (an agent, or anyone who is not a team member) instead of owner_user_id. Not for an action step. See list_playbook_owner_names."
},
"description": {
"type": "string",
"description": "What the step is for."
},
"goes_out_date": {
"type": "string",
"description": "Content steps: YYYY-MM-DD the finished content goes out."
},
"goes_out_time": {
"type": "string",
"description": "Content steps: optional time of day it goes out, \"HH:MM\". Needs goes_out_date."
},
"owner_user_id": {
"type": "integer",
"description": "Team member who owns the step. Defaults to you. Do not send together with owner_name."
},
"blueprint_uuid": {
"type": "string",
"format": "uuid",
"description": "Content steps: blueprint to write from (from list_blueprints)."
},
"after_plan_uuid": {
"type": "string",
"format": "uuid",
"description": "Place the step right after this step (plan_uuid from get_playbook_cycle). Omit to add it at the end."
},
"draft_lead_days": {
"type": "integer",
"maximum": 365,
"minimum": 0,
"description": "Content steps only: whole calendar days (0-365) before due_date when scheduled auto-generate starts (rejects non-integers and null; defaults to 3 when do_on_date is newly enabled, 0 on existing schedules). Note: later sending draft_lead_days (or schedule_time_zone, title, description, prompt, blueprint_id, project_id, reference_document_ids (even []), builds_on_plan_ids when any link/doc remains, context_collection_ids, targeting_dimension_ids, or generation_settings) via update_plan turns an enabled auto-generate schedule off; MCP cannot turn auto-generate on (stored lead only; when the owner turns it back on in the app, an unset lead resets to 3, so pick the intended lead there)."
},
"use_cycle_source": {
"type": "boolean",
"description": "Content steps only: true so this step's generation also sees a live snapshot of the cycle (topic/details, variables, anchor, and team-visible steps' title, owner, dates, status); private steps are omitted and the generated document footer states how many were left out, not other steps' text."
},
"context_collection_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "integer"
},
"description": "Content steps only (ignored on checklist/action steps): context collection IDs (list_context_collections) to attach to this step. Omit, [], or null starts empty (nothing inherits from the cycle); unavailable/unreadable IDs are refused."
},
"targeting_dimension_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "integer"
},
"description": "Content steps only (ignored on checklist/action steps): targeting dimension option IDs (list_targeting_dimensions) to attach to this step. Omit, [], or null starts empty (nothing inherits from the cycle); unavailable IDs are refused."
}
}
}Output Schema
{
"type": "object",
"properties": {
"step": {
"type": "object",
"properties": {
"kind": {
"type": "string"
},
"schedule": {
"type": "object",
"properties": {
"error": {
"type": [
"string",
"null"
]
},
"due_at": {
"type": [
"integer",
"null"
]
},
"enabled": {
"type": "boolean"
},
"outcome": {
"enum": [
"claimed",
"dispatching",
"started",
"failed",
"unknown",
"skipped",
"cancelled",
"overdue",
"waiting",
"waiting_content",
"invalidated",
null
],
"type": [
"string",
"null"
],
"description": "Schedule outcome: null (pending), waiting_content (a \"Do it on its date\" step is waiting because an earlier content step it builds on has no ready draft yet; retries on its own once that source is ready), waiting (waiting on an earlier checklist or action step; needs explicit produce_plan or generate_cycle_content), overdue (due date passed without running; needs explicit produce_plan or generate_cycle_content), invalidated (a teammate's edit or revoked consent switched automatic start off), cancelled (turned off or reassigned), skipped (step became ineligible for automatic start), claimed (picked up by a scheduler sweep), dispatching (starting execution), started (scheduled run started), failed (start failed with a client error), or unknown (ambiguous start error; check existing work before trying manually)."
},
"time_zone": {
"type": "string"
},
"generate_at": {
"type": [
"integer",
"null"
]
},
"attempted_at": {
"type": [
"integer",
"null"
]
},
"execution_uuid": {
"type": [
"string",
"null"
]
}
},
"description": "Date-schedule state readback when scheduled. outcome is null (pending), waiting_content (waiting on an earlier content step's draft; retries on its own once ready), waiting (waiting on an earlier checklist or action step), overdue (past due), invalidated (teammate edit or revoked consent switched automatic start off), cancelled (turned off or reassigned), skipped (ineligible), or claimed / dispatching / started / failed / unknown during or after a scheduled run. An overdue or waiting step does not auto-generate and needs an explicit generate via produce_plan or generate_cycle_content."
},
"do_on_date": {
"type": "boolean"
},
"draft_lead_days": {
"type": "integer",
"description": "Content steps: whole calendar days (0-365) before due_date when auto-generate starts (defaults to 3 when newly enabled; 0 for existing schedules). Changing draft_lead_days (or schedule_time_zone, title, description, prompt, blueprint_id, project_id, reference_document_ids (even [])/builds_on_plan_ids, context_collection_ids, targeting_dimension_ids, generation_settings) via update_plan turns an enabled auto-generate schedule off, and MCP cannot turn auto-generate on (stored lead only; when the owner turns it back on in-app, an unset lead resets to 3 so they must pick the intended lead there)."
},
"schedule_time_zone": {
"type": "string"
}
},
"description": "The step's kind, draft_lead_days (content steps: 0-365 whole calendar days), schedule readback (see schedule.outcome: waiting_content retries on its own once the source draft is ready; overdue or waiting needs an explicit generate; invalidated means a teammate's edit or revoked consent turned automatic start off), owner_name, times of day and other step settings."
},
"team": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"description": "Team this action applied to."
},
"stage": {
"type": "string"
},
"title": {
"type": "string"
},
"run_id": {
"type": "integer"
},
"due_date": {
"type": [
"string",
"null"
]
},
"link_url": {
"type": "string"
},
"plan_uuid": {
"type": "string",
"format": "uuid",
"description": "The new step's id."
},
"cycle_link_url": {
"type": "string",
"description": "Link to the running playbook."
},
"context_collections": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Context collection IDs attached to this step (content steps only)."
},
"generation_settings": {
"type": [
"object",
"null"
],
"description": "Generation source settings (e.g. { use_cycle_source: true }), or null. use_cycle_source: true gives generation a live snapshot of team-visible cycle steps only (private steps omitted with a footer count)."
},
"targeting_dimensions": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Targeting dimension option IDs attached to this step (content steps only)."
}
}
}Instructions
Add one step (content, checklist, or action) to a RUNNING playbook cycle (run_id), leaving the playbook template unchanged. The new step is a normal step of the running playbook: same visibility, project and category as its other steps, stage Accepted, counted in its progress and picked up by generate_cycle_content.
Position: right after after_plan_uuid, or at the end. builds_on may only name earlier steps.
- Content steps: accept
prompt({Variables}filled from the running playbook's values),blueprint_uuid,use_cycle_source(live snapshot of the cycle — topic, variables, anchor, and team-visible steps' title, owner, dates, status; private steps are omitted with a footer count),draft_lead_days(0–365 whole calendar days beforedue_date; later editing schedule-sensitive fields viaupdate_planturns auto-generate off),targeting_dimension_ids, andcontext_collection_ids. Step targeting/collections start empty unless explicitly passed (no cycle inheritance). - Due dates and times:
due_dateis theYYYY-MM-DDdeadline the step is due.due_timeandgoes_out_timerequire their corresponding date (due_date/goes_out_date).revieweris deprecated and ignored (not written or returned by MCP; existing values are kept). - Owner:
owner_user_iddefaults to you;owner_nameapplies tocontentandcheckliststeps only (use exact spelling fromlist_playbook_owner_names). - Action steps (
kind: "action"): requireaction: { instruction }(one or two plain sentences, up to 12,000 characters,{Variable}allowed) andowner_user_id; when its owner presses Run in the Marcora app, their in-app agent carries it out with their connected apps, asks for approval before external writes, and saves the result on the step. It does not run over MCP.
Refusals change nothing. Present link_url as returned.
When to use: when the user wants an extra step on a playbook they are already running ("add a QA check after step 3"). To change the template for future runs use update_playbook; to edit a step that exists use update_plan.
Links: present link_url to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.