How to connect Read AI MCP with TypeScript

Retrieve a single Read AI meeting (owned by or shared with the authenticated user) by its ULID identifier, with optional expansion of rich meeting content. When to call this tool ---------------------- Call this tool only when: - You already have a specific meeting ID (a ULID), and - The user wants information about that *one* meeting, such as: - Metadata (title, times, participants, platform, report URL) - Summary / chapter summaries - Action items / key questions - Topics discussed - Full transcript - Metrics/analytics - A link to download the recording Do NOT call this tool: - To search or browse meetings by title, date, participant, or keywords (use a dedicated list/search tool instead). - When working with multiple meetings at once. - With guessed or fabricated IDs. Only use IDs explicitly provided by the user or returned from another tool. Parameters ---------- id : str The Read AI meeting identifier in ULID format. - 26-character, case-insensitive, base32 ULID string (e.g. "01KA3883FYZSFZXE391Q0FMV39"). - Must come from: - A previous tool (e.g., a meeting list/search tool), or - Explicit user input. - Do not invent, modify, or "fix" IDs. expand : Optional[List[ExpandableEnum]] Optional list specifying which additional sections of the meeting record should be fully populated. Only sections listed here are fetched; all others remain `None`. Request the smallest set that satisfies the user’s need. Each additional expand value can increase latency and resource usage, especially "transcript". Allowed values (strings): - "summary": concise natural-language overview of the meeting. - "chapter_summaries": breakdown into labeled sections/chapters. - "action_items": follow-up tasks and next steps. - "key_questions": important or open questions discussed. - "topics": main themes/subjects covered. - "transcript": detailed spoken content of the meeting, including who spoke and what they said, suitable for verbatim quotes and fine‑grained analysis. - "metrics": high-level analytics (e.g., read_score, sentiment, engagement). - "recording_download": url to download the meeting recording. Output ------ MeetingEvent A single meeting object with: - Base metadata (id, title, start/end times, scheduled times, platform, platform_id, report_url, folders). - `access_level`: the authenticated caller's access level on this meeting, one of "owner", "editor", "viewer_full", or "viewer_recap_only" (or null if it could not be resolved). "editor" or "owner" is required to share the report via the `share_meeting_report` tool. - Owner and participants (with name/email and attendance status). - Expandable fields populated only if requested in `expand`: - `summary`: Optional[str] - `chapter_summaries`: Optional[List[Chapter]] - `action_items`: Optional[List[str]] - `key_questions`: Optional[List[str]] - `topics`: Optional[List[str]] - `transcript`: Optional[Transcript] - `metrics`: Optional[Metrics] - `recording_download`: Optional[RecordingDownload] Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply it as a parameter. - If missing or invalid, the tool fails with errors such as: - "Unauthorized: No access token provided" - "Invalid token: No subject in access token claims". - Not found / access issues: - If the ID is invalid or the meeting is not accessible to the user, the tool fails with "Not Found". - If the user's Read AI account does not have sufficient quota to view the meeting, the tool fails with an "Out of quota" error. This is a billing issue and the user can resolve it by upgrading their plan. They can resolve this by visiting "https://app.read.ai/analytics/meetings/{meeting_id}" in their browser, where {meeting_id} is the provided meeting ID. - Idempotency: - Read-only and idempotent. Calling with the same arguments returns the same logical result. Usage examples for agents ------------------------- 1) User: "Give me the summary and action items from meeting 01H9T5X9G5K3M7Y8R0D8AYZ5WQ." -> Call: { "id": "01H9T5X9G5K3M7Y8R0D8AYZ5WQ", "expand": ["summary", "action_items"] } 2) User: "Who said 'We should move this to next quarter' in meeting <meeting_ulid>?" -> You need detailed speech text: { "id": "<meeting_ulid>", "expand": ["transcript"] }

List Read AI meetings for the authenticated user with optional start-time filters and cursor-based pagination. When to call this tool ---------------------- Call this tool when: - You need to browse or filter a user's meetings by time range. - You need meeting IDs (ULIDs) that can later be used with a "get_meeting_by_id" tool for detailed inspection. - You want a page of recent meetings (optionally with summaries or metrics). Do NOT call this tool: - When you already know the specific meeting ID and only need that single meeting (use the "get_meeting_by_id" tool instead). - To find meetings by what was said in them (use "meeting_search_agent"). - To guess or fabricate meeting IDs. Parameters ---------- limit : int, default 10 (max 10) Maximum number of meetings to return in this page. - Must be ≤ 10. - If omitted, defaults to 10. start_datetime_gt : Optional[datetime] Only include meetings whose start time is strictly greater than this value (exclusive lower bound). ISO 8601 string, e.g. "2025-11-01T00:00:00Z". start_datetime_gte : Optional[datetime] Only include meetings whose start time is greater than or equal to this value (inclusive lower bound). ISO 8601 string. - Typically use either `start_datetime_gt` or `start_datetime_gte`, not both. start_datetime_lt : Optional[datetime] Only include meetings whose start time is strictly less than this value (exclusive upper bound). ISO 8601 string. start_datetime_lte : Optional[datetime] Only include meetings whose start time is less than or equal to this value (inclusive upper bound). ISO 8601 string. - Typically use either `start_datetime_lt` or `start_datetime_lte`, not both. - For a closed interval [A, B], use: - `start_datetime_gte = A` - `start_datetime_lte = B` cursor : Optional[str] Cursor for pagination. - First page: omit or pass `null`. - Next page: pass the ID of the last meeting returned in the previous page (`previous_response.data[-1].id`), which acts as a "start after this" pointer. expand : Optional[List[ExpandableEnum]] Optional list specifying which extra sections of *each* meeting should be fully populated. Only sections listed here are fetched; all others remain `None`. Because this is a list endpoint, expansions apply to every meeting in the page and can be expensive. Request only what the user needs. Allowed values (strings), with the same meanings as in `get_meeting_by_id`: - "summary": concise natural-language overview of the meeting. - "chapter_summaries": breakdown into labeled sections/chapters. - "action_items": follow-up tasks and next steps. - "key_questions": important or open questions discussed. - "topics": main themes/subjects covered. - "transcript": detailed spoken content of the meeting, including who spoke and what they said, suitable for verbatim quotes and fine‑grained analysis. - "metrics": high-level analytics (e.g., read_score, sentiment, engagement). - "recording_download": url to download the meeting recording. Returns ------- ListMeetingResponse A paginated list of meetings with: - `object`: str – always "list". - `url`: str – API-style URL for this collection. - `has_more`: bool – True if there are more meetings beyond this page. - `data`: List[MeetingEvent] – meetings matching the filters, each with: - Core metadata (id, title, start/end times, platform, etc.). - `access_level`: the caller's access level on the meeting ("owner", "editor", "viewer_full", "viewer_recap_only", or null). "editor"/"owner" is required to share the report via `share_meeting_report`. - Owner and participants. - Any expandable fields populated according to `expand`. Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not pass it as a parameter. - If missing or invalid, the tool raises errors such as: - "Unauthorized: No access token provided" - "Invalid token: No subject in access token claims". - Filtering: - All provided filters are combined with logical AND. - Conflicting ranges (e.g., lower bound after upper bound) will typically return an empty result. - Prefer at most one lower-bound parameter (`gt` or `gte`) and one upper- bound parameter (`lt` or `lte`). - Pagination: - `limit` controls the number of meetings per page (max 10). - Use `has_more` plus `cursor` (last meeting's id from `data`) to fetch subsequent pages. - Ordering: - Meetings are ordered by id, which for almost all meetings matches start_time order. An uploaded meeting whose start_time was corrected after upload can appear out of strict start_time order relative to its neighbors. - Idempotency: - Read-only and idempotent. Repeating the same call yields the same logical results, except for new meetings created in the underlying system. Usage examples for agents ------------------------- 1) Get the 10 most recent meetings (no filters, first page): -> Call: { "limit": 10 } 2) Get meetings in November 2025, including brief summaries: -> Call: { "limit": 10, "start_datetime_gte": "2025-11-01T00:00:00", "start_datetime_lte": "2025-11-30T23:59:59", "expand": ["summary"] } 3) Page through all recent meetings since 2025-11-01: First page: -> Call: { "limit": 10, "start_datetime_gte": "2025-11-01T00:00:00" } Next page (if has_more is true): -> Call: { "limit": 10, "start_datetime_gte": "2025-11-01T00:00:00", "cursor": "<id_of_last_meeting_from_previous_page>" } 4) Find candidate meetings to inspect in detail later: - First, list meetings with summaries and metrics: { "limit": 5, "expand": ["summary", "metrics"] } - Then, pick a specific meeting ID and call `readai_get_meeting_by_id` with `expand=["transcript"]` if you need the full conversation.

Send a Read AI meeting agent (bot) to a video conferencing meeting on behalf of the authenticated user. This creates a new Read AI meeting ID and the agent will attempt to join the meeting to record & transcribe it for the user. When to call this tool ---------------------- Call this tool when: - The user explicitly asks for an agent to "join", "record", "capture," "send a bot to", or "take notes on" a specific meeting they identify on their calendar, by providing a meeting link, or specifying a video conferencing platform with a meeting ID and optional password. - The meeting is on a supported platform (Zoom, Google Meet, Microsoft Teams) Do NOT call this tool: - For meetings the user has not explicitly authorized an agent to join. - To join arbitrary or guessed meeting IDs. - If a user wants to record using a desktop or mobile client. Those are available from Read AI's website (https://read.ai) and can be used separately. Parameters ---------- meeting_url : str Meeting URL that can be used to join the meeting. If provided, the meeting_platform and meeting_id will be extracted from the URL and those additional parameters are not required. meeting_platform : str The video conferencing platform for the meeting. Must be one of: - "zoom" (Zoom) - "meet" (Google Meet) - "teams" (Microsoft Teams) If a meeting_url is provided, this parameter is not required. meeting_id : str The platform-specific meeting identifier (e.g. a Zoom meeting number, a Google Meet meeting code like "abc-defg-hij", a Teams meeting ID, etc.). Provide the raw ID as it would appear in the meeting URL. If a meeting_url is provided, this parameter is not required. meeting_password : Optional[str] Optional passcode/password for the meeting, if one is required. Omit if the meeting does not require a password or if a meeting_url is provided. start_time : Optional[datetime] Optional start time to stamp on the created meeting, in ISO 8601 format (e.g. "2026-05-21T15:00:00" or "2026-05-21T15:00:00Z"). If omitted, the meeting is stamped with the current time at creation and an agent is dispatched immediately to join the meeting. If a time in the future is specified, the agent will join the meeting at the specified time. title : Optional[str] Optional human-readable title to stamp on the created meeting (e.g. "Q3 Planning Sync"). If omitted, the meeting is given a generic platform-derived default such as "Zoom Meeting" or "Meet Meeting". Only set this when the user has provided or clearly implied a title; do not invent one. Returns ------- str The ULID for the newly created (or matched existing) Read AI meeting that the the meeting recording agent has been dispatched for. This meeting ID can be passed to other tools such as `get_meeting_by_id` once the meeting has progressed far enough to have data available. Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply user IDs or tokens. - If missing or invalid, the tool fails with errors such as: - "Unauthorized: No access token provided" - "Invalid token: No subject in access token claims". - Validation: - `meeting_id` is required and must be non-empty if a meeting_url is not provided. - If the platform / meeting combination is unsupported or the agent cannot be deployed (e.g. mobile/desktop platforms, or missing required platform integrations), the tool will fail with an error. - Idempotency: - This tool is idempotent. If an entry for the same meeting already exists in an active state, the system may return the existing meeting ID instead of creating a new one. - Side effects: - An agent may join the live meeting and a new meeting ID is created in Read AI. Usage examples for agents ------------------------- 1) User: "Have Read AI record my Zoom meeting 1234567890." -> Call: { "meeting_platform": "zoom", "meeting_id": "1234567890" } 2) User: "Send the Read AI bot to my Google Meet abc-defg-hij." -> Call: { "meeting_platform": "meet", "meeting_id": "abc-defg-hij" } 3) User: "Join my Zoom 9876543210 with passcode hunter2." -> Call: { "meeting_platform": "zoom", "meeting_id": "9876543210", "meeting_password": "hunter2" } 4) User: "Join my meeting now: https://meet.google.com/abc-defg-hij" -> Call: { "meeting_url": "https://meet.google.com/abc-defg-hij" } 5) User: "Join my meeting at 2026-05-21T15:00:00Z: https://meet.google.com/abc-defg-hij" -> Call: { "meeting_url": "https://meet.google.com/abc-defg-hij", "start_time": "2026-05-21T15:00:00Z" } 6) User: "Join my Zoom 1234567890 and call it 'Q3 Planning Sync'." -> Call: { "meeting_platform": "zoom", "meeting_id": "1234567890", "title": "Q3 Planning Sync" }

Share a Read AI meeting report with an email address on behalf of the authenticated user. Grants the recipient access to the meeting at a specified access level and (optionally) emails them an invite. When to call this tool ---------------------- Call this tool when: - The user explicitly asks to "share", "send", "give access to", or "invite someone to" a specific meeting report, identified by its ULID. - You have already confirmed (via `get_meeting_by_id` or `list_meetings`) that the user has "editor" or "owner" access to that meeting — only editors and owners are allowed to share. Do NOT call this tool: - To share meetings the user does not have edit access to. If `access_level` from `get_meeting_by_id`/`list_meetings` is "viewer_full" or "viewer_recap_only", the user cannot share and the call will fail. - With guessed or fabricated meeting IDs or email addresses. Only use values explicitly provided by the user or returned from another tool. - To transfer ownership. Ownership cannot be granted through this tool. Parameters ---------- id : str The Read AI meeting identifier in ULID format (26-character, case-insensitive base32). Must come from a previous tool or explicit user input. email : str The email address to share the report with. Must be a valid email address. If the email belongs to an existing Read AI user, access is granted to that user directly; otherwise an email-based access invite is created. access_level : str The access level to grant. One of: - "viewer_recap_only": can view only the recap/summary of the meeting. - "viewer_full": full read access to the meeting report. - "editor": read access plus the ability to edit (and re-share) the report. Defaults to "viewer_full". "owner" is not allowed. message : Optional[str] Optional personal message to include in the invite email. Only relevant when `notify` is true. notify : bool, default true Whether to send the recipient an invite email. Set to false to grant access silently without notifying them. Returns ------- ShareMeetingResponse An object describing the grant: - `id`: the meeting ULID that was shared. - `shared_with_email`: the email the report was shared with. - `access_level`: the access level that was granted. - `notified`: whether an invite email was sent. - `report_url`: a link to the meeting report. Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply user IDs or tokens. - Permissions: - The caller must have "editor" or "owner" access to the meeting. If not, the tool fails with a "Forbidden" error. Confirm the caller's `access_level` using `get_meeting_by_id` before calling this tool. - Validation: - An invalid email address will cause the tool to fail. - Granting "owner" (or any non-shareable level) will fail. - Idempotency: - Re-sharing with the same email and access level is safe; the existing grant is updated rather than duplicated, and the invite email is not re-sent. The `notified` field in the response reflects whether an email was actually sent on this call. - Side effects: - The recipient gains access to the meeting, and (unless `notify` is false, or an equivalent grant already existed) an invite email is sent to them. Usage examples for agents ------------------------- 1) User: "Share meeting 01H9T5X9G5K3M7Y8R0D8AYZ5WQ with alex@example.com." -> First confirm the caller can share (get_meeting_by_id -> access_level is "editor" or "owner"), then call: { "id": "01H9T5X9G5K3M7Y8R0D8AYZ5WQ", "email": "alex@example.com" } 2) User: "Give jordan@example.com edit access to that meeting and add a note." -> Call: { "id": "<meeting_ulid>", "email": "jordan@example.com", "access_level": "editor", "message": "Please review and update the action items." } 3) User: "Quietly share the recap of <meeting_ulid> with sam@example.com without emailing them." -> Call: { "id": "<meeting_ulid>", "email": "sam@example.com", "access_level": "viewer_recap_only", "notify": false }

List all folders belonging to the authenticated user: their private (custom) folders, folders shared with them, and their system-generated auto folders. When to call this tool ---------------------- Call this tool when: - You need to find a folder by name, or show the user what folders they have. - You need a folder's ID to pass to "get_folder", "list_folder_items", or a folder-item-management tool. Do NOT call this tool: - When you already know the specific folder ID and only need that one folder's details (use "get_folder" instead). - To list the meetings *inside* a folder (use "list_folder_items" instead). Parameters ---------- sort_direction : str, default "desc" Either "asc" or "desc". Applies to whichever `sort_column` is chosen. sort_column : str, default "custom" One of "custom" (the user's own manual/default ordering), "name", "created_on", "updated_on", or "last_item_action_on". kind : Optional[str] Filter to a single Folder Type (matches the "Folder Types" filter on the Folders page in the web app): "custom" (private), "shared", or "auto". Omit to return all types. Returns ------- List[FolderEvent] Every folder the user has, unpaginated (there is no cursor/limit - this returns the user's complete folder list in one call). Each entry has: - `id`, `name`, `color`, `icon`, `description`. - `kind`: "custom" (private), "shared", or "auto" (system-generated, e.g. platform-based folders the user did not create). - `total_items`: number of meetings currently in the folder. - `created_on` / `updated_on` / `last_item_action_on`. - `access_level`: the caller's access level on the folder ("owner", "editor", "viewer", or "none"). Always "owner" for custom folders; null for auto folders (no per-user ACL applies to them). - `item_access_level`: for shared folders only, the access level members get to sessions placed in the folder ("viewer" or "editor"). Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply it as a parameter. - Idempotency: - Read-only and idempotent. Usage examples for agents ------------------------- 1) User: "What folders do I have?" -> Call: {} 2) User: "Put this meeting in my 'Sales Calls' folder." -> First call list_folders to find the folder named "Sales Calls" and get its id, then use a folder-item tool with that id. 3) User: "What folders are shared with me?" -> {"kind": "shared"}

Retrieve a single folder (owned by, or shared with, the authenticated user) by its ULID identifier. When to call this tool ---------------------- Call this tool only when: - You already have a specific folder ID (a ULID), and - You need that folder's details (name, kind, item count, your access level). Do NOT call this tool: - To search or browse folders by name (use "list_folders" instead). - To list the meetings *inside* the folder (use "list_folder_items" instead). - With guessed or fabricated IDs. Only use IDs explicitly provided by the user or returned from another tool (e.g. "list_folders"). Parameters ---------- id : str The folder identifier in ULID format (26-character, case-insensitive base32 string). Must come from a previous tool or explicit user input. Returns ------- FolderEvent Same shape as each entry returned by "list_folders" - see that tool's description for field details. Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply it as a parameter. - Not found / access issues: - If the ID is invalid, or the folder is private and not owned by the caller, the tool fails with "Not Found". - If the folder is shared but the caller has no access to it, the tool fails with a permissions error. - Idempotency: - Read-only and idempotent. Usage examples for agents ------------------------- 1) User: "What's in my folder 01H9T5X9G5K3M7Y8R0D8AYZ5WQ?" -> Call: {"id": "01H9T5X9G5K3M7Y8R0D8AYZ5WQ"} Then, to see the actual meetings, call "list_folder_items" with the same id.

List the meetings contained in a single folder, with optional expansion of each meeting's rich content, using cursor-based pagination. When to call this tool ---------------------- Call this tool when: - You already have a folder ID (from "list_folders" or "get_folder") and need to see the meetings it contains. Do NOT call this tool: - To browse a user's meetings in general, independent of any folder (use "list_meetings" instead). - With a guessed or fabricated folder ID. Parameters ---------- folder_id : str The folder's ULID identifier. Must come from a previous tool or explicit user input. limit : int, default 10 (max 10) Maximum number of meetings to return in this page. cursor : Optional[str] Cursor for pagination. - First page: omit or pass `null`. - Next page: pass the ID of the last meeting returned in the previous page (`previous_response.data[-1].id`). expand : Optional[List[ExpandableEnum]] Optional list specifying which extra sections of *each* meeting should be fully populated. Only request what the user needs - this is a list endpoint, so expansions apply to every meeting in the page and can be expensive. Allowed values (strings), with the same meanings as in "list_meetings": - "summary": concise natural-language overview of the meeting. - "chapter_summaries": breakdown into labeled sections/chapters. - "action_items": follow-up tasks and next steps. - "key_questions": important or open questions discussed. - "topics": main themes/subjects covered. - "transcript": detailed spoken content of the meeting, including who spoke and what they said, suitable for verbatim quotes and fine‑grained analysis. - "metrics": high-level analytics (e.g., read_score, sentiment, engagement). - "recording_download": url to download the meeting recording. Returns ------- ListMeetingResponse The same shape "list_meetings" returns: - `object`: str - always "list". - `url`: str - API-style URL for this collection. - `has_more`: bool - True if there are more items beyond this page. - `data`: List[MeetingEvent] - meetings in the folder, each with the same fields documented in "get_meeting_by_id" / "list_meetings" (metadata, participants, access_level, and any requested expandable fields). Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply it as a parameter. - Access: - The caller must be able to view the folder (same rules as "get_folder"). If not, the tool fails the same way "get_folder" would for that folder. - Pagination: - `limit` controls the number of items per page (max 10). - Use `has_more` plus `cursor` (last item's id from `data`) to fetch subsequent pages. - Idempotency: - Read-only and idempotent, except for meetings added to or removed from the folder between calls. Usage examples for agents ------------------------- 1) User: "What meetings are in my 'Sales Calls' folder?" -> First call list_folders to find the folder id, then: {"folder_id": "<folder_ulid>", "limit": 10} 2) User: "Summarize everything in that folder." -> {"folder_id": "<folder_ulid>", "limit": 10, "expand": ["summary"]}

Create a new folder owned by the authenticated user - either private (custom) or shared. When to call this tool ---------------------- Call this tool when: - The user wants a new folder to organize meetings into, and no existing folder (from "list_folders") already fits. Do NOT call this tool: - If a suitable folder already exists (check "list_folders" first). - To invite other people to a shared folder you just created - use "share_folder" for that afterward. This tool only creates the folder itself, with the caller as its sole owner. Parameters ---------- name : str The folder's display name (max 100 characters). color : str The folder's color. One of: "gray", "pink", "redOrange", "green", "yellowGreen", "teal", "blue", "indigo" (matches the web app's color picker - not a hex code). icon : Optional[str] Optional icon for the folder. One of: "folder", "lightning", "lightbulb", "star", "paint", "code", "briefcase", "building", "trophy", "beaker", "bookmark", "flag", "heart", "rocket", "speechBubble", "trendUp" (matches the web app's icon picker). description : Optional[str] Optional folder description (max 1000 characters). kind : str, default "custom" "custom" (private, visible only to the caller) or "shared" (a shared folder others can later be invited to via "share_folder"). "auto" cannot be created through this tool. item_access_level : Optional[str] Shared folders only ("kind"="shared"): the access level folder members get to sessions placed in it, "viewer" or "editor" (defaults to "viewer" if omitted). Must not be set when "kind"="custom". Returns ------- FolderEvent The newly created folder - same shape as "list_folders"/"get_folder" entries, with `total_items` 0 and the caller as `access_level` "owner". Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply it as a parameter. - Idempotency: - Not idempotent - each call creates a new folder, even with identical arguments. Check "list_folders" first if you want to avoid duplicates. Usage examples for agents ------------------------- 1) User: "Make me a folder called 'Sales Calls'." -> {"name": "Sales Calls", "color": "blue"} 2) User: "Create a 'Q1 Planning' folder with a star icon for onboarding notes." -> {"name": "Q1 Planning", "color": "indigo", "icon": "star", "description": "Onboarding notes"} 3) User: "Create a shared folder called 'Team Retros' that members can add meetings to." -> {"name": "Team Retros", "color": "teal", "kind": "shared", "item_access_level": "editor"} Then use "share_folder" to invite people to it.

