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
| 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. |
status | string | No | — | Filter by suggestion status. Default: suggested. |
call_context_item_id | string (uuid) | No | — | Optional context_item_id UUID of a call transcript to filter suggestions from that call. |
limit | integer | No | — | Maximum number of suggestions to return (1-50, default 20). |
cursor | string | No | — | 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.