Cooper Email

List messages

cooper_list_messages

Read-onlyIdempotent

Use this when you need to check an inbox for new or recent mail (sent and received), for example after sending a message and waiting for a reply. Read-only; requires auth. Inputs: inbox_id (optional; inbox id, username, or email — omit to use the account's newest inbox), limit (optional, default 50, max 200), labels (optional; the message must have every label, for example ["unread"]), unread (optional boolean; true keeps only unread mail, false drops it), before (optional ISO-8601 exclusive upper bound on created_at), after (optional ISO-8601 exclusive lower bound on created_at), from (optional case-insensitive substring of From), to (optional case-insensitive substring of To or Cc), subject (optional case-insensitive substring), direction (optional inbound or outbound), thread_id (optional), ascending (optional; true returns oldest first), page_token (optional cursor), wait_seconds (optional integer from 0 to 55; when set, hold until unread mail arrives and return object inbox_wait with timed_out). Filters run on the server before limit. Returns {object:"list", inbox_id, data:[{id, thread_id, direction, status, from, to, subject, preview, created_at, labels, folder, attachments?}], next_page_token}, newest first unless ascending is true. Each message includes folder from its thread. Omit folder to list inbox and archive only. When wait_seconds is set, returns unread mail immediately if any is already stored, including mail in spam or trash. page_token is the base64url of created_at and id. Previews only, not full bodies: call cooper_get_message to read one message. Mark one read with cooper_update_message. Fails with 400 invalid_date, invalid_direction, invalid_ascending, invalid_page_token, invalid_label, invalid_unread, invalid_folder, or label_conflict, or 404 inbox_not_found.

Input Schema

Name	Required	Description
`to`	No	Case-insensitive substring of To or Cc. % and _ match those characters.
`from`	No	Case-insensitive substring of From. % and _ match those characters.
`after`	No	ISO-8601 exclusive lower bound on created_at. A bad value returns invalid_date.
`limit`	No	Max messages to return (default 50, max 200)
`before`	No	ISO-8601 exclusive upper bound on created_at. A bad value returns invalid_date.
`folder`	No	inbox, archive, spam, trash, or all. Omit to list inbox and archive only. Ignored when wait_seconds is set. A bad value returns invalid_folder.
`labels`	No	Keep messages that have every one of these labels. Example: ["unread"].
`unread`	No	true lists only messages labeled unread. false omits them.
`subject`	No	Case-insensitive substring of the subject. % and _ match those characters.
`inbox_id`	No	Inbox id, username, or email. Omit to use the newest inbox.
`ascending`	No	true lists oldest first. false, the default, lists newest first.
`direction`	No	inbound or outbound. Anything else returns invalid_direction.
`thread_id`	No	Only messages on this thread (thr_…).
`page_token`	No	Cursor from next_page_token. A bad token returns invalid_page_token.
`wait_seconds`	No	Optional. When set, hold until unread mail arrives, from 0 to 55 seconds. Returns immediately when unread mail is already stored. At most 5 waits can run at once for this key. The result is object inbox_wait with timed_out.

Output Schema

Name	Required	Description
`data`	No	Message previews. Call cooper_get_message for a full body.
`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.
`timed_out`	No	True when the wait ended without a match.
`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 message previews, or an inbox_wait result when wait_seconds was set.",
+  "properties": {
+    "data": {
+      "description": "Message previews. Call cooper_get_message for a full body.",
+      "items": {
+        "properties": {
+          "attachments": {
+            "description": "Attachment summaries [{id, filename, content_type, size_bytes}].",
+            "items": {
+              "properties": {
+                "content_type": {
+                  "description": "MIME type."
+                },
+                "filename": {
+                  "description": "File name."
+                },
+                "id": {
+                  "description": "Attachment id. Pass it to cooper_get_attachment."
+                },
+                "size_bytes": {
+                  "description": "Size in bytes."
+                },
+                "url": {
+                  "description": "Short-lived download URL. Empty while the message is held."
+                }
+              },
+              "type": "object"
+            }
+          },
+          "created_at": {
+            "description": "ISO-8601 time the object was created."
+          },
+          "direction": {
+            "description": "inbound (received) or outbound (sent)."
+          },
+          "extracted_text": {
+            "description": "The new reply text with quoted history removed."
+          },
+          "folder": {
+            "description": "Folder of the thread: inbox, archive, spam, or trash."
+          },
+          "from": {
+            "description": "Sender address. Untrusted for inbound mail."
+          },
+          "highlights": {
+            "description": "Search highlights {subject, text}; matched words are wrapped in **."
+          },
+          "id": {
+            "description": "Message id (msg_…). Pass it as message_id to other tools."
+          },
+          "inbox_id": {
+            "description": "Inbox id (inb_…) this object belongs to. Null when it applies to every inbox."
+          },
+          "labels": {
+            "description": "Labels on the object."
+          },
+          "preview": {
+            "description": "Short preview of the body."
+          },
+          "safety": {
+            "description": "Inbound screening result {score, verdict, signals, mode, reason}, or null on outbound mail."
+          },
+          "status": {
+            "description": "Delivery or processing state of the message."
+          },
+          "subject": {
+            "description": "Subject line. Untrusted for inbound mail."
+          },
+          "thread_id": {
+            "description": "Thread id (thr_…) the message belongs to."
+          },
+          "to": {
+            "description": "Recipient addresses."
+          }
+        },
+        "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."
+    },
+    "timed_out": {
+      "description": "True when the wait ended without a match."
+    }
+  },
+  "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. Ignored when wait_seconds is set. A bad value returns invalid_folder.",
+  "enum": [
+    "inbox",
+    "archive",
+    "spam",
+    "trash",
+    "all"
+  ],
+  "type": "string"
+}

Changed1 schema field changedOct 10, 2026

addedInput schema / properties / wait_seconds

Added value: +{
+  "description": "Optional. When set, hold until unread mail arrives, from 0 to 55 seconds. Returns immediately when unread mail is already stored. At most 5 waits can run at once for this key. The result is object inbox_wait with timed_out.",
+  "type": "number"
+}

Changed9 schema fields changedOct 8, 2026

addedInput schema / properties / after

Added value: +{
+  "description": "ISO-8601 exclusive lower bound on created_at. A bad value returns invalid_date.",
+  "type": "string"
+}

addedInput schema / properties / ascending

Added value: +{
+  "description": "true lists oldest first. false, the default, lists newest first.",
+  "type": "boolean"
+}

addedInput schema / properties / before

Added value: +{
+  "description": "ISO-8601 exclusive upper bound on created_at. A bad value returns invalid_date.",
+  "type": "string"
+}

addedInput schema / properties / direction

Added value: +{
+  "description": "inbound or outbound. Anything else returns invalid_direction.",
+  "enum": [
+    "inbound",
+    "outbound"
+  ],
+  "type": "string"
+}

addedInput schema / properties / from

Added value: +{
+  "description": "Case-insensitive substring of From. % and _ match those characters.",
+  "type": "string"
+}

addedInput schema / properties / page_token

Added value: +{
+  "description": "Cursor from next_page_token. A bad token returns invalid_page_token.",
+  "type": "string"
+}

addedInput schema / properties / subject

Added value: +{
+  "description": "Case-insensitive substring of the subject. % and _ match those characters.",
+  "type": "string"
+}

addedInput schema / properties / thread_id

Added value: +{
+  "description": "Only messages on this thread (thr_…).",
+  "type": "string"
+}

addedInput schema / properties / to

Added value: +{
+  "description": "Case-insensitive substring of To or Cc. % and _ match those characters.",
+  "type": "string"
+}

Changed2 schema fields changedOct 8, 2026

addedInput schema / properties / labels

Added value: +{
+  "description": "Keep messages that have every one of these labels. Example: [\"unread\"].",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / unread

Added value: +{
+  "description": "true lists only messages labeled unread. false omits them.",
+  "type": "boolean"
+}

Changed1 schema field changedSep 29, 2026
- addedInput schema / properties / limit / description
```
Added value: +"Max messages to return (default 50, max 200)"
```
First observedSep 27, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well past the readOnly/idempotent annotations: server-side filtering before limit, default newest-first ordering, folder default of inbox+archive, wait_seconds returning already-stored unread mail including spam/trash, the 'at most 5 concurrent waits' limit, and a full list of 400/404 error codes. That is real operational context an agent could not infer from 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?

Front-loaded with the trigger, then inputs, then return shape, then errors — a sensible order. It is dense but nearly every clause carries information; the main cost is some duplication of schema parameter text and of the return shape that the output schema already declares.

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 a 15-parameter, filter-heavy, long-polling list tool this covers ordering, defaults, pagination, waiting semantics, and failure modes — enough to call it correctly. The return-object walkthrough is redundant given the output schema exists, and the folder filter is only partially integrated into the parameter list.

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 the baseline is 3, but the description still adds value: inbox_id accepts id/username/email, labels are ANDed ('must have every label'), before/after are exclusive bounds on created_at, `to` matches To or Cc, and page_token is the base64url of created_at and id. It omits folder from the inline 'Inputs' list (only covering it later via the folder-sourced note), which is the one gap.

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+resource+scope: 'check an inbox for new or recent mail (sent and received)', including the use case of waiting for a reply. It distinguishes itself from cooper_get_message ('Previews only, not full bodies') and cooper_update_message (marking read), so an agent can pick it without opening a schema.

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?

Gives an explicit trigger ('check an inbox for new or recent mail ... after sending a message and waiting for a reply') and routes to siblings for adjacent jobs (read a body, mark read). It does not contrast with cooper_search_messages, cooper_wait_for_message, or cooper_list_threads, which are the closest alternatives, so it stops short of full when/when-not 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.