Skip to main content
Glama
Sign In

email

by dev.primitive
OverviewDiscussionsAdmin

Get conversation

getConversation
Read-onlyIdempotent

Read a whole conversation with message bodies: the tool for finding out what was said. Pass the id of any inbound email in the thread. Each message has a direction and a role (inbound→user, outbound→assistant). Texts have links as [link] and quoted history removed; full: true returns them as stored, with message ids. A brand-new message has thread_id null and one message. For link targets, use getEmail (links: "all") or getSentEmail (full: true). For a thread of only messages you sent, use listSentEmails and getSentEmail. Result: thread_id, subject, messages, quoted_chars_removed (0 with full), and when given, message_count and truncated (message cap reached).

Input Schema

NameRequiredDescriptionDefault
idYesAny inbound email in the thread, by its id from listEmails or searchEmails.
fullNoReturn the stored record, with links, quoted history and message ids, instead of the compact view for reading.

Output Schema

NameRequiredDescriptionDefault
subjectYesSubject of the thread.
messagesYesEvery message, oldest first.
thread_idYesConversation id; null for a brand-new message.
truncatedNoTrue when the message cap was reached.
message_countNoMessages in the thread; more than returned when truncated.
quoted_chars_removedYesCharacters of quoted history left out of the texts; 0 with full.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedOutput schema / properties / messages / items / properties / direction / description
      Previous value: -"inbound or outbound."New value: +"Received or sent."
    • addedOutput schema / properties / messages / items / properties / direction / enum
      Added value: +[
+  "inbound",
+  "outbound"
+]
    • addedOutput schema / properties / messages / items / properties / role / enum
      Added value: +[
+  "user",
+  "assistant"
+]
    • changedOutput schema / properties / messages / items / properties / text / description
      Previous value: -"Readable text, with links as [link]; as stored with full."New value: +"Readable text, with links as [link]; as stored with full. Null if withheld."
    • changedOutput schema / properties / messages / items / properties / text / type
      Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
  2. Changed5 schema fields changed
    • changedOutput schema / properties / messages / items / properties / direction / description
      Previous value: -"Received or sent."New value: +"inbound or outbound."
    • removedOutput schema / properties / messages / items / properties / direction / enum
      Removed value: -[
-  "inbound",
-  "outbound"
-]
    • removedOutput schema / properties / messages / items / properties / role / enum
      Removed value: -[
-  "user",
-  "assistant"
-]
    • changedOutput schema / properties / messages / items / properties / text / description
      Previous value: -"Readable text, with links as [link]; as stored with full. Null if withheld."New value: +"Readable text, with links as [link]; as stored with full."
    • changedOutput schema / properties / messages / items / properties / text / type
      Previous value: -[
-  "string",
-  "null"
-]New value: +"string"
  3. Changed5 schema fields changed
    • changedOutput schema / properties / messages / items / properties / direction / description
      Previous value: -"inbound or outbound."New value: +"Received or sent."
    • addedOutput schema / properties / messages / items / properties / direction / enum
      Added value: +[
+  "inbound",
+  "outbound"
+]
    • addedOutput schema / properties / messages / items / properties / role / enum
      Added value: +[
+  "user",
+  "assistant"
+]
    • changedOutput schema / properties / messages / items / properties / text / description
      Previous value: -"Readable text, with links as [link]; as stored with full."New value: +"Readable text, with links as [link]; as stored with full. Null if withheld."
    • changedOutput schema / properties / messages / items / properties / text / type
      Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
  4. Changed12 schema fields changed
    • addedOutput schema / additionalProperties
      Added value: +false
    • changedOutput schema / description
      Previous value: -"Envelope; the result is in data.data."New value: +"The whole thread, oldest message first."
    • removedOutput schema / properties / data
      Removed value: -{
-  "description": "API response: the result in data, or error.",
-  "properties": {
-    "data": {
-      "description": "The whole thread.",
-      "properties": {
-        "message_count": {
-          "description": "Messages in the thread.",
-          "type": "number"
-        },
-        "messages": {
-          "description": "Every message, oldest first.",
-          "items": {
-            "properties": {
-              "attachments": {
-                "type": "array"
-              },
-              "direction": {
-                "description": "inbound or outbound.",
-                "type": "string"
-              },
-              "from": {
-                "type": "string"
-              },
-              "id": {
-                "type": "string"
-              },
-              "message_id": {
-                "description": "Message-ID header; full only.",
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "role": {
-                "description": "user (inbound) or assistant (outbound).",
-                "type": "string"
-              },
-              "subject": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "text": {
-                "description": "Readable text; as stored with full.",
-                "type": "string"
-              },
-              "timestamp": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "to": {
-                "type": "string"
-              }
-            },
-            "type": "object"
-          },
-          "type": "array"
-        },
-        "quoted_chars_removed": {
-          "description": "Quoted text left out; 0 with full.",
-          "type": "number"
-        },
-        "subject": {
-          "description": "Thread subject.",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "thread_id": {
-          "description": "Null for a brand-new message.",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "truncated": {
-          "description": "Message cap reached.",
-          "type": "boolean"
-        }
-      },
-      "type": [
-        "object",
-        "null"
-      ]
-    },
-    "error": {
-      "description": "Why the call was refused; absent on success.",
-      "properties": {
-        "code": {
-          "description": "Error code to branch on.",
-          "type": "string"
-        },
-        "message": {
-          "description": "What went wrong, in words.",
-          "type": "string"
-        }
-      },
-      "type": [
-        "object",
-        "null"
-      ]
-    },
-    "success": {
-      "description": "True when data holds the result.",
-      "type": "boolean"
-    }
-  },
-  "type": "object"
-}
    • addedOutput schema / properties / message_count
      Added value: +{
+  "description": "Messages in the thread; more than returned when truncated.",
+  "type": "integer"
+}
    • addedOutput schema / properties / messages
      Added value: +{
+  "description": "Every message, oldest first.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "attachments": {
+        "description": "Files on it; absent when none.",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "content_type": {
+              "description": "Media type, such as application/pdf.",
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "filename": {
+              "description": "File name; null when the email gave none.",
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "part_index": {
+              "description": "Pass to getEmailAttachment to read it.",
+              "type": [
+                "integer",
+                "null"
+              ]
+            },
+            "size_bytes": {
+              "description": "Size in bytes.",
+              "type": [
+                "integer",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "filename",
+            "content_type",
+            "size_bytes",
+            "part_index"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "direction": {
+        "description": "inbound or outbound.",
+        "type": "string"
+      },
+      "from": {
+        "description": "Sender.",
+        "type": "string"
+      },
+      "id": {
+        "description": "Email id: getEmail for inbound, getSentEmail for outbound.",
+        "type": "string"
+      },
+      "message_id": {
+        "description": "full only: Message-ID header.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "role": {
+        "description": "user for inbound, assistant for outbound.",
+        "type": "string"
+      },
+      "subject": {
+        "description": "Subject line.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "text": {
+        "description": "Readable text, with links as [link]; as stored with full.",
+        "type": "string"
+      },
+      "timestamp": {
+        "description": "When it was sent or received.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "to": {
+        "description": "Recipients.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "role",
+      "direction",
+      "id",
+      "from",
+      "to",
+      "subject",
+      "text",
+      "timestamp"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / quoted_chars_removed
      Added value: +{
+  "description": "Characters of quoted history left out of the texts; 0 with full.",
+  "type": "integer"
+}
    • removedOutput schema / properties / status
      Removed value: -{
-  "description": "HTTP status; 2xx on success.",
-  "type": "number"
-}
    • addedOutput schema / properties / subject
      Added value: +{
+  "description": "Subject of the thread.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • addedOutput schema / properties / thread_id
      Added value: +{
+  "description": "Conversation id; null for a brand-new message.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • removedOutput schema / properties / tool
      Removed value: -{
-  "description": "Tool that answered.",
-  "type": "string"
-}
    • addedOutput schema / properties / truncated
      Added value: +{
+  "description": "True when the message cap was reached.",
+  "type": "boolean"
+}
    • changedOutput schema / required
      Previous value: -[
-  "tool",
-  "status",
-  "data"
-]New value: +[
+  "thread_id",
+  "subject",
+  "quoted_chars_removed",
+  "messages"
+]
  5. Changed14 schema fields changed
    • changedOutput schema / properties / data / description
      Previous value: -"API response; result in data."New value: +"API response: the result in data, or error."
    • changedOutput schema / properties / data / properties / data / properties / message_count / type
      Previous value: -[
-  "number",
-  "string"
-]New value: +"number"
    • addedOutput schema / properties / data / properties / data / properties / messages / items / properties / message_id
      Added value: +{
+  "description": "Message-ID header; full only.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • changedOutput schema / properties / data / properties / data / properties / messages / items / properties / text / description
      Previous value: -"Readable text, no quoted history."New value: +"Readable text; as stored with full."
    • changedOutput schema / properties / data / properties / data / properties / quoted_chars_removed / description
      Previous value: -"Quoted text left out."New value: +"Quoted text left out; 0 with full."
    • changedOutput schema / properties / data / properties / data / properties / quoted_chars_removed / type
      Previous value: -[
-  "number",
-  "string"
-]New value: +"number"
    • changedOutput schema / properties / data / properties / data / properties / thread_id / description
      Previous value: -"Thread id."New value: +"Null for a brand-new message."
    • changedOutput schema / properties / data / properties / error / description
      Previous value: -"Refusal: code, message."New value: +"Why the call was refused; absent on success."
    • addedOutput schema / properties / data / properties / error / properties
      Added value: +{
+  "code": {
+    "description": "Error code to branch on.",
+    "type": "string"
+  },
+  "message": {
+    "description": "What went wrong, in words.",
+    "type": "string"
+  }
+}
    • addedOutput schema / properties / data / properties / error / type
      Added value: +[
+  "object",
+  "null"
+]
    • changedOutput schema / properties / data / properties / success / description
      Previous value: -"Accepted."New value: +"True when data holds the result."
    • changedOutput schema / properties / data / type
      Previous value: -[
-  "object",
-  "string",
-  "null"
-]New value: +"object"
    • changedOutput schema / properties / status / description
      Previous value: -"HTTP status."New value: +"HTTP status; 2xx on success."
    • addedOutput schema / properties / tool / description
      Added value: +"Tool that answered."
  6. Changed6 schema fields changed
    • changedOutput schema / properties / data / properties / data / properties / message_count / type
      Previous value: -"number"New value: +[
+  "number",
+  "string"
+]
    • removedOutput schema / properties / data / properties / data / properties / messages / items / properties / message_id
      Removed value: -{
-  "description": "Message-ID header; full only.",
-  "type": [
-    "string",
-    "null"
-  ]
-}
    • changedOutput schema / properties / data / properties / data / properties / messages / items / properties / text / description
      Previous value: -"Readable text; as stored with full."New value: +"Readable text, no quoted history."
    • changedOutput schema / properties / data / properties / data / properties / quoted_chars_removed / description
      Previous value: -"Quoted text left out; 0 with full."New value: +"Quoted text left out."
    • changedOutput schema / properties / data / properties / data / properties / quoted_chars_removed / type
      Previous value: -"number"New value: +[
+  "number",
+  "string"
+]
    • changedOutput schema / properties / data / properties / data / properties / thread_id / description
      Previous value: -"Null for a brand-new message."New value: +"Thread id."
  7. Changed6 schema fields changed
    • changedOutput schema / properties / data / properties / data / properties / message_count / type
      Previous value: -[
-  "number",
-  "string"
-]New value: +"number"
    • addedOutput schema / properties / data / properties / data / properties / messages / items / properties / message_id
      Added value: +{
+  "description": "Message-ID header; full only.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • changedOutput schema / properties / data / properties / data / properties / messages / items / properties / text / description
      Previous value: -"Readable text, no quoted history."New value: +"Readable text; as stored with full."
    • changedOutput schema / properties / data / properties / data / properties / quoted_chars_removed / description
      Previous value: -"Quoted text left out."New value: +"Quoted text left out; 0 with full."
    • changedOutput schema / properties / data / properties / data / properties / quoted_chars_removed / type
      Previous value: -[
-  "number",
-  "string"
-]New value: +"number"
    • changedOutput schema / properties / data / properties / data / properties / thread_id / description
      Previous value: -"Thread id."New value: +"Null for a brand-new message."
  8. Changed4 schema fields changed
    • changedOutput schema / description
      Previous value: -"The whole thread."New value: +"Envelope; the result is in data.data."
    • changedOutput schema / properties / data / description
      Previous value: -"API body."New value: +"API response; result in data."
    • addedOutput schema / properties / data / properties / data / description
      Added value: +"The whole thread."
    • changedOutput schema / properties / data / properties / error / description
      Previous value: -"Why refused."New value: +"Refusal: code, message."
  9. Changed2 schema fields changed
    • changedOutput schema / properties / data / properties / data / properties / messages / description
      Previous value: -"Oldest first: role, direction, from, to, text."New value: +"Every message, oldest first."
    • addedOutput schema / properties / data / properties / data / properties / messages / items
      Added value: +{
+  "properties": {
+    "attachments": {
+      "type": "array"
+    },
+    "direction": {
+      "description": "inbound or outbound.",
+      "type": "string"
+    },
+    "from": {
+      "type": "string"
+    },
+    "id": {
+      "type": "string"
+    },
+    "role": {
+      "description": "user (inbound) or assistant (outbound).",
+      "type": "string"
+    },
+    "subject": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "text": {
+      "description": "Readable text, no quoted history.",
+      "type": "string"
+    },
+    "timestamp": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "to": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
  10. Changed4 schema fields changed
    • changedInput schema / properties / full / description
      Previous value: -"Set true for the stored record, with links, quoted history and message ids; the default is a compact view for reading."New value: +"Return the stored record, with links, quoted history and message ids, instead of the compact view for reading."
    • changedOutput schema / properties / data / properties / data / properties / messages / description
      Previous value: -"Oldest first."New value: +"Oldest first: role, direction, from, to, text."
    • addedOutput schema / properties / data / properties / data / properties / subject / description
      Added value: +"Thread subject."
    • addedOutput schema / properties / data / properties / data / properties / thread_id / description
      Added value: +"Thread id."
  11. Changed11 schema fields changed
    • changedInput schema / properties / full / description
      Previous value: -"Set true for the record as stored. By default the result is a compact view for reading, which leaves out link targets, the quoted history each reply repeats and per-turn message ids and classification."New value: +"Set true for the stored record, with links, quoted history and message ids; the default is a compact view for reading."
    • changedInput schema / properties / id / description
      Previous value: -"ID of any inbound email in the conversation."New value: +"Any inbound email in the thread, by its id from listEmails or searchEmails."
    • addedOutput schema / description
      Added value: +"The whole thread."
    • addedOutput schema / properties / data / description
      Added value: +"API body."
    • removedOutput schema / properties / data / properties / data / properties / has_more
      Removed value: -{
-  "type": "boolean"
-}
    • addedOutput schema / properties / data / properties / data / properties / message_count / description
      Added value: +"Messages in the thread."
    • addedOutput schema / properties / data / properties / data / properties / quoted_chars_removed / description
      Added value: +"Quoted text left out."
    • changedOutput schema / properties / data / properties / data / properties / truncated / description
      Previous value: -"The message cap was reached."New value: +"Message cap reached."
    • addedOutput schema / properties / data / properties / error / description
      Added value: +"Why refused."
    • addedOutput schema / properties / data / properties / success / description
      Added value: +"Accepted."
    • addedOutput schema / properties / status / description
      Added value: +"HTTP status."
  12. Changed2 schema fields changed
    • addedOutput schema / properties / data / properties / data / properties / messages / description
      Added value: +"Oldest first."
    • addedOutput schema / properties / data / properties / data / properties / truncated / description
      Added value: +"The message cap was reached."
  13. Changed4 schema fields changed
    • removedOutput schema / additionalProperties
      Removed value: -false
    • addedOutput schema / properties / data / properties
      Added value: +{
+  "data": {
+    "properties": {
+      "has_more": {
+        "type": "boolean"
+      },
+      "message_count": {
+        "type": [
+          "number",
+          "string"
+        ]
+      },
+      "messages": {
+        "type": "array"
+      },
+      "quoted_chars_removed": {
+        "type": [
+          "number",
+          "string"
+        ]
+      },
+      "subject": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "thread_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "truncated": {
+        "type": "boolean"
+      }
+    },
+    "type": [
+      "object",
+      "null"
+    ]
+  },
+  "error": {},
+  "success": {
+    "type": "boolean"
+  }
+}
    • addedOutput schema / properties / data / type
      Added value: +[
+  "object",
+  "string",
+  "null"
+]
    • removedOutput schema / properties / statusText
      Removed value: -{
-  "type": "string"
-}
  14. Changed1 schema field changed
    • addedInput schema / properties / full
      Added value: +{
+  "default": false,
+  "description": "Set true for the record as stored. By default the result is a compact view for reading, which leaves out link targets, the quoted history each reply repeats and per-turn message ids and classification.",
+  "type": "boolean"
+}
  15. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already cover read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond them: the direction/role mapping, how link text and quoted history are transformed, what full:true changes, and the truncated/message_count cap indicator. It doesn't spell out failure behavior for an invalid or out-of-thread id, which keeps it short of perfect.

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 purpose and then pivots cleanly into alternatives and result shape. The trailing enumeration of result fields (thread_id, subject, messages, ...) partly duplicates the output schema, so it is slightly longer than strictly necessary.

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?

Covers the full decision path for a two-parameter read tool: what it returns, how normalization differs under full:true, when a different sibling is the right call, and the fresh-thread edge case. An agent could invoke it correctly without consulting anything else.

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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: id may come from any inbound email in the thread, and full:true alters downstream output (quoted_chars_removed becomes 0, message ids appear). It does not describe format or validation constraints beyond what the schema already states.

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?

States a specific verb and resource ('Read a whole conversation with message bodies') plus a use case ('the tool for finding out what was said'), which separates it from getEmail, getSentEmail, and listEmails without requiring the schema to be opened.

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?

Gives explicit routing rules: use getEmail with links:"all" or getSentEmail with full:true for link targets, and listSentEmails plus getSentEmail for threads containing only sent messages. It also explains what id to pass ('any inbound email in the thread') and covers the edge case of a brand-new message.

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

All email toolsInspect
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