Cherami

Find conversations

list_threads

Read-onlyIdempotent

Find an inbox's conversations containing at least one message that matches all supplied filters.

Input Schema

Name	Required	Description
`from`	No	Exact From address, case-insensitive.
`after`	No	Received or sent at or after this time: YYYY-MM-DDTHH:mm:ss, optional 1–3 fractional digits, then Z or ±HH:mm.
`limit`	No
`order`	No	Defaults to newest. relevance requires query. Conversations sort by their latest activity.
`query`	No	Words or quoted phrases that must all appear in the subject or body. Case-insensitive keyword match, not semantic search; up to 16 terms or phrases.
`before`	No	Received or sent before this time: YYYY-MM-DDTHH:mm:ss, optional 1–3 fractional digits, then Z or ±HH:mm.
`cursor`	No	Continue with next_cursor from the previous result, keeping the same filters. Stop when next_cursor is null.
`subject`	No	Literal, case-insensitive substring of the subject.
`inbox_id`	Yes
`recipient`	No	Exact To, Cc or Bcc address, case-insensitive.
`labels_all`	No	Require every listed label. An empty array in any label filter adds no condition.
`labels_any`	No	Require at least one listed label.
`labels_none`	No	Exclude messages with any listed label.

Output Schema

Name	Required	Description	Default
`threads`	Yes
`next_cursor`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedOct 9, 2026

changedInput schema / properties / after / description

Previous value: -"Inclusive receipt/submission time: YYYY-MM-DDTHH:mm:ss, optional 1–3 fractional digits, then Z or ±HH:mm."New value: +"Received or sent at or after this time: YYYY-MM-DDTHH:mm:ss, optional 1–3 fractional digits, then Z or ±HH:mm."

changedInput schema / properties / before / description

Previous value: -"Exclusive receipt/submission time: YYYY-MM-DDTHH:mm:ss, optional 1–3 fractional digits, then Z or ±HH:mm."New value: +"Received or sent before this time: YYYY-MM-DDTHH:mm:ss, optional 1–3 fractional digits, then Z or ±HH:mm."

changedInput schema / properties / from / description

Previous value: -"Exact email address in From, case-insensitive; not the SMTP envelope sender."New value: +"Exact From address, case-insensitive."

changedInput schema / properties / labels_all / description

Previous value: -"Require every listed label. Filter groups combine with AND; empty arrays impose no condition."New value: +"Require every listed label. An empty array in any label filter adds no condition."

changedInput schema / properties / order / description

Previous value: -"Defaults to newest. Relevance requires query; ties use newest first. Threads order by their latest activity."New value: +"Defaults to newest. relevance requires query. Conversations sort by their latest activity."

changedInput schema / properties / query / description

Previous value: -"Match all words or quoted phrases in subject/body. Case-insensitive keyword search, not semantic similarity; up to 16 terms/phrases."New value: +"Words or quoted phrases that must all appear in the subject or body. Case-insensitive keyword match, not semantic search; up to 16 terms or phrases."

changedInput schema / properties / recipient / description

Previous value: -"Exact email address in To/Cc/Bcc where available, case-insensitive."New value: +"Exact To, Cc or Bcc address, case-insensitive."

changedInput schema / properties / subject / description

Previous value: -"Literal case-insensitive substring of the subject."New value: +"Literal, case-insensitive substring of the subject."

addedOutput schema / properties / threads / items / properties / latest_message

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "counterpart": {
+          "anyOf": [
+            {
+              "anyOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "address": {
+                      "type": "string"
+                    },
+                    "name": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "name",
+                    "address"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "group": {
+                      "items": {
+                        "additionalProperties": false,
+                        "properties": {
+                          "address": {
+                            "type": "string"
+                          },
+                          "name": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "name",
+                          "address"
+                        ],
+                        "type": "object"
+                      },
+                      "type": "array"
+                    },
+                    "name": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "name",
+                    "group"
+                  ],
+                  "type": "object"
+                }
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Parsed From; null when absent."
+        },
+        "direction": {
+          "const": "received",
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "direction",
+        "counterpart"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "counterpart": {
+          "anyOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "address": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "address"
+              ],
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "First To recipient, lowercased address without name; null when unavailable."
+        },
+        "direction": {
+          "const": "sent",
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "direction",
+        "counterpart"
+      ],
+      "type": "object"
+    }
+  ],
+  "description": "Newest message in the conversation, even when filters matched others."
+}

changedOutput schema / properties / threads / items / properties / matching_message_count / description

Previous value: -"Total matching members; may exceed the returned matching IDs."New value: +"Number of matching messages; can exceed the 100 IDs returned."

changedOutput schema / properties / threads / items / properties / matching_message_ids / description

Previous value: -"Up to 100 matching member IDs, newest first. Present when filters are supplied."New value: +"IDs of up to 100 matching messages, newest first. Present when filters are supplied."

changedOutput schema / properties / threads / items / required

Previous value: -[
-  "id",
-  "inbox_id",
-  "subject",
-  "message_count",
-  "received_count",
-  "accepted_count",
-  "rejected_count",
-  "unknown_count",
-  "last_activity_at"
-]New value: +[
+  "id",
+  "inbox_id",
+  "subject",
+  "message_count",
+  "received_count",
+  "accepted_count",
+  "rejected_count",
+  "unknown_count",
+  "last_activity_at",
+  "latest_message"
+]

First observedOct 4, 2026

TDQS

B3.3/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real value by specifying AND semantics across filters and that matching happens at the message level, but says nothing about pagination behavior or how results are ordered/capped beyond what the schema already documents.

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?

A single front-loaded sentence with no filler; the qualifying condition is stated immediately and nothing is repeated from the title or schema.

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

Completeness3/5

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

For a 13-parameter tool the description is thin, relying on the schema and an existing output schema for return values. It omits when-to-use context and behavior for the no-filter case, leaving real gaps even though the structured fields carry most of the load.

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

Parameters3/5

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

Schema description coverage is 85%, so the schema already explains nearly every parameter (from, query, cursor, labels_*, order, etc.). The description only reinforces the AND-of-all-filters rule and adds no per-parameter syntax or format detail beyond that.

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?

States a specific verb and resource ('Find an inbox's conversations') and adds the key semantic that a conversation qualifies if at least one of its messages matches all filters. This distinguishes it from list_messages (which returns messages) and count_messages, though no sibling is named explicitly.

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

Usage Guidelines2/5

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

No guidance on when to use this versus get_thread, list_messages, or count_messages, and no statement about behavior when filters are omitted. Usage is only implied by the filter-matching sentence.

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

All Cherami 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.

Resources

Need Help?