Carbon Voice

list_messages

Read-only

Retrieve messages with filters for date, conversation, folder, workspace, creator, or language. Includes full bodies, transcripts, and AI summaries for review.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No	1-based page number. Use with `size`; check `has_next_page` in the response.
`size`	No	Max number of results per page is: 50
`type`	No	Type (optional)
`end_date`	No	End Date range
`language`	No	Language (optional)
`user_ids`	No	Filter by message CREATOR (sender) — matched against `creator_id`, not participants. Requires user IDs from `search_users`, not names. To find messages exchanged WITH someone, resolve the conversation via `list_conversations` and pass `conversation_id` instead.
`folder_id`	No	Folder ID (optional)
`start_date`	No	Start Date range
`workspace_id`	No	Workspace ID (optional)
`sort_direction`	No	The field used to sort results is Creation Date	DESC
`conversation_id`	No	Conversation ID (optional)
`response_fields`	No	Dot-path allowlist to shrink the response, e.g. ["results.id","total"]. Omit for the full payload.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.10.0Sep 14, 2026

addedInput schema / properties / page / description

Added value: +"1-based page number. Use with `size`; check `has_next_page` in the response."

addedInput schema / properties / response_fields

Added value: +{
+  "description": "Dot-path allowlist to shrink the response, e.g. [\"results.id\",\"total\"]. Omit for the full payload.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / user_ids / description

Previous value: -"User IDs (optional). List of user IDs to filter messages by. If not provided, all users will be included."New value: +"Filter by message CREATOR (sender) — matched against `creator_id`, not participants. Requires user IDs from `search_users`, not names. To find messages exchanged WITH someone, resolve the conversation via `list_conversations` and pass `conversation_id` instead."

First observedAug 15, 2025

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond readOnlyHint=true/destructiveHint=false, the description discloses the 183-day max date span, that user_ids filters by SENDER (matched against creator_id, not participants), the pagination contract ('Page on has_next_page/total — do not guess'), and that the full payload is much larger, warranting response_fields narrowing. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Longer than typical but every section earns its place given 12 params and ~39 siblings. The sectioned format (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, NARROW) is scannable and front-loaded with the core purpose. Slight density cost, hence not a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates fully by inlining the return structure, pagination guidance, and payload-shrinking advice. Covers setup prerequisites, usage routing, and behavioral constraints for a complex 12-param tool with zero required parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds genuine value on top: the user_ids semantics (filters by sender/creator_id, requires IDs from search_users, resolve conversations for the WITH-someone case), the origin of workspace_id, and the response_fields dot-path usage. These go beyond what the schema states, earning a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource plus explicit filter dimensions ('date, conversation, folder, workspace, creator or language'). Differentiates from siblings by naming get_recent_messages and search_message_ids and what distinguishes them. The USE INSTEAD section preempts the agent picking the wrong sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit USE WHEN / USE INSTEAD routing: get_recent_messages for a quick capped look (hard-capped at 10, no paging) and search_message_ids for filters this cannot express (notified state, mentions, labels). Also instructs FIRST to resolve workspace_id from get_workspaces_basic_info, covering the prerequisite an agent would otherwise have to infer.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

list_messages

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools