How to connect Carbon Voice MCP with Python

List messages with filtering by date, conversation, folder, workspace, creator or language. USE WHEN: The general-purpose message reader; full bodies incl. transcript and AI summary. Max date span 183 days. `user_ids` filters by SENDER — for messages exchanged WITH someone, pass `conversation_id` from `list_conversations`. Use presigned URLs as-is. USE INSTEAD: `get_recent_messages` for a quick look at the latest few (hard-capped at 10, no paging). `search_message_ids` for filters this cannot express — notified state, mentions or labels. FIRST: `workspace_id` comes from `get_workspaces_basic_info` (field `id`) — call it first if you don't have one. EXAMPLE: {"workspace_id":"ws-abc","start_date":"2026-09-01T00:00:00Z","size":25} RETURNS: `{page, size, sort_direction, total, results_count, has_next_page, filters, results: [{id, transcript?, ai_summary?, audio_url?, creator_id, conversation_id?, duration_ms, reply_count, status, type, created_at, ...}]}`. Page on `has_next_page`/`total` — do not guess. NARROW: pass response_fields ["total","has_next_page","results.id","results.transcript","results.created_at"] unless you need more — the full payload is much larger.

Get one message by ID, optionally expanded with related records. USE WHEN: You have a message ID. `fields` ADDS related data (`conversation`, `creator`, `labels`) — it does not narrow the response. Use `response_fields` to narrow. USE INSTEAD: `list_messages` when you do not have an ID, or need several messages — it already returns full bodies, so fetching each one again is wasted. FIRST: `id` comes from `list_messages` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"msg-abc","fields":"creator"} RETURNS: `{message: {id, transcript?, ai_summary?, audio_url?, creator_id, duration_ms, status, type, attachments?, created_at, ...}}`.

Get up to 10 of the most recent messages, each with its conversation, creator and labels. USE WHEN: A quick "what just happened" glance. Pre-joined, so no follow-up calls for creator or conversation names. USE INSTEAD: `list_messages` whenever you need more than 10, any date range, paging, or a filter other than conversation and language — this tool supports none of those. EXAMPLE: {"conversation_id":"conv-abc"} RETURNS: `{results: [{message: {...}, conversation: {...}, creator: {...}, labels: [...]}]}`. No total and no paging: the cap of 10 is the whole answer.

Post a message into an existing conversation, or reply in a thread. USE WHEN: You have a `conversation_id`. Pass `parent_id` (a message ID) to reply as a thread. Either `transcript` or `links` is required — the schema marks neither individually, so both param descriptions say so. USE INSTEAD: `create_direct_message` to reach people who are not already in a conversation. `create_voicememo_message` for a standalone memo. FIRST: `id` comes from `list_conversations` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"conv-abc","transcript":"Agreed, shipping Friday."} RETURNS: `{message: {id, link, transcript?, status, type, conversation_id, created_at, ...}}`. ERROR BAD_REQUEST: Neither `transcript` nor `links` was provided. — Pass at least one of them.

Send a direct message to one or more people, by user ID or email. USE WHEN: Reaching people outside an existing conversation. Address it with `to.user_ids` or `to.emails`. Requires `transcript` or `links`. USE INSTEAD: `create_conversation_message` when a conversation already exists — a DM starts a separate thread rather than joining it. FIRST: `to.user_ids` comes from `search_users` (field `id`) — call it first if you don't have one. EXAMPLE: {"to":{"user_ids":["user-abc"]},"transcript":"Quick question about the deck."} RETURNS: `{message: {id, link, transcript?, status, conversation_id, created_at, ...}}`. ERROR BAD_REQUEST: A user ID is invalid, or neither `transcript` nor `links` was provided. — Resolve people with `search_users` — never pass a display name as a user ID — and include a transcript or links.

Create a voice memo, either from text (spoken via text-to-speech) or from an audio file at a URL. USE WHEN: Pass `transcript` (2-5000 chars) to have Carbon Voice speak the text, or an https `audio_url` to upload audio, which wins over `transcript`. File it with `folder_id`, whose type must match, or a `workspace_id`. USE INSTEAD: `create_conversation_message` to post into an existing conversation, or `create_direct_message` to send to specific people. A voice memo is standalone and lives in a folder or workspace. EXAMPLE: {"transcript":"Reminder to review the pricing deck before Friday."} RETURNS: `{message: {id, link, transcript?, audio_url?, duration_ms, status, type, created_at, ...}}`. `status` is often `processing` at first. ERROR INVALID_AUDIO_URL: `audio_url` is not https, unreachable, too large, timed out, embeds credentials, or resolves to a private address. — The message gives the reason. Use a public https URL, or pass `transcript` instead. ERROR BAD_REQUEST: None of `transcript`, `audio_url` or `links` was provided, or the transcript is outside 2-5000 characters. — Provide one of the three, and keep the transcript within the length limits.

Attach one or more link URLs to an existing message. USE WHEN: Adding external links to a message that already exists. USE INSTEAD: `create_message_share_link` to share a Carbon Voice message outward — that produces a link, this consumes them. FIRST: `id` comes from `list_messages` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"msg-abc","links":["https://example.com/spec"]} RETURNS: `{...}` confirmation with the resulting attachments.

Get a user's full profile by ID — names, languages, voice settings, workspace roles. USE WHEN: You already have a user ID and need complete details. USE INSTEAD: `search_user` / `search_users` to FIND someone by email, phone or name. `get_current_user` for the caller — this tool needs an explicit ID and will not default to you. FIRST: `id` comes from `search_users` (field `id`) — call it first if you don't have one. EXAMPLE: {"id":"user-abc"} RETURNS: `{id, first_name, last_name?, languages, voice_gender, workspace_ids, workspace_roles, user_type, created_at, ...}`. NARROW: pass response_fields ["id","first_name","last_name","workspace_ids"] unless you need more — the full payload is much larger.

Find a single user by email, phone or name. USE WHEN: Resolving ONE person. Supply exactly one of `email`, `phone` or `name`. Name search only matches your own contacts. USE INSTEAD: `search_users` for several people in one call — it takes arrays and saves a round trip per person. `get_user` when you already have the ID. EXAMPLE: {"email":"someone@example.com"} RETURNS: `{id, full_name, first_name, last_name?, link, image_url?, languages?, ...}`. Use `id` wherever another tool asks for a user ID. ERROR NOT_FOUND: Nobody matched, or a name search hit a non-contact. — Try an email or phone instead of a name; name search is limited to your contacts.

Resolve several users at once by emails, phones, IDs or names. USE WHEN: Turning a list of people into user IDs in one call — the right first step before any tool that takes user IDs. Name search only matches your contacts. USE INSTEAD: `search_user` for a single lookup. `get_user` for a full profile once you have the ID. EXAMPLE: {"names":["Brett"]} RETURNS: Array of `{id, full_name, first_name, last_name?, link, languages?, ...}`. If a name returns more than one candidate, ask which person was meant rather than guessing. NARROW: pass response_fields ["id","full_name"] unless you need more — the full payload is much larger.

Get the calling user's own identity, workspaces and settings. USE WHEN: Establishing who you are acting as, or finding the caller’s workspace IDs before a workspace-scoped call. Takes no arguments. USE INSTEAD: `get_user` for somebody else (it requires an explicit ID). `get_workspaces_basic_info` if you only need workspace IDs and names — it is far smaller than this response. EXAMPLE: {} RETURNS: `{success, user: {user_guid, first_name, last_name?, email_txt?, phone_txt?, workspace_guids, identities, entries, environments, lifecycle_events, notification_settings, settings, ...}, settings: {...}}`. This payload is LARGE — several unbounded arrays and an open settings map. NARROW: pass response_fields ["user.user_guid","user.first_name","user.email_txt","user.workspace_guids"] unless you need more — the full payload is much larger.

List your conversations from the last 6 months, optionally filtered by participants, type and name. USE WHEN: Finding a `conversation_id`. Filter with `user_ids` plus `match`, `types` and `name` — YOUR DM with someone is `user_ids: ["<their id>"], types: ["directMessage"]`. You are always an implicit participant, so never pass your own ID. Filters AND together; if several match, ask which was meant. USE INSTEAD: `get_conversation` when you already have an ID and want full detail — this returns only id, name, workspace_id and type. EXAMPLE: {"user_ids":["user-abc"],"types":["directMessage"]} RETURNS: `{results_count, results: [{id, name, workspace_id, type}]}` where type is `directMessage` | `customerConversation` | `namedConversation` | `asyncMeeting`. No paging: `results_count` is what is returned, after filtering. `name` adds `unfiltered_count`: rows the name was matched against, AFTER `user_ids`/`types`. ALWAYS check it before saying no such conversation exists. 0 of 47 means none matched that string (misspelt, or >6 months old); 0 of 0 means your other filters left nothing — not that the caller has none. Widen the filters or ask; never report it does not exist.

