MCP Tools
Plans & Playbooks

list_playbook_suggestions

List call-detected playbook suggestions visible to the caller in the specified team (suggested, started, or dismissed), including pre-filled variables, anchor date, and matched playbook.

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.
statusstringNo—Filter by suggestion status. Default: suggested.
call_context_item_idstring (uuid)No—Optional context_item_id UUID of a call transcript to filter suggestions from that call.
limitintegerNo—Maximum number of suggestions to return (1-50, default 20).
cursorstringNo—Opaque next_cursor from a previous call to fetch the next page.

Input Schema

{
  "type": "object",
  "required": [
    "team_id"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum number of suggestions to return (1-50, default 20)."
    },
    "cursor": {
      "type": "string",
      "maxLength": 512,
      "description": "Opaque next_cursor from a previous call to fetch the next page."
    },
    "status": {
      "enum": [
        "suggested",
        "started",
        "dismissed"
      ],
      "type": "string",
      "description": "Filter by suggestion status. Default: suggested."
    },
    "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."
    },
    "call_context_item_id": {
      "type": "string",
      "format": "uuid",
      "description": "Optional context_item_id UUID of a call transcript to filter suggestions from that call."
    }
  }
}

Output Schema

{
  "type": "object",
  "required": [
    "suggestions",
    "next_cursor"
  ],
  "properties": {
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Opaque cursor for the next page, or null when no more results exist."
    },
    "suggestions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "initiative",
          "playbook",
          "call",
          "visibility",
          "variables",
          "anchor_date",
          "supporting_quote",
          "status",
          "run",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Suggestion UUID. Pass as suggestion_id to instantiate_playbook or dismiss_playbook_suggestion."
          },
          "run": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "playbook_run_uuid",
              "link_url"
            ],
            "properties": {
              "link_url": {
                "type": "string"
              },
              "playbook_run_uuid": {
                "type": "string",
                "format": "uuid"
              }
            }
          },
          "call": {
            "type": "object",
            "required": [
              "context_item_id",
              "name"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "context_item_id": {
                "type": "string",
                "format": "uuid"
              }
            }
          },
          "status": {
            "enum": [
              "suggested",
              "started",
              "dismissed"
            ],
            "type": "string"
          },
          "coverage": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "item_id",
                "plan_uuid"
              ],
              "properties": {
                "item_id": {
                  "type": "integer",
                  "description": "Playbook step id already covered by an existing plan."
                },
                "plan_uuid": {
                  "type": "string",
                  "format": "uuid",
                  "description": "UUID of the existing plan covering that step."
                }
              },
              "additionalProperties": false
            },
            "description": "Which steps the call already planned; edits to those steps are refused."
          },
          "playbook": {
            "type": "object",
            "required": [
              "playbook_uuid",
              "name",
              "link_url"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "link_url": {
                "type": "string"
              },
              "playbook_uuid": {
                "type": "string",
                "format": "uuid"
              }
            }
          },
          "variables": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "created_at": {
            "type": "integer",
            "description": "Unix ms timestamp."
          },
          "initiative": {
            "type": "object",
            "required": [
              "id",
              "name",
              "occurrence"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "occurrence": {
                "type": "string"
              }
            }
          },
          "updated_at": {
            "type": "integer",
            "description": "Unix ms timestamp."
          },
          "visibility": {
            "enum": [
              "private",
              "team"
            ],
            "type": "string"
          },
          "anchor_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "supporting_quote": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Instructions

List call-detected playbook suggestions visible to the caller in the specified team (team_id) — suggested (default), started, or dismissed (or all). Each suggestion carries its initiative, occurrence, pre-filled variables, anchor_date, supporting call quote, coverage (existing matching plans), and matched playbook (playbook_uuid and link_url).

Suggestions from private calls appear only to their owner. To start a suggestion, match playbook.playbook_uuid via list_playbooks to get its numeric playbook_id, then pass playbook_id and suggestion_id to instantiate_playbook. To decline one, use dismiss_playbook_suggestion.

When to use

When the user asks what playbooks were suggested from calls, wants to review or start a call-detected initiative, or before instantiate_playbook / dismiss_playbook_suggestion to find a suggestion_id.

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.