Plans & Playbooks

update_plan

Partial update of a plan: mutable fields and stage transitions.

Parameters

Name	Type	Required	Default	Description
`plan_uuid`	`string`	Yes	—	Required. UUID of the plan to update.
`title`	`string`	No	—	Update plan title (1-200 chars).
`description`	`string`	No	—	Update plan description.
`prompt`	`string`	No	—	Update the content prompt.
`blueprint_id`	`string`	No	—	Update blueprint association — accepts a blueprint UUID (from list_blueprints) or integer id. Pass `null` to clear.
`project_id`	`string`	No	—	Update project association. Pass a new value to change it; `null` is ignored.
`category_id`	`integer`	No	—	Update category association. Pass a new value to change it; `null` is ignored.
`due_date`	`string`	No	—	Update due date (ISO YYYY-MM-DD). Pass `null` to clear.
`assigned_to`	`integer`	No	—	Reassign to a different team member (integer user ID). Must be a current team member. Assigning a private plan to anyone other than the calling user auto-promotes it to team visibility.
`visibility`	`string`	No	—	Change the plan's visibility. Creator-only — non-creators get InputError.
`reference_document_ids`	`array of string`	No	—	Non-empty array REPLACES the full set; `[]` is ignored.
`context_collection_ids`	`array of integer`	No	—	Non-empty array REPLACES the full set; `[]` is ignored.
`targeting_dimension_ids`	`array of integer`	No	—	Non-empty array REPLACES the full set; `[]` is ignored.
`target_stage`	`string`	No	—	Request a stage transition. Use UNDERSCORE form In_Process. Validated against the allowed-transition map; disallowed transitions return InputError. Allowed: Suggested, Accepted, In_Process, Complete, Dismissed.

Input Schema

{
  "type": "object",
  "required": [
    "plan_uuid"
  ],
  "properties": {
    "title": {
      "type": "string",
      "description": "Update plan title (1-200 chars)."
    },
    "prompt": {
      "type": "string",
      "description": "Update the content prompt."
    },
    "due_date": {
      "type": "string",
      "description": "Update due date (ISO YYYY-MM-DD). Pass `null` to clear."
    },
    "plan_uuid": {
      "type": "string",
      "description": "Required. UUID of the plan to update."
    },
    "project_id": {
      "type": "string",
      "description": "Update project association. Pass a new value to change it; `null` is ignored."
    },
    "visibility": {
      "enum": [
        "private",
        "team"
      ],
      "type": "string",
      "description": "Change the plan's visibility. Creator-only — non-creators get InputError."
    },
    "assigned_to": {
      "type": "integer",
      "description": "Reassign to a different team member (integer user ID). Must be a current team member. Assigning a private plan to anyone other than the calling user auto-promotes it to team visibility."
    },
    "category_id": {
      "type": "integer",
      "description": "Update category association. Pass a new value to change it; `null` is ignored."
    },
    "description": {
      "type": "string",
      "description": "Update plan description."
    },
    "blueprint_id": {
      "type": "string",
      "description": "Update blueprint association — accepts a blueprint UUID (from list_blueprints) or integer id. Pass `null` to clear."
    },
    "target_stage": {
      "type": "string",
      "description": "Request a stage transition. Use UNDERSCORE form In_Process. Validated against the allowed-transition map; disallowed transitions return InputError. Allowed: Suggested, Accepted, In_Process, Complete, Dismissed."
    },
    "context_collection_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Non-empty array REPLACES the full set of context collection associations; `[]` is ignored."
    },
    "reference_document_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Non-empty array REPLACES the full set of reference doc associations; `[]` is ignored."
    },
    "targeting_dimension_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Non-empty array REPLACES the full set of targeting dimension associations; `[]` is ignored."
    }
  }
}

Output Schema

{
  "type": "object",
  "required": [
    "plan_uuid",
    "stage",
    "updated_at",
    "link_url"
  ],
  "properties": {
    "id": {
      "type": "integer"
    },
    "stage": {
      "enum": [
        "Suggested",
        "Accepted",
        "In_Process",
        "Complete",
        "Dismissed"
      ],
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "prompt": {
      "type": [
        "string",
        "null"
      ]
    },
    "source": {
      "type": "string"
    },
    "team_id": {
      "type": "integer"
    },
    "due_date": {
      "type": [
        "string",
        "null"
      ]
    },
    "link_url": {
      "type": "string",
      "format": "uri",
      "description": "Shareable deep-link that opens the plans screen with this plan's detail overlay. Give this to the user."
    },
    "plan_uuid": {
      "type": "string"
    },
    "created_at": {
      "type": "integer"
    },
    "created_by": {
      "type": "integer"
    },
    "project_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "updated_at": {
      "type": "integer"
    },
    "visibility": {
      "enum": [
        "private",
        "team"
      ],
      "type": "string",
      "description": "private = creator-only; team = visible to all active teammates."
    },
    "assigned_to": {
      "type": "integer"
    },
    "category_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "blueprint_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "completed_at": {
      "type": [
        "integer",
        "null"
      ]
    },
    "dismissed_at": {
      "type": [
        "integer",
        "null"
      ]
    },
    "source_metadata": {
      "type": [
        "object",
        "null"
      ]
    },
    "context_collections": {
      "type": "array"
    },
    "produced_content_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "reference_documents": {
      "type": "array"
    },
    "targeting_dimensions": {
      "type": "array"
    }
  },
  "description": "Updated plan object with all fields."
}

Instructions

Performs a partial update on a plan. All fields are optional — supply only what you want to change.

Array fields replace entirely: a non-empty reference_document_ids, context_collection_ids or targeting_dimension_ids REPLACES the full set (not a merge). An empty array [] is ignored, so these lists can't be cleared with this tool.

Clearing fields: pass null to clear blueprint_id or due_date. null is ignored for project_id and category_id: pass a new value to change one.

Stage transitions (use target_stage):

Suggested -> Accepted or Dismissed
Accepted -> In_Process or Dismissed
In_Process -> Complete, Accepted, or Dismissed
Complete -> Accepted or Dismissed
Dismissed -> terminal, no further transitions

Use UNDERSCORE form for stage values: In_Process (not In Process).

Note: source and source_metadata are immutable and cannot be updated after creation.

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.