Get one conversation by ID, with full metadata. USE WHEN: You have a `conversation_id` and need its description, visibility, owner or workspace name. USE INSTEAD: `get_conversation_users` for the participant list. `list_messages` with `conversation_id` for its messages — this returns neither. FIRST: `id` comes from `list_conversations` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"conv-abc"} RETURNS: `{id, name, description?, link, workspace_id, workspace_name, owner_id, type, visibility, ...}`.

List the people in a conversation. USE WHEN: Finding out who is in a conversation, or collecting participant user IDs. USE INSTEAD: `search_users` to resolve people by name or email generally — this is scoped to one conversation. FIRST: `id` comes from `list_conversations` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"conv-abc"} RETURNS: Array of user objects with `id` and profile fields. NARROW: pass response_fields ["id","full_name"] unless you need more — the full payload is much larger.

Summarize a conversation by running an AI Action over its recent messages. USE WHEN: You want a conversation summarized and have a `conversation_id`. Message selection is handled for you — omit `message_ids` and the most recent messages are used. USE INSTEAD: `run_ai_action` if you already know exactly which `message_ids` to process, or want a non-summary AI Action. FIRST: `prompt_id` comes from `list_ai_actions` (field `id`) — call it first if you don't have one. FIRST: `conversation_id` comes from `list_conversations` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"conversation_id":"conv-abc","prompt_id":"prompt-abc","limit":50} RETURNS: Same as `run_ai_action`: `{id, prompt_id, message_ids, responses: [{language, text?, markdown?, ...}], ...}`. ERROR BAD_REQUEST: `prompt_id` is not a valid AI Action ID. — Call `list_ai_actions` to get valid `prompt_id` values.

List the root folders of a workspace for a given folder type. USE WHEN: Orienting in the folder tree, or finding a `folder_id`. `type` is required: `voicememo` or `prerecorded`. `include_all_tree` returns nested folders too. USE INSTEAD: `get_folder` to inspect one folder. `get_folder_with_messages` when you want a folder’s messages rather than its structure. EXAMPLE: {"type":"voicememo","workspace_id":"ws-abc"} RETURNS: `{type, workspace_id?, include_all_tree?, sort_by, sort_direction, results: [{id, name, parent_folder_id?, subfolder_ids?, total_nested_folders_count, total_nested_messages_count, ...}]}`. Not paginated — this is the complete set. NARROW: pass response_fields ["results.id","results.name","results.total_nested_messages_count"] unless you need more — the full payload is much larger.

Create a folder in a workspace, optionally nested under another. USE WHEN: Organising memos. `name`, `type` and `workspace_id` are all required; add `parent_folder_id` to nest. USE INSTEAD: `move_folder` to relocate a folder that already exists. FIRST: `workspace_id` comes from `get_workspaces_basic_info` (field `id`) — call it first if you don't have one. EXAMPLE: {"name":"Q4 planning","type":"voicememo","workspace_id":"ws-abc"} RETURNS: The created folder, same shape as `get_folder`.

Get one folder's metadata and, optionally, its immediate subfolders. USE WHEN: Inspecting a folder. Set `include_first_level_tree: true` to get subfolders. Both `date` AND `direction` are silently ignored unless you do — upstream only documented that caveat on `date`. USE INSTEAD: `get_folder_with_messages` when you want the messages inside the folder — this returns structure and counts only. FIRST: `id` comes from `get_root_folders` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"folder-abc","include_first_level_tree":true} RETURNS: `{id, name, type, workspace_id, parent_folder_id?, path?, subfolder_ids?, message_ids?, total_nested_folders_count, total_nested_messages_count, subfolders?, ...}`.

Get a folder together with the messages stored directly in it. USE WHEN: Reading a folder’s contents. Only messages at that folder’s own level are returned — nested folders are not walked. USE INSTEAD: `get_folder` for structure and counts without message bodies. `list_messages` with `folder_id` when you need date filtering or paging, which this tool does not support. FIRST: `id` comes from `get_root_folders` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"folder-abc"} RETURNS: `{folder: {...}, messages: [{...}]}`. NARROW: pass response_fields ["folder.id","folder.name","messages"] unless you need more — the full payload is much larger.

Rename a folder. USE WHEN: Changing only the name. `name` is the sole editable field here. USE INSTEAD: `move_folder` to change where a folder sits in the tree. FIRST: `id` comes from `get_root_folders` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"folder-abc","name":"Q4 planning (final)"} RETURNS: The updated folder, same shape as `get_folder`.

Permanently delete a folder, including every nested folder and all their messages. USE WHEN: Only when the whole subtree should be destroyed. This cascades and cannot be undone. USE INSTEAD: `move_folder` to get a folder out of the way, or `move_message_to_folder` to relocate its messages first. Check `total_nested_messages_count` via `get_folder` before calling — the cascade is easy to underestimate. FIRST: `id` comes from `get_root_folders` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"folder-abc"} RETURNS: Deletion confirmation.

Move a folder into another folder, or up to a workspace root. USE WHEN: Relocating a folder. Pass `folder_id` for a new parent folder, or `workspace_id` to move it to the workspace root — one or the other, not both. USE INSTEAD: `update_folder_name` to rename in place. `move_message_to_folder` for a single message rather than a folder. FIRST: `id` comes from `get_root_folders` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"folder-abc","folder_id":"folder-parent"} RETURNS: The moved folder, same shape as `get_folder`. ERROR BAD_REQUEST: Both `folder_id` and `workspace_id` were given, or neither, or the move would nest a folder inside itself. — Pass exactly one destination.

Move a message into a folder, or out to a workspace. USE WHEN: Filing a memo. Only `voicememo`/`prerecorded` messages you created can be moved, and the message type must match the folder's type. Pass exactly one of `folder_id` or `workspace_id`. USE INSTEAD: `move_folder` to relocate a whole folder. `create_voicememo_message` with `folder_id` to file a memo at creation time instead of moving it after. FIRST: `message_id` comes from `list_messages` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"message_id":"msg-abc","folder_id":"folder-abc"} RETURNS: The updated message with its new placement. ERROR BAD_REQUEST: The message type is not `voicememo`/`prerecorded`, it does not match the destination folder's type, or both/neither destination was given. — Check `type` via `get_message` and the folder type via `get_folder`; they must match. Pass exactly one destination.

List every workspace you belong to, as id and name only. USE WHEN: The cheapest way to resolve a workspace name to an ID before a workspace-scoped call. Takes no arguments. USE INSTEAD: `get_current_user` if you need more than ids and names — but note that response is much larger, so prefer this one when ids suffice. EXAMPLE: {} RETURNS: Array of `{id, name}`. Nothing else, and no paging.

List the AI Actions (Prompts) available to you — each has an `id` usable as `prompt_id`. USE WHEN: Before calling `run_ai_action` or `summarize_conversation`, to find a `prompt_id`. Also to show the user which AI Actions exist. Filter by `owner_type` (`user` = your own, `workspace` = shared, `system` = Carbon Voice built-ins). USE INSTEAD: `get_ai_action_responses` if you want results that were already generated rather than the list of available actions. EXAMPLE: {"owner_type":"system"} RETURNS: Array of `{id, name, description?, prompt, owner_type, workspace_id?, response_format?, created_at, last_updated_at}`. Use `id` as `prompt_id` elsewhere. NARROW: pass response_fields ["id","name","description","owner_type"] unless you need more — the full payload is much larger.

Run an AI Action (Prompt) against one or more specific messages. USE WHEN: You have concrete `message_ids` and a `prompt_id`, and want the AI Action applied to exactly those messages. USE INSTEAD: `summarize_conversation` if you want a whole conversation summarized and would otherwise have to list its messages yourself — it does that selection for you. FIRST: `prompt_id` comes from `list_ai_actions` (field `id`) — call it first if you don't have one. FIRST: `message_ids` comes from `list_messages` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"prompt_id":"prompt-abc","message_ids":["msg-1","msg-2"],"language":"english"} RETURNS: `{id, prompt_id, message_ids, creator_id, channel_id?, workspace_id?, responses: [{language, text?, markdown?, html?, json?}], created_at}`. The generated output is in `responses[]`, one entry per language. ERROR BAD_REQUEST: `prompt_id` or one of `message_ids` is not a valid ID. — Call `list_ai_actions` for valid `prompt_id` values and `list_messages` for valid message IDs; do not retry with the same IDs.

