Commonpost MCP for Thunderbird

Search Mail

searchMessages

Read-onlyIdempotent

Search message headers across Thunderbird accounts by sender, recipient, subject, date, tags, or keywords; optionally full-text search bodies and group results by sender or thread.

Instructions

Search message headers across accounts (Trash/Junk skipped); for the latest mail with no query, getRecentMessages. Returns { messages, totalMatches, offset, limit, hasMore }; each row has id + folderPath for getMessage/getMessages. For a company use query 'participant:@domain' with groupBy.

Input Schema

Name	Required	Description
`tag`	No	Tag label or key (e.g. 'Important' or '$label1')
`query`	Yes	Words that must all match (subject, from, to, cc, preview). Operators: from:, to:, cc:, subject:, participant: (from/to/cc/bcc; '@domain' = addresses in that domain, commas = any of them: 'participant:@a.com,@b.com'); quote phrases, e.g. 'participant:@acme.com subject:"invoice 42"'. A single leading operator applies to all words ('from:Alice Smith'). Empty string matches all.
`fields`	No	Only these row columns (id, folderPath and option columns always); not with countOnly, groupBy or legacy
`format`	No	'table': messages as { columns, rows }, fewer tokens. 'legacy' (deprecated): the 0.10 output, a plain array of full rows unless offset is passed; not with groupBy
`offset`	No	Rows to skip; use with hasMore
`endDate`	No	ISO 8601 date: on or before; date-only includes the whole day
`groupBy`	No	Collapse matches into one row per sender or conversation: count, unread, first/last date, latestId + latestFolderPath of the newest non-draft message, drafts count
`threadOf`	No	The whole conversation of this message across folders (Sent included), oldest first; a Re: without threading headers joins by subject the earlier message its sender took part in (linkedBy: subject). Reads 10,000 headers at most, else incomplete: true (narrow with folderPath)
`countOnly`	No	Return only { count }
`sortOrder`	No	By date; default desc, asc with threadOf
`startDate`	No	ISO 8601 date: on or after
`folderPath`	No	Folder URI (from listFolders) to search, with subfolders
`maxResults`	No	Rows (or groups) per page
`searchBody`	No	Full-text search of subject, body and attachment names via the Gloda index (slower): words or "quoted phrases", all must match, no operators; terms under 3 characters are ignored; English matches other word forms, other languages only the exact form. IMAP needs offline sync.
`unreadOnly`	No	Only unread
`flaggedOnly`	No	Only flagged/starred
`includeTrash`	No	Also search Trash and Junk
`attachmentName`	No	Only messages with an attachment whose filename contains this (any case); rows list them
`attachmentType`	No	Same for a MIME type or prefix ('application/pdf', 'image/'). Reads local copies, 500 at most; attachmentSearch counts skipped ones
`dedupByMessageId`	No	Collapse copies of one message in several folders into one row with dupLocations
`includeSubfolders`	No	Search subfolders of folderPath

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.19.2Nov 5, 2026

addedInput schema / properties / fields

Added value: +{
+  "description": "Only these row columns (id, folderPath and option columns always); not with countOnly, groupBy or legacy",
+  "items": {
+    "enum": [
+      "date",
+      "author",
+      "recipients",
+      "ccList",
+      "subject",
+      "read",
+      "flagged",
+      "tags",
+      "preview",
+      "dupLocations"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / format / description

Previous value: -"'table': messages as { columns, rows }, fewer tokens. 'legacy' (deprecated, to be removed): the 0.10 output, a plain array of full rows (threadId, folder, whole preview) unless offset is passed, 50 rows by default; not with groupBy"New value: +"'table': messages as { columns, rows }, fewer tokens. 'legacy' (deprecated): the 0.10 output, a plain array of full rows unless offset is passed; not with groupBy"

changedInput schema / properties / searchBody / description

Previous value: -"Full-text search of subject, body and attachment names via the Gloda index (slower). Query: words or \"quoted phrases\", all must match, no operators; terms under 3 characters are ignored; English words match other forms (stemming), other languages only the exact form. IMAP needs offline sync."New value: +"Full-text search of subject, body and attachment names via the Gloda index (slower): words or \"quoted phrases\", all must match, no operators; terms under 3 characters are ignored; English matches other word forms, other languages only the exact form. IMAP needs offline sync."

changedInput schema / properties / threadOf / description

Previous value: -"Return the whole conversation of this message across folders (incl. Sent), oldest first. A Re: message without threading headers joins by subject the earlier message its sender took part in (linkedBy: subject). Reads at most 10,000 headers, else incomplete: true (narrow with folderPath)"New value: +"The whole conversation of this message across folders (Sent included), oldest first; a Re: without threading headers joins by subject the earlier message its sender took part in (linkedBy: subject). Reads 10,000 headers at most, else incomplete: true (narrow with folderPath)"

First observedv0.1.0Nov 5, 2026

TDQS

A4.1/5.0

Behavior4/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 beyond that: the default exclusion of Trash/Junk and the exact response envelope { messages, totalMatches, offset, limit, hasMore } with the per-row id + folderPath needed for follow-up calls, which is not stated in any annotation.

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?

Four compact sentences, front-loaded with purpose, then the alternative, then the return shape, then the follow-up tools and recipe. It is dense with parenthetical shorthand but nothing is redundant; it could be slightly more scannable as a list, but every sentence carries information.

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 21-parameter search tool with no output schema, the description supplies the missing piece — the return envelope and row shape — and routes to getRecentMessages for the common no-query case. Gaps are minor, e.g. pagination via offset/hasMore is only implied by naming hasMore, and pagination size limits live only in the schema.

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 100% with 21 richly documented parameters, so the schema already carries the parameter burden and baseline is 3. The description's only added parameter meaning is the pairing of 'participant:@domain' with groupBy for company-wide searches, which is a useful but modest increment over what the query and groupBy descriptions already say.

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 ('Search message headers across accounts') plus the scope constraint that Trash/Junk are skipped by default. It explicitly names the sibling it is not (getRecentMessages) and explains how the returned rows feed into getMessage/getMessages, so an agent can distinguish it without opening any 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 routing rule: for the latest mail with no query, use getRecentMessages instead. It also supplies a concrete usage recipe ('participant:@domain' with groupBy) and the follow-up path to getMessage/getMessages. It stops short of covering when to prefer query-only search vs the schema's searchBody full-text mode, so it is strong but not fully exhaustive.

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

Search Mail

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools