Skip to main content
Glama
epinethrone

icloud-mcp

by epinethrone
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

mail_get_thread

Read-only

List the messages in the same conversation as a given email, across its folder, INBOX and Sent, oldest first. Use to see the back-and-forth before replying.

Instructions

List the messages in the same conversation as a given message, found in its folder, INBOX and Sent, oldest first, as summaries without bodies.

Use when: you need the back-and-forth around a message before replying or summarising. Not for reading bodies (use mail_get_messages or mail_get_message) or for finding mail by subject (use mail_search_messages). Parameters:

  • folder is where the uid lives: an alias (INBOX, Sent, Drafts, Trash, Junk, Archive; case-insensitive) or a name copied exactly from mail_list_folders. INBOX and Sent are searched whatever you pass.

  • uid is an integer valid only in that folder, from mail_search_messages, mail_list_changes, mail_list_senders (latest_uid), mail_list_awaiting_reply (its Sent folder) or a summary of an earlier thread (use that summary's own folder).

  • uidvalidity comes from the same result as the uid. Passed, a renumbered folder is refused instead of threading the wrong message; omitted, that check is skipped. Only the given folder is checked; INBOX and Sent are read as they are now. Behavior:

  • read-only; reads the message's threading headers, then finds messages whose Message-ID is the thread root or whose References contain it.

  • Messages filed in other folders are not found.

  • Copies in several folders are merged by Message-ID. Returns: {root_message_id, count, messages}.

  • Each summary carries its own folder and uidvalidity, so read bodies with mail_get_messages one folder at a time.

  • A message without threading headers gives root_message_id null, only that message and no count. Errors:

  • 'No message with uid' or 'uids are out of date': search again.

  • 'Could not open the folder' or 'Could not locate the folder' for an alias the account lacks: check mail_list_folders.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
uidYesMessage uid in that folder (from mail_search_messages).
folderYesMail folder, e.g. INBOX, Sent, Archive or a custom name.
uidvalidityNoThe 'uidvalidity' from the result the uid came from: a renumbered folder is then refused, not misread.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": true,
-  "title": "mail_get_threadDictOutput",
-  "type": "object"
-}New value: +null
  2. Changed1 schema field changedv0.12.0
    • changedInput schema / properties / uid / description
      Previous value: -"Message uid in that folder (from mail_search)."New value: +"Message uid in that folder (from mail_search_messages)."
  3. Changed10 schema fields changedv0.7.0
    • changedInput schema / properties / folder / description
      Previous value: -"Mail folder: INBOX, or Sent / Drafts / Trash / Junk / Archive, or a custom folder name."New value: +"Mail folder, e.g. INBOX, Sent, Archive or a custom name."
    • removedInput schema / properties / folder / title
      Removed value: -"Folder"
    • changedInput schema / properties / uid / description
      Previous value: -"Message uid inside that folder, taken from mail_search or mail_get_message results."New value: +"Message uid in that folder (from mail_search)."
    • removedInput schema / properties / uid / title
      Removed value: -"Uid"
    • removedInput schema / properties / uidvalidity / anyOf
      Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]
    • removedInput schema / properties / uidvalidity / default
      Removed value: -null
    • changedInput schema / properties / uidvalidity / description
      Previous value: -"The folder's 'uidvalidity' from the mail_search / mail_get_message result the uid came from. Pass it back: if the folder was renumbered since, the call is refused instead of acting on the wrong message."New value: +"The 'uidvalidity' from the result the uid came from: a renumbered folder is then refused, not misread."
    • removedInput schema / properties / uidvalidity / title
      Removed value: -"Uidvalidity"
    • addedInput schema / properties / uidvalidity / type
      Added value: +"integer"
    • removedInput schema / title
      Removed value: -"mail_get_threadArguments"
  4. Changed1 schema field changedv0.4.0
    • addedInput schema / properties / uidvalidity
      Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The folder's 'uidvalidity' from the mail_search / mail_get_message result the uid came from. Pass it back: if the folder was renumbered since, the call is refused instead of acting on the wrong message.",
+  "title": "Uidvalidity"
+}
  5. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the threading algorithm (root Message-ID or References match), that messages in other folders are not found, that cross-folder copies are merged by Message-ID, the exact return shape, the degenerate case of missing threading headers, and error messages with recovery steps.

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 answer to the core question, then cleanly sectioned under Parameters/Behavior/Returns/Errors, with no filler sentences. It is on the long side and repeats the INBOX-and-Sent rule in both the Parameters and Behavior sections, a small redundancy that keeps it short of a 5.

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?

There is no output schema, yet the description specifies the return object keys and the per-message folder/uidvalidity fields, plus the failure modes. For a read-only threading tool with 3 parameters this is complete enough to call correctly without guessing.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the accepted folder aliases and case-insensitivity, that INBOX and Sent are always searched regardless of the argument, the provenance of a valid uid (five named sources), and precisely what passing or omitting uidvalidity does on a renumbered folder.

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 with scope: 'List the messages in the same conversation as a given message, found in its folder, INBOX and Sent, oldest first, as summaries without bodies.' It also names adjacent siblings (mail_get_messages, mail_get_message, mail_search_messages), so an agent can distinguish it from every other read tool in the list.

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?

Explicit 'Use when' clause gives the triggering scenario ('the back-and-forth around a message before replying or summarising') plus two explicit exclusions with named alternatives for each (body reading, subject search). Nothing is left for the agent to infer.

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

Deploy Server

Other Tools