Run an AI Action (Prompt) against one or more shared messages, addressed by share link ID. USE WHEN: You have share link IDs — from `create_message_share_link`, or a link someone gave you — and want an AI Action applied to the messages behind them. USE INSTEAD: `run_ai_action` if you have the message IDs directly; going through a share link adds nothing when you already have access. FIRST: `share_link_ids` comes from `create_message_share_link` (field `id`) — call it first if you don't have one. FIRST: `prompt_id` comes from `list_ai_actions` (field `id`) — call it first if you don't have one. EXAMPLE: {"prompt_id":"prompt-abc","share_link_ids":["share-abc"]} RETURNS: `{share_link_ids, responses: [{language, text?, markdown?, html?, json?}], ...}`. ERROR NOT_FOUND: A share link ID does not exist, or its access has been revoked or expired. — Create a fresh link with `create_message_share_link`, or verify the ID with `get_message_share_link`.

Retrieve AI Action results that were generated previously. USE WHEN: You want existing output rather than a fresh run — e.g. showing what an AI Action already produced for a message or conversation. Combine `prompt_id`, `message_id` and `channel_id` to narrow. USE INSTEAD: `run_ai_action` (or `summarize_conversation`) to generate new output; this tool only reads what already exists and returns an empty array if nothing has been generated. EXAMPLE: {"channel_id":"conv-abc","limit":10} RETURNS: Array of `{id, prompt_id, creator_id, message_ids, channel_id?, workspace_id?, responses: [{language, text?, markdown?, html?, json?}], created_at}`. NARROW: pass response_fields ["id","prompt_id","responses"] unless you need more — the full payload is much larger.

Create a shareable link to an existing message (e.g. a voice memo), and get the URL back. USE WHEN: `share_type: "link"` for a shareable URL; `"forward"` to attach the share onto another message (also needs `message_id`). Also how you get a `share_link_ids` value. USE INSTEAD: `add_attachments_to_message` to attach an external URL to a message, rather than share a Carbon Voice message outward. FIRST: `shared_message_id` comes from `list_messages` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"shared_message_id":"msg-abc","share_type":"link","access_type":"public"} RETURNS: `{id, link, share_type, access_type, created_by, specified_access?, end_access_at?, revoked_at?, shared_message: {...}}`. `link` is the URL to hand out; `id` is the `share_link_ids` value other tools take. NARROW: pass response_fields ["id","link","share_type","access_type"] unless you need more — the full payload is much larger. ERROR BAD_REQUEST: `shared_message_id` is invalid, or `share_type` is "forward" without `message_id`. — Confirm the ID with `get_message`; when forwarding, also pass `message_id`.

Look up an existing message share link by its ID, including the message behind it. USE WHEN: You have a share link ID and want its URL, access settings, or whether it is still valid — check `revoked_at` and `end_access_at` before relying on it. USE INSTEAD: `create_message_share_link` to make a new link; this only reads existing ones. `get_message` if you have the message ID and do not care about the share. FIRST: `share_link_id` comes from `create_message_share_link` (field `id`) — call it first if you don't have one. EXAMPLE: {"share_link_id":"share-abc"} RETURNS: Same shape as `create_message_share_link`: `{id, link, share_type, access_type, revoked_at?, end_access_at?, shared_message: {...}, ...}`. NARROW: pass response_fields ["id","link","revoked_at","end_access_at"] unless you need more — the full payload is much larger. ERROR NOT_FOUND: No share link with that ID, or it is no longer accessible. — Create a new one with `create_message_share_link`; do not retry the same ID.

