Cooper Email

List threads

cooper_list_threads

Read-onlyIdempotent

Use this when you need whole conversations instead of individual messages, for example to see who is in a thread and when the last reply arrived. Read-only; requires auth. Inputs: inbox_id (optional; inbox id, username, or email — omit to list every inbox on the account), assignee (optional; 1–64 characters: letters, digits, and . _ @ + : -), unassigned (optional; true returns threads with no assignment), claimable (optional; true returns threads that are unassigned or whose claim has expired), limit (optional, default 20, max 100), page_token (optional cursor from a previous page), before (optional ISO-8601 upper bound on updated_at), after (optional ISO-8601 lower bound on updated_at). Returns {object:"list", inbox_id, data:[thread], next_page_token}. Each thread has id, subject (first message), preview (latest message), senders, recipients, message_count, last_message_id, labels, attachment_count, received_at, sent_at, created_at, updated_at, assignment (null or a thread_assignment), folder (inbox, archive, spam, or trash), and purge_after (set only for trash). Ordered by updated_at, newest first. Omit folder to list inbox and archive only. A bad page_token returns HTTP 400 invalid_page_token. A bad assignee returns HTTP 400 invalid_assignee. A bad folder returns invalid_folder. An unknown inbox_id returns inbox_not_found.

Input Schema

Name	Required	Description
`after`	No	Only threads whose latest message is after this ISO-8601 timestamp.
`limit`	No	Max threads to return (default 20, max 100)
`before`	No	Only threads whose latest message is before this ISO-8601 timestamp.
`folder`	No	inbox, archive, spam, trash, or all. Omit to list inbox and archive only. Spam and trash stay hidden until you ask for them. A bad value returns invalid_folder.
`assignee`	No	Only threads assigned to this handle. 1–64 characters: letters, digits, and . _ @ + : -.
`inbox_id`	No	Inbox id, username, or email. Omit to list threads in every inbox on the account.
`claimable`	No	When true, threads that are unassigned or whose claim has expired. A worker pool uses this to pick work.
`page_token`	No	Cursor from next_page_token. A bad token returns invalid_page_token.
`unassigned`	No	When true, only threads with no assignment row.

Output Schema

Name	Required	Description
`data`	No	Items on this page, in the order the tool description gives.
`object`	No	Object type name, such as list, message, or thread.
`inbox_id`	No	Inbox id (inb_…) this object belongs to. Null when it applies to every inbox.
`next_page_token`	No	Cursor for the next page, or null when this is the last page. Pass it back as page_token.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 3, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "description": "One page of threads.",
+  "properties": {
+    "data": {
+      "description": "Items on this page, in the order the tool description gives.",
+      "items": {
+        "properties": {
+          "assignment": {
+            "description": "Current assignment {assignee, note, claimed_until, claim_active, …}, or null."
+          },
+          "attachment_count": {
+            "description": "Number of attachments across the thread."
+          },
+          "created_at": {
+            "description": "ISO-8601 time the object was created."
+          },
+          "folder": {
+            "description": "inbox, archive, spam, or trash."
+          },
+          "id": {
+            "description": "Thread id (thr_…)."
+          },
+          "inbox_id": {
+            "description": "Inbox id (inb_…) this object belongs to. Null when it applies to every inbox."
+          },
+          "labels": {
+            "description": "Labels on the object."
+          },
+          "last_message_id": {
+            "description": "Id of the newest message."
+          },
+          "message_count": {
+            "description": "Number of messages on the thread."
+          },
+          "preview": {
+            "description": "Preview of the latest message."
+          },
+          "purge_after": {
+            "description": "ISO-8601 time a trashed thread is deleted, or null."
+          },
+          "received_at": {
+            "description": "ISO-8601 time of the latest inbound message, or null."
+          },
+          "recipients": {
+            "description": "Addresses that received mail on this thread."
+          },
+          "senders": {
+            "description": "Addresses that sent mail on this thread."
+          },
+          "sent_at": {
+            "description": "ISO-8601 time of the latest outbound message, or null."
+          },
+          "subject": {
+            "description": "Subject of the first message."
+          },
+          "updated_at": {
+            "description": "ISO-8601 time the object last changed."
+          }
+        },
+        "type": "object"
+      }
+    },
+    "inbox_id": {
+      "description": "Inbox id (inb_…) this object belongs to. Null when it applies to every inbox."
+    },
+    "next_page_token": {
+      "description": "Cursor for the next page, or null when this is the last page. Pass it back as page_token."
+    },
+    "object": {
+      "description": "Object type name, such as list, message, or thread."
+    }
+  },
+  "type": "object"
+}

Changed1 schema field changedOct 25, 2026

addedInput schema / properties / folder

Added value: +{
+  "description": "inbox, archive, spam, trash, or all. Omit to list inbox and archive only. Spam and trash stay hidden until you ask for them. A bad value returns invalid_folder.",
+  "enum": [
+    "inbox",
+    "archive",
+    "spam",
+    "trash",
+    "all"
+  ],
+  "type": "string"
+}

Changed3 schema fields changedOct 24, 2026

addedInput schema / properties / assignee

Added value: +{
+  "description": "Only threads assigned to this handle. 1–64 characters: letters, digits, and . _ @ + : -.",
+  "type": "string"
+}

addedInput schema / properties / claimable

Added value: +{
+  "description": "When true, threads that are unassigned or whose claim has expired. A worker pool uses this to pick work.",
+  "type": "boolean"
+}

addedInput schema / properties / unassigned

Added value: +{
+  "description": "When true, only threads with no assignment row.",
+  "type": "boolean"
+}

AddedOct 8, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the basic annotations, the description is highly transparent, detailing the return structure, ordering (newest first), and specific error behaviors (e.g., HTTP 400 for bad tokens/IDs). This level of detail significantly reduces ambiguity for the agent.

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?

While detailed and somewhat dense, the description is well-structured to front-load the primary purpose and follow with detailed constraints and operational definitions, making its verbosity necessary for the 9-parameter complexity.

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 definition is exceptionally complete. It covers purpose, usage, parameter semantics, return structure, error handling, and specific scoping rules (like the `folder` default). No crucial operational knowledge is missing.

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 the schema is complete, the description adds critical context: it explains that omitting `inbox_id` searches all inboxes, clarifies that `claimable` is for 'worker pool' logic, and specifies default behaviors for the `folder` parameter.

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 description clearly states that this tool is for retrieving 'whole conversations' (threads) and contrasts its function with fetching 'individual messages,' effectively distinguishing it from message listing siblings in the repertoire.

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 explicitly frames the use case by giving examples of why one would need threads over messages (seeing members or last reply time), providing clear directional guidance.

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

All Cooper Email tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.