Add one or more meetings to an existing folder. When to call this tool ---------------------- Call this tool when: - You already have a folder ID (from "list_folders", "get_folder", or "create_folder") and one or more meeting IDs to place in it. Do NOT call this tool: - With a guessed or fabricated folder ID or meeting ID. Only use IDs explicitly provided by the user or returned from another tool. - To remove meetings from a folder (use "remove_folder_items" instead). Parameters ---------- folder_id : str The folder's ULID identifier. items : List[object] One or more meetings to add, each with: - `meeting_id` (str): the meeting's ULID. - `apply_to_series` (bool, default false): if true, also adds every other meeting in this meeting's recurring series (not just this meeting). Set per meeting, not once for the whole call - mixing recurring and non-recurring meetings in one call is fine as long as only the actually-recurring ones have `apply_to_series` set. Fails if a meeting with `apply_to_series` true is not part of a recurring series. Returns ------- FolderEvent The folder's current state after the addition, including its updated `total_items` count - same shape as "get_folder". Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply it as a parameter. - Access: - The caller must have edit access to the folder (owner for private folders, owner/editor for shared folders). If not, the tool fails with a permissions error. - The caller must also have at least viewer access to each meeting being added (editor access if the folder is shared). - Not found / access issues: - Meeting IDs that don't exist (or are deleted/opted-out) are silently skipped rather than failing the whole call. - A meeting ID the caller lacks sufficient access to fails the entire call with a permissions error - it is not skipped like a not-found ID. - Idempotency: - Idempotent in practice - adding a meeting already in the folder again has no additional effect. Usage examples for agents ------------------------- 1) User: "Add this meeting to my 'Sales Calls' folder." -> {"folder_id": "<folder_ulid>", "items": [{"meeting_id": "<meeting_ulid>"}]} 2) User: "Add these three meetings to that folder, and include the rest of the first one's recurring series too." -> { "folder_id": "<folder_ulid>", "items": [ {"meeting_id": "<id_1>", "apply_to_series": true}, {"meeting_id": "<id_2>"}, {"meeting_id": "<id_3>"} ] }