List your action items across every conversation and folder: those assigned to you, PLUS unassigned ones you created. USE WHEN: Answering "what do I owe / what is on my plate" — but check `assigned_to` before calling something the user's own commitment: a null one is an item they raised that nobody has picked up. Filter by `status` (`todo` open, `suggested` AI-proposed, `done` complete). Page with `starting_after`. USE INSTEAD: `list_action_items` when you want one specific conversation or folder rather than everything of yours. EXAMPLE: {"status":"todo","limit":25} RETURNS: `{results: [{id, title, status, notes_text?, assigned_to?, due_date?, container_id?, container_type?, source_message_id?, creator_id, ...}], total?, results_count?, has_more?, next_cursor?, filters?}`. Keep paging while `has_more` is true, passing `next_cursor` as `starting_after`. NARROW: pass response_fields ["results.id","results.title","results.status","results.assigned_to","results.due_date"] unless you need more — the full payload is much larger.

List action items belonging to one container — a conversation, a folder, or home. USE WHEN: You have a `container_id` and want its action items. `container_type` is `channel` for a conversation, `folder` for a folder, or `home`. A conversation id is NOT a folder id — resolve `container_id` with the tool matching your `container_type`. Filter by `status` or `assigned_to` (pass the string `null` for unassigned). USE INSTEAD: `list_my_action_items` for everything assigned to you regardless of where it lives. FIRST: `container_id` comes from `list_conversations` (field `results[].id`) when `container_type` is `channel` — call it first if you don't have one. FIRST: `container_id` comes from `get_root_folders` (field `results[].id`) when `container_type` is `folder` — call it first if you don't have one. EXAMPLE: {"container_type":"channel","container_id":"conv-abc","status":"todo"} RETURNS: Same as `list_my_action_items`: `{results: [...], total?, results_count?, has_more?, next_cursor?, filters?}`. NARROW: pass response_fields ["results.id","results.title","results.status","results.assigned_to"] unless you need more — the full payload is much larger.

Get one action item by its ID, with full detail. USE WHEN: You have an action item ID and need its notes, assignee, due date, or source message. USE INSTEAD: `list_my_action_items` or `list_action_items` if you do not have an ID yet — they already return the same fields per item, so a follow-up call is usually wasted. FIRST: `id` comes from `list_my_action_items` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"ai-abc"} RETURNS: `{id, title, status, notes_text?, creator_id, assigned_to?, due_date?, container_id?, container_type?, source_message_id?, last_updated_by, ...}`.

Create an action item, optionally attached to a conversation or folder. USE WHEN: Recording a task. Only `title` is required. Attach it by passing both `container_type` and `container_id`, and link it to what prompted it with `source_message_id`. USE INSTEAD: `suggest_action_items_from_messages` to have tasks extracted from message content automatically instead of writing each one yourself. EXAMPLE: {"title":"Send the pricing deck","assigned_to":"user-abc"} RETURNS: `{id, title, status, notes_text?, assigned_to?, due_date?, container_id?, container_type?, creator_id, ...}`. New items start at status `todo`. ERROR BAD_REQUEST: `assigned_to` is not a valid user ID, or `container_id` does not match `container_type`. — Resolve people with `search_users` (never pass a name) and containers with `list_conversations` or `get_root_folders`.

Change an action item's title, notes, assignee, or due date. USE WHEN: Editing item content. Send only the fields you want changed — omitted fields are left as they are. USE INSTEAD: `set_action_item_status` to move an item between `todo` / `done` / `suggested`; status is not editable here. FIRST: `id` comes from `list_my_action_items` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"ai-abc","due_date":"2026-10-01"} RETURNS: The updated action item, same shape as `get_action_item`.

Move an action item between `suggested`, `todo` and `done`. USE WHEN: Completing an item (`done`), reopening it (`todo`), or accepting an AI-suggested item by promoting it from `suggested` to `todo`. USE INSTEAD: `update_action_item` for title, notes, assignee or due date; this tool only sets status. FIRST: `id` comes from `list_my_action_items` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"ai-abc","status":"done"} RETURNS: The updated action item, same shape as `get_action_item`.

Permanently delete an action item. USE WHEN: The item was created in error and should not exist at all. USE INSTEAD: `set_action_item_status` with `done` to complete an item — that keeps the record. Deleting cannot be undone, so prefer it only when the item is genuinely spurious. FIRST: `id` comes from `list_my_action_items` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"id":"ai-abc"} RETURNS: Deletion confirmation for the removed item.

Extract action items from ONE message and return them immediately. USE WHEN: Turning a single message into tasks — "what did she ask me to do?". The items come back in this call, already saved with `status: "suggested"`; promote the ones you want with `set_action_item_status`. Prefer this over `suggest_action_items_from_messages` whenever there is exactly one message, since it needs no polling. USE INSTEAD: `suggest_action_items_from_messages` for two or more messages — it reasons over the whole set at once and can catch commitments that span messages, which calling this tool repeatedly cannot. `create_action_item` when you already know the task. FIRST: `message_id` comes from `list_messages` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"message_id":"msg-1"} RETURNS: Array of the created action items, each with `id`, `title`, `assigned_to`, `due_date`, `notes_text` and `status: "suggested"`. An empty array means the model found nothing actionable. Runs the extraction inline, so expect this call to take a few seconds.

Queue AI extraction of candidate action items from specific messages. Runs in the background. USE WHEN: Turning a conversation into tasks — "what did we agree to?". Pass the `message_ids` to analyse, then POLL `list_my_action_items` or `list_action_items` with `status: "suggested"` for the results, and promote the ones you want with `set_action_item_status`. USE INSTEAD: `suggest_action_items_from_message` (singular) for a SINGLE message — it returns the items directly, with no polling. `create_action_item` when you already know the task and do not need it inferred — that returns the item synchronously, with an id. FIRST: `message_ids` comes from `list_messages` (field `results[].id`) — call it first if you don't have one. EXAMPLE: {"message_ids":["msg-1","msg-2"]} RETURNS: ACKNOWLEDGEMENT ONLY — no items are returned. Extraction is queued and runs in the background, so poll a listing tool with `status: "suggested"` to see the results.

Find message IDs by notified state, mentions, labels, creator, conversation or workspace — returning IDs plus cursor metadata. USE WHEN: Any filter `list_messages` cannot express: whether you were notified (`notified_status`), whether you were tagged (`tagged_user_ids`), or by `label_ids`. Cheap in tokens because it returns IDs only — hydrate the ones you need with `get_message`. USE INSTEAD: `list_messages` when a date range, conversation or workspace filter is all you need and you want full message bodies in one call. `search_messages_by_heard_status` for unread/listened state, which this tool cannot filter on. EXAMPLE: {"notified_status":"notified","limit":50} RETURNS: `{ids: [{...}], has_more, next_cursor?}`. Keep paging while `has_more` is true, passing `next_cursor` back as `next_cursor`. ERROR BAD_REQUEST: An ID list contains names rather than IDs, or exceeds 50 entries. — Resolve people to IDs with `search_users` and conversations with `list_conversations`; split lists longer than 50.

Find messages by whether you have listened to them, and get per-conversation unheard counts. USE WHEN: "What have I not listened to yet" / "catch me up". `heardStatus: "unheard"` is the unread filter. The response also carries `unheard_counts_by_channel`, so you can prioritise conversations without fetching their messages. USE INSTEAD: `search_message_ids` for notified state, mentions or date anchors — this tool accepts no date filter (see note below). `list_messages` for plain recent history. EXAMPLE: {"heardStatus":"unheard","limit":25} RETURNS: `{messages: [{message_guid, creator_guid, creator_first_name, channel_guids, transcript_txt, message_ts, heard_status, ...}], unheard_counts_by_channel: {conversation_id: count}, success}`. Use `unheard_counts_by_channel` to decide where to look first. NARROW: pass response_fields ["unheard_counts_by_channel","messages.message_guid","messages.channel_guids","messages.creator_first_name","messages.transcript_txt","messages.message_ts"] unless you need more — the full payload is much larger.

List your inbox notifications, with a total unread count. USE WHEN: Answering "what did I miss" or "where was I mentioned" — pass `category: "mentions"` for mentions. The response includes `total_unread`, so you can report a count without paging. USE INSTEAD: `search_message_ids` with `notified_status` if you want the messages themselves rather than notification records. `search_messages_by_heard_status` for unlistened messages. EXAMPLE: {"category":"mentions","limit":25} RETURNS: `{results: [...], total_results, total_unread, filters}`. Pages with `skip`/`limit`, not cursors. NARROW: pass response_fields ["results","total_unread","total_results"] unless you need more — the full payload is much larger.