MCP Tools
Plans & Playbooks

instantiate_playbook

Run a playbook: create one content plan per playbook item, in order, as a batch.

Input Schema

{
  "type": "object",
  "required": [
    "playbook_id"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "format": "uuid",
      "description": "Scope every created plan to this project (optional)."
    },
    "anchor_date": {
      "type": [
        "string",
        "null"
      ],
      "description": "The reference date every item's `offset_days` counts from: each plan's due_date = anchor_date + offset_days. Three distinct cases, so choose deliberately — OMIT the field to inherit the playbook's own saved anchor_date (due dates are only unset if the playbook has no saved anchor either); pass an explicit null (or empty string) to force NO anchor, which leaves every due date unset even when the playbook has a saved one; or pass a YYYY-MM-DD date to override with that date. Any other format is rejected. When the user names a date (\"anchored to next Monday\") send it explicitly; when they just say \"run my playbook\" omit the field so their saved anchor is honored."
    },
    "assigned_to": {
      "type": "integer",
      "description": "User id to assign the created plans to. Defaults to the caller."
    },
    "category_id": {
      "type": "integer",
      "description": "Override the content category for every created plan (optional)."
    },
    "playbook_id": {
      "type": "integer",
      "description": "Numeric id of the saved playbook to run — the `id` from list_playbooks or the trailing number in its link_url, not a UUID. If you only have the playbook's name, call list_playbooks first to resolve the id. The playbook must contain at least one item; running an empty playbook fails."
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "run": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string",
          "description": "Auto-named \"<playbook> — <Mon YYYY>\" unless you passed a name."
        },
        "link_url": {
          "type": "string",
          "description": "https://app.marcora.ai/runs/{run_id}"
        },
        "anchor_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "Persisted YYYY-MM-DD reference date, or null."
        }
      },
      "description": "The created cycle."
    },
    "plans": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "link_url": {
            "type": "string",
            "description": "https://app.marcora.ai/plans/{plan_uuid}"
          }
        }
      },
      "description": "The created content plans (same shape as create_plan / get_plan), stage Accepted, source playbook."
    },
    "run_id": {
      "type": "integer",
      "description": "ID of the cycle (run) this created — the group the plans belong to."
    },
    "playbook_id": {
      "type": "integer",
      "description": "The instantiated playbook."
    },
    "created_count": {
      "type": "integer",
      "description": "Number of plans created (one per playbook item)."
    }
  },
  "description": "An object describing the run."
}

Instructions

Run a playbook: create one content plan per playbook item, in order, as a batch. Plans land in the Accepted stage with source playbook and INHERIT the playbook's visibility (team playbook → team plans; private playbook → private plans). Optionally anchor due dates to a date (each item's offset_days is applied to anchor_date) and/or scope the batch to a project. This is a distinct bulk action — it does not create or edit the playbook itself.

Parameters:

Parameter Type Required Description
playbook_id integer Yes Numeric id of the saved playbook to run — the id from list_playbooks or the trailing number in its link_url, not a UUID. The playbook must contain at least one item; running an empty playbook fails
anchor_date string | null No The reference date every item's offset_days counts from: due_date = anchor_date + offset_days. Three distinct cases — see below
project_id string (uuid) No Scope every created plan to this project
assigned_to integer No User id to assign the created plans to. Defaults to the caller
category_id integer No Override the content category for every created plan

anchor_date has THREE distinct cases — choose deliberately:

What you send What happens
Omit the field Inherits the playbook's own saved anchor_date. Due dates are only left unset if the playbook has no saved anchor either
Explicit null (or empty string) Forces NO anchor — every due date is left unset, even when the playbook has a saved one
YYYY-MM-DD Overrides with that date

Any other format is rejected. When the user names a date ("anchored to next Monday") send it explicitly; when they just say "run my playbook", omit the field so their saved anchor is honored.

Output: an object describing the run:

Field Type Description
playbook_id integer The instantiated playbook
run_id integer ID of the cycle (run) this created — the group the plans belong to
run object The created cycle: id, name (auto-named "<playbook> — <Mon YYYY>" unless you passed a name), anchor_date, and link_url (https://app.marcora.ai/runs/{run_id}) — share it to hand the user their new cycle
created_count integer Number of plans created (one per playbook item)
plans array The created content plans (same shape as create_plan / get_plan), each with its own link_url (https://app.marcora.ai/plans/{plan_uuid}). Stage Accepted, source playbook

Example prompts:

  • "Run my launch playbook"
  • "Instantiate this template anchored to next Monday"
Scroll to Top