Remove one or more meetings from a folder. The meetings themselves are not deleted - only untagged from this folder. When to call this tool ---------------------- Call this tool when: - You already have a folder ID and one or more meeting IDs currently in it that the user wants removed from the folder. Do NOT call this tool: - With a guessed or fabricated folder ID or meeting ID. Only use IDs explicitly provided by the user or returned from another tool. - To delete a meeting entirely (this tool has no such effect - it only removes the folder association). Parameters ---------- folder_id : str The folder's ULID identifier. items : List[object] One or more meetings to remove, each with: - `meeting_id` (str): the meeting's ULID. - `apply_to_series` (bool, default false): if true, also removes every other meeting in this meeting's recurring series (not just this meeting). Set per meeting, not once for the whole call - mixing recurring and non-recurring meetings in one call is fine as long as only the actually-recurring ones have `apply_to_series` set. Fails if a meeting with `apply_to_series` true is not part of a recurring series. Returns ------- FolderEvent The folder's current state after the removal, including its updated `total_items` count - same shape as "get_folder". Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply it as a parameter. - Access: - The caller must have edit access to the folder (owner for private folders, owner/editor for shared folders - or, for shared folders, ownership of every session being removed). If not, the tool fails with a permissions error. - Not found / skip cases: - Meeting IDs not currently in the folder are silently skipped rather than failing the whole call. - Idempotency: - Idempotent - removing a meeting already absent from the folder has no effect. - Eventual consistency: - This tool's own returned `total_items` can occasionally still reflect the pre-removal count for a moment after the call - the underlying removal has already happened by the time the tool returns. If a caller needs to confirm the new count, a follow-up "get_folder" or "list_folder_items" call is authoritative. Usage examples for agents ------------------------- 1) User: "Remove this meeting from my 'Sales Calls' folder." -> {"folder_id": "<folder_ulid>", "items": [{"meeting_id": "<meeting_ulid>"}]} 2) User: "Remove these three meetings from that folder, and the rest of the first one's recurring series too." -> { "folder_id": "<folder_ulid>", "items": [ {"meeting_id": "<id_1>", "apply_to_series": true}, {"meeting_id": "<id_2>"}, {"meeting_id": "<id_3>"} ] }

Update a folder's name, color, icon, and/or description. When to call this tool ---------------------- Call this tool when: - The user wants to rename, recolor, or otherwise edit an existing folder's attributes. Do NOT call this tool: - To change what kind of folder it is (private vs. shared) - not supported by this tool. - On an auto (system-generated) folder - not editable at all, this tool fails clearly rather than silently doing nothing. - To share a folder with other people, or change who has access to it (use "share_folder" instead). - To add or remove meetings from a folder (use "add_folder_items" or "remove_folder_items" instead). Parameters ---------- id : str The folder's ULID identifier. name : Optional[str] New folder name (max 100 characters). Omit to leave unchanged. color : Optional[str] New folder color. One of: "gray", "pink", "redOrange", "green", "yellowGreen", "teal", "blue", "indigo". Omit to leave unchanged. icon : Optional[str] New icon for the folder. One of: "folder", "lightning", "lightbulb", "star", "paint", "code", "briefcase", "building", "trophy", "beaker", "bookmark", "flag", "heart", "rocket", "speechBubble", "trendUp". Omit to leave unchanged. description : Optional[str] New folder description (max 1000 characters). Omit to leave unchanged. item_access_level : Optional[str] Shared folders only: access level folder members get to sessions placed in it, "viewer" or "editor". Omit to leave unchanged. Must not be set on a private (custom) folder. Returns ------- FolderEvent The folder's state after the update - same shape as "get_folder". Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply it as a parameter. - Access: - The caller must have edit access to the folder (owner for private folders, owner/editor for shared folders). If not, the tool fails with a permissions error. - Auto folders cannot be edited through this tool at all, regardless of access level - the tool fails with a clear error rather than silently applying no changes. - item_access_level: - Setting this on a folder that isn't kind="shared" fails with a clear error rather than being silently ignored. - Idempotency: - Idempotent - repeating an identical call produces the same result. - Omitted fields are left unchanged, not cleared. There is no way to clear `icon`/`description` back to empty with this tool. Usage examples for agents ------------------------- 1) User: "Rename my 'Sales Calls' folder to 'Q3 Sales Calls'." -> First find the folder id via "list_folders", then: {"id": "<folder_ulid>", "name": "Q3 Sales Calls"} 2) User: "Change that folder's color to blue and add a description." -> {"id": "<folder_ulid>", "color": "blue", "description": "..."}

