Skip to main content
Glama

List conversations

list_conversations

Lists threads, most recently updated first, with the contact, the subject of the mail and the one the team gave the thread ("team_subject", null until rename_conversation gives one), the ticket number of a helpdesk case (what the client quotes, null on somebody's mailbox), the status, where the thread stands in the pipeline, who is handling it, whether a draft is waiting for review, the folder each sits in and whether you have read it. Each thread also says since when its contact has been waiting for our answer ("waiting_since", their oldest message still unanswered, null when nobody waits), and when the last reply came and from which side ("last_reply_at", "last_reply_by"): the two figures a helpdesk queue is watched by, to tell which tickets drag. Name a "box" to read ONE mailbox exactly as its screen shows it: its Inbox by default, another folder on demand, and "unread" for the bold rows alone. Without a "box" it lists the whole account by pipeline status instead, which is a different question: a thread sitting unread in a mailbox has a status like any other, so a list by status is not the list of what is waiting to be read.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_conversations"
  }
}

Input Schema

NameRequiredDescriptionDefault
boxNoThe address of the mailbox to look in, for example "simon@sonentreprise.com": call list_sender_addresses to find it. One of its aliases names the same mailbox. A support queue is not a mailbox and has no folders.
teamNoNarrows to the threads handed to one team, by its slug (list_teams gives it), taken by one of its members or not. Narrows the account list, so it does not go with "box".
brandNoThe slug of a brand, to narrow to that subdivision of the account: call list_brands to find it.
limitNoHow many threads to bring back, 1 to 200. Defaults to 100.
beforeNoOnly the threads updated before this instant, as an ISO 8601 timestamp such as "2026-08-31T09:00:00Z". This is how you read past the first page: take the "updated_at" of the last thread the answer gave you and ask again with it.
folderNoWhich folder of the box to list: one of inbox, sent, drafts, spam, trash, archive, or the id of a folder a person made (list_folders gives them). Defaults to the Inbox, like opening the mailbox does. Needs "box".
statusNoWhere the thread stands: "open" for one nobody has taken, "customer_reply" when the contact has written back, "answered" once we replied, "delivery_failed" when our reply bounced, "in_progress" while someone works on it, "closed" when it is over.
unreadNoOnly the threads you have not read: the bold rows of the screen, and the same count its Inbox shows. Needs "box". A key that acts for no person has no read state and is told so rather than answered with a list built for nobody.
channelNoThe channel the thread runs on. Email is the usual one; "portal" carries the messages written from a client space.
assigneeNoNarrows to the threads one person is handling, by the email address they sign in with, which list_people gives. The word "none" answers with what nobody has taken yet, which is the queue waiting to be shared out (a thread handed to a team has been shared out). Narrows the account list, so it does not go with "box".
external_refNoNarrows to the threads of one contact identified by the reference a consumer app gave them, for example "epovest:account:42".

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / box / description
      Previous value: -"The address of the mailbox to look in, for example \"simon@sonentreprise.com\": call list_sender_addresses to find it. A support queue is not a mailbox and has no folders."New value: +"The address of the mailbox to look in, for example \"simon@sonentreprise.com\": call list_sender_addresses to find it. One of its aliases names the same mailbox. A support queue is not a mailbox and has no folders."
  2. First observed

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations, the description carries the load and does so well: default ordering, default limit, cursor pagination via updated_at, null semantics for team_subject/waiting_since, and an explicit error case ('A key that acts for no person has no read state and is told so'). It does not state permissions, rate limits, or that the call is purely read-only beyond the implication of 'Lists'.

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

Conciseness3/5

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

The one-sentence front load is correct, but the remainder is a single sprawling block dense with nested parentheticals and field-by-field enumeration, some of which duplicates the 100%-covered schema. It is informative but tiring to parse and not segmented by mode.

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

Completeness4/5

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

For an 11-parameter, zero-required tool with no output schema, describing returned fields (waiting_since, last_reply_at, team_subject) is justified and largely complete, including pagination mechanics. The main omission is any statement of what happens with multiple narrowing filters combined or whether results are ever truncated beyond 'limit'.

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 already 100%, so the baseline is 3; the description earns above it by explaining interactions the schema only hints at — box vs status listing semantics, 'unread' as the bold rows, 'none' for assignee meaning the unshared queue, and that a support queue is not a mailbox. It still leaves the exact timezone/ordering interaction of 'before' vs the default sort implicit.

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

Purpose4/5

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

The opening clause states a specific verb and resource ('Lists threads, most recently updated first') and immediately scopes the two listing modes (per-mailbox vs whole-account-by-status). It never names the obvious sibling search_conversations, so an agent must infer the list-vs-search boundary, which keeps it out of 5 territory.

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

Usage Guidelines4/5

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

It gives concrete selection rules: pass 'box' to read one mailbox as its screen shows it, omit it to list by pipeline status, and it explicitly warns that these are 'a different question'. The schema also records the incompatibilities (team/assignee 'does not go with box'; folder/unread need box). No guidance on when keyword search would be the better tool, so not a 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources