MCP Tools
Plans & Playbooks

get_playbook_cycle

Read one playbook cycle with its project and steps in playbook order: instructions, stage, due date, owner, schedule state, what each builds on, and the document it produced.

Parameters

NameTypeRequiredDefaultDescription
team_idintegerYes—Team id to act in (from initialize instructions or get_current_user_info). Required on external MCP; optional in bound sessions.
run_idintegerYes—Cycle id — the integer run_id from list_playbook_cycles / instantiate_playbook, not a UUID.

Input Schema

{
  "type": "object",
  "required": [
    "team_id",
    "run_id"
  ],
  "properties": {
    "run_id": {
      "type": "integer",
      "description": "Cycle id — the integer run_id from list_playbook_cycles / instantiate_playbook, not a UUID."
    },
    "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."
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "cycle": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "topic": {
          "type": [
            "string",
            "null"
          ],
          "description": "What the cycle is about (set when it was started), or null."
        },
        "run_id": {
          "type": "integer",
          "description": "Cycle id. Pass to get_playbook_cycle, or to list_plans as run_id."
        },
        "status": {
          "enum": [
            "active",
            "complete"
          ],
          "type": "string",
          "description": "complete = every step is Complete or Dismissed."
        },
        "link_url": {
          "type": "string",
          "description": "URL to open this cycle in the Marcora web app."
        },
        "progress": {
          "type": "object",
          "properties": {
            "done": {
              "type": "integer"
            },
            "total": {
              "type": "integer"
            },
            "by_stage": {
              "type": "object"
            },
            "dismissed": {
              "type": "integer"
            }
          },
          "description": "Step counts: total, done (Complete), dismissed, and by_stage."
        },
        "created_at": {
          "type": "integer",
          "description": "Unix ms timestamp."
        },
        "created_by": {
          "type": "integer"
        },
        "project_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Project scoped to this cycle, or null."
        },
        "anchor_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "YYYY-MM-DD date the step due dates count from."
        },
        "playbook_id": {
          "type": "integer"
        },
        "project_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Name of that project when readable, or null."
        },
        "playbook_name": {
          "type": "string",
          "description": "Source playbook template name, or \"Deleted template\" when the template has been deleted."
        }
      }
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "done": {
            "type": "boolean",
            "description": "true when the step is Complete or Dismissed."
          },
          "step": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "description": "content (a document is generated) | checklist (tick it off) | action (Marcora performs an action)."
              },
              "due_time": {
                "type": "string",
                "description": "HH:MM time of day the step is due, only when set."
              },
              "optional": {
                "type": "boolean"
              },
              "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": "Auto-generation schedule state readback. 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 schedule does not auto-generate and needs an explicit generate via produce_plan or generate_cycle_content."
              },
              "do_on_date": {
                "type": "boolean"
              },
              "owner_name": {
                "type": "string",
                "description": "Typed owner name, only when set."
              },
              "goes_out_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "YYYY-MM-DD date this piece goes out, if set."
              },
              "goes_out_time": {
                "type": "string",
                "description": "HH:MM time of day the content goes out, only when set."
              },
              "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). Note: 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)."
              },
              "schedule_time_zone": {
                "type": "string"
              }
            },
            "description": "What kind of step this is."
          },
          "stage": {
            "type": "string",
            "description": "Suggested | Accepted | In_Process | Complete | Dismissed."
          },
          "title": {
            "type": "string"
          },
          "prompt": {
            "type": [
              "string",
              "null"
            ],
            "description": "The step's instructions."
          },
          "result": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "note": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "result_url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Result link recorded on completion."
              },
              "completed_by": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "description": "Completion record, or null while the step is open."
          },
          "document": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "stage": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "link_url": {
                "type": "string"
              },
              "content_id": {
                "type": "string"
              }
            },
            "description": "The document produced for this step, if any."
          },
          "due_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "link_url": {
            "type": "string",
            "description": "URL to open this step in the Marcora web app."
          },
          "position": {
            "type": "integer",
            "description": "1-based order within the cycle."
          },
          "builds_on": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "position": {
                  "type": "integer"
                },
                "plan_uuid": {
                  "type": "string"
                }
              }
            },
            "description": "Earlier steps this one builds on."
          },
          "plan_uuid": {
            "type": "string",
            "format": "uuid"
          },
          "assigned_to": {
            "type": "integer"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "assigned_to_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "use_cycle_source": {
            "type": "boolean",
            "description": "Present (true) when this content step's generation also sees a live snapshot of the cycle's team-visible steps (private steps are omitted with a footer count)."
          }
        }
      }
    }
  }
}

Instructions

Read one playbook cycle (run_id) with its steps in order (including any steps added mid-cycle via add_playbook_step). Each step has its plan_uuid, title, description, prompt (the instructions), stage, due_date, owner (assigned_to and step.owner_name), use_cycle_source, step.schedule, the earlier steps it builds on (builds_on), the produced document (with link) when there is one, and — once completed — the recorded result (link / note).

Each step's plan_uuid is how you act on it:

  • Change a step's title, prompt, due date, assignee, typed owner, time of day, targeting/collections, attach an existing document, or dismiss it → update_plan (turns do_on_date off on content/targeting/lead edits)
  • Complete or reopen a step → update_playbook_step_status
  • Rename the cycle or change its topic → update_playbook_cycle

When to use: when the user asks about a specific cycle, what a step involves, what is due next in it, or what an earlier step produced. Get run_id from list_playbook_cycles or a cycle link_url.

Output: cycle (same shape as a list_playbook_cycles row, including project_id / project_name and playbook_name = "Deleted template" if the template was deleted) and steps. Each step carries position, plan_uuid, title, description, prompt, stage, done, due_date, assigned_to / assigned_to_name, use_cycle_source, builds_on, document (or null), step (kind, optional, do_on_date, draft_lead_days, schedule_time_zone, schedule, goes_out_date, plus owner_name, due_time, and goes_out_time when set), result (or null), and link_url. step.schedule.outcome is null (pending), waiting_content, waiting, overdue, invalidated, cancelled, skipped, claimed, dispatching, started, failed, or unknown.

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.