Permanently delete a folder. When to call this tool ---------------------- Call this tool only when: - The user explicitly wants a folder itself removed (not just emptied). Do NOT call this tool: - To remove meetings from a folder while keeping the folder itself (use "remove_folder_items" instead). - With a guessed or fabricated folder ID. Only use IDs explicitly provided by the user or returned from another tool. - Without clear, explicit user intent - this action cannot be undone. Parameters ---------- id : str The folder's ULID identifier. Returns ------- FolderDeleteResponse `id`: the deleted folder's ID. `deleted`: always true on success. Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply it as a parameter. - Access: - The caller must be the folder's owner. If not, the tool fails with a permissions error. - Irreversibility: - This only deletes the folder itself (its categorization) - the meetings that were in it are not deleted and remain fully accessible. There is no undo for the folder itself: a deleted folder's name, color, and item list cannot be recovered, though the user can create a new folder and manually re-add the same meetings if they know which ones they were. - Deleting a **shared** folder removes it for every member, not just the caller - confirm this is intended before calling with a shared folder's ID. - Not found / already deleted: - Deleting an already-deleted or nonexistent folder ID fails with a permissions error rather than a clean success, since ownership is checked before the folder's existence - there is no owner relationship left to find once a folder is gone. Treat that error as "already gone" for a folder you just deleted, rather than retrying. Usage examples for agents ------------------------- 1) User: "Delete my 'Old Sales Calls' folder." -> First find the folder id via "list_folders", confirm this is really the folder the user means, then: {"id": "<folder_ulid>"}

Share an existing shared folder with someone by email. When to call this tool ---------------------- Call this tool when: - The user wants to grant another person access to a folder that is already a shared (kind="shared") folder. Do NOT call this tool: - On a private (kind="custom") folder - not supported. See "Behavior and edge cases" below for the workaround. - To change what kind of folder something is (use "update_folder" for attribute edits; there is no MCP tool to convert a private folder to shared). - With a guessed or fabricated folder ID. Only use IDs explicitly provided by the user or returned from another tool (e.g. "list_folders"). Parameters ---------- id : str The folder's ULID identifier. Must already be kind="shared" - check with "get_folder" or "list_folders" first if unsure. email : str Email address to share the folder with. access_level : str, default "viewer" Access level to grant the recipient: "viewer" (read access) or "editor" (read + add/remove items). Ownership cannot be granted. message : Optional[str] Optional personal message to include in the invite email. notify : bool, default True Whether to send the recipient an invite email notifying them of the shared folder. Returns ------- FolderEvent The folder's state after the share - same shape as "get_folder". Behavior and edge cases ----------------------- - Authentication: - Access token is handled internally; do not supply it as a parameter. - Access: - The caller must have edit access to the folder (owner or editor). If not, the tool fails with a permissions error. - Folder must already be shared: - If the target folder is private (kind="custom"), the tool fails with a clear error rather than converting it. Workaround: create a new shared folder, add the same meetings to it (some meetings may not carry over - adding to a shared folder requires editor access to each meeting, versus only viewer access for a private folder), then delete the original private folder if it's no longer needed. - Idempotency: - The access grant itself is idempotent (repeating an identical share does not create a duplicate grant), but the invite email is not always deduplicated: a recipient who does not yet have a Read AI account only gets a fresh invite email the first time they're shared with, while a recipient who already has an account may receive a new notification email on every call with `notify=true`, even if they already had this exact access level. Usage examples for agents ------------------------- 1) User: "Share my 'Q3 Sales Calls' folder with alex@example.com as a viewer." -> First confirm the folder is shared (via "get_folder"), then: {"id": "<folder_ulid>", "email": "alex@example.com", "access_level": "viewer"} 2) User: "Give jordan@example.com edit access to that folder, with a note." -> { "id": "<folder_ulid>", "email": "jordan@example.com", "access_level": "editor", "message": "Adding you so you can help tag new calls." }