Skip to main content
Glama
PhononX

Carbon Voice

by PhononX
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

list_conversations

Read-only

Find conversation IDs from the last 6 months by filtering participants, type, or name. Returns matching conversations with ID, name, workspace, and type.

Instructions

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoKeep only conversations whose name contains this string, case-insensitively. When nothing matches, check `unfiltered_count` before reporting no such conversation — it says how many existed to match against. Several matches means ask which was meant.
matchNoMatch mode for `user_ids`: `any` (union, default) or `all` (intersection). YOU are always included implicitly — `user_ids: ["u1"]` already means conversations containing you and u1, so never pass your own ID. Doing so under `any` matches every conversation you are in and silently discards the filter.
typesNoKeep only these conversation types. `directMessage` is the 1:1 with someone — combine with `user_ids` to find your DM with a person. `namedConversation` is a conversation somebody named. Omit for all types.
user_idsNoList of user IDs to filter conversations by. When omitted, all conversations for the caller are returned. Requires actual user IDs, not usernames or display names. If you only have a person's name, call `search_users` first (e.g. `names: ["Brett"]`) to resolve it to a user ID. If `search_users` returns more than one candidate for a name, ask the caller which person they meant instead of guessing.
response_fieldsNoDot-path allowlist to shrink the response, e.g. ["results.id","total"]. Omit for the full payload.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.12.0
    • addedInput schema / properties / name
      Added value: +{
+  "description": "Keep only conversations whose name contains this string, case-insensitively. When nothing matches, check `unfiltered_count` before reporting no such conversation — it says how many existed to match against. Several matches means ask which was meant.",
+  "type": "string"
+}
  2. Changed5 schema fields changedv2.10.0
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / match
      Added value: +{
+  "description": "Match mode for `user_ids`: `any` (union, default) or `all` (intersection). YOU are always included implicitly — `user_ids: [\"u1\"]` already means conversations containing you and u1, so never pass your own ID. Doing so under `any` matches every conversation you are in and silently discards the filter.",
+  "enum": [
+    "any",
+    "all"
+  ],
+  "type": "string"
+}
    • 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"
+}
    • addedInput schema / properties / types
      Added value: +{
+  "description": "Keep only these conversation types. `directMessage` is the 1:1 with someone — combine with `user_ids` to find your DM with a person. `namedConversation` is a conversation somebody named. Omit for all types.",
+  "items": {
+    "enum": [
+      "directMessage",
+      "customerConversation",
+      "namedConversation",
+      "asyncMeeting"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / user_ids
      Added value: +{
+  "description": "List of user IDs to filter conversations by. When omitted, all conversations for the caller are returned. Requires actual user IDs, not usernames or display names. If you only have a person's name, call `search_users` first (e.g. `names: [\"Brett\"]`) to resolve it to a user ID. If `search_users` returns more than one candidate for a name, ask the caller which person they meant instead of guessing.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  3. Changed1 schema field changedv1.0.0
    • removedInput schema / additionalProperties
      Removed value: -false
  4. First observed

TDQS

A5/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail beyond that: the 6-month retention window, implicit participant semantics, filter AND-ing, the meaning of unfiltered_count, and the absence of paging. These details are critical for correct invocation and interpretation.

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

Conciseness5/5

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

The description is well-structured with clear section labels (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS) and front-loads the core purpose. Despite its length, each sentence contributes operational guidance rather than repetition, and the format makes it easy for an agent to parse.

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?

The description fully covers the tool's complexity: return shape, type enum, count semantics, edge cases (0 of 47 vs 0 of 0), and when to ask the caller for clarification. Since there is no output schema, the description correctly carries the responsibility of explaining the response and filtering behavior.

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

Parameters5/5

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

Although schema description coverage is 100%, the description adds meaning the schema alone does not fully convey: the agent is always an implicit participant, passing the caller's own ID silently breaks filtering, and user_ids must be resolved via search_users before use. It also supplies a concrete JSON example that models correct parameter usage.

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?

The first sentence states a specific verb ('List'), resource ('your conversations'), time scope ('last 6 months'), and optional filters. It also explicitly contrasts itself with get_conversation, saying it returns only id, name, workspace_id and type, which makes its identity unambiguous among siblings.

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?

The description provides explicit 'USE WHEN' and 'USE INSTEAD' guidance, names the alternative tool, and explains the exact conditions for choosing between them. It also instructs the agent on what to do when filters produce multiple matches or when unfiltered_count suggests a nonexistent conversation.

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

Deploy Server

Other Tools