What can you do with this server?

mailwarden is a native Gmail MCP server providing full mailbox triage for AI assistants, including reliable search, bulk operations, and a unique snooze system. Search & Retrieval * search – Query Gmail using native syntax (e.g. from:foo is:unread); results are paginated and read-state predicates are re-verified against live labels to eliminate false positives. * get_thread – Fetch full thread content: headers, plaintext/HTML bodies, and attachment metadata. * list_labels – View all system and user-defined Gmail labels. Label & Inbox Management * modify_labels – Add or remove labels on a thread. * bulk_modify – Apply label changes to all messages matching a query (batched at 1000/call, with partial-failure reporting). * archive, mark_read, mark_unread – Convenience wrappers for common triage actions. * trash / untrash – Move a thread to Trash or restore it. Snooze (unique feature) * snooze – Archives a thread and applies a dated label (MCP/Snoozed/YYYY-MM-DD) to resurface it in the inbox on a specified date. * list_snoozed – See all snoozed threads and their due dates. * unsnooze – Cancel a snooze and immediately return the thread to the inbox. * sweep_snoozed – Resurface all due snoozed threads; safe to run repeatedly or on a schedule. Attachments * download_attachment – Save attachments to a local path; never overwrites existing files; can be restricted to a safe download directory. Security & Robustness * Read-only mode available; no send capability, no telemetry, no open ports by default. * Correctly decodes RFC 2047 headers and various charsets; API errors handled with exponential backoff retries.

Which integrations are available for this server?

Provides tools for searching, reading, labeling, archiving, trashing, downloading attachments, and snoozing threads in Gmail via the live Gmail API.

How do I use mailwarden?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mailwarden search for recent emails from john@example.com" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

mailwarden

by csitte

Overview Schema Related Servers Score Discussions

TypeScript

Remote

mailwarden

npm license Node Website Smithery

A reliable, native Gmail MCP server — full mailbox triage for AI assistants, with the feature no other Gmail MCP server ships: mailbox-side snooze.

Highlights

Snooze — the only mailbox-side snooze in a Gmail MCP server. Archive a thread now, have it resurface in the inbox on a date. Built on dated labels + a sweep, so it works from any client, is visible in Gmail itself, and survives restarts. (Where another server offers a "snooze", it is a local reminder list — the mail never leaves or re-enters the inbox.)
Search you can trust. Gmail's threads.list — the call any thread search goes through — can answer is:unread from a stale thread-level read state: measured in one real mailbox, 86% of the threads it returned held no unread message at all; in a second mailbox, no drift whatsoever. You cannot tell which mailbox you are in without looking, so search re-verifies every hit against its live labels. Paginated via pageToken/nextPageToken. (the measurements)
Sender authentication, not sender spelling. get_thread reports the SPF/DKIM/DMARC results the receiving server recorded, so "is this really from my bank?" is answered from the message's own headers instead of from how the domain looks. It reads the receiving server's report only — a message can carry forged ones of its own — and says unchecked when nobody checked, because a missing check is not a passing one.
Bulk operations that scale. bulk_modify archives/labels everything matching a query at 1000 messages per API request — with per-chunk partial-success reporting instead of all-or-nothing. The snooze sweep uses the same batch path.
Structured outputs. Every tool declares an outputSchema and returns validated structuredContent alongside fenced JSON text — no parsing guesswork for clients. Failures are structured as well: a code and a retryable flag, so a client can tell "try again later" from "re-authorize" without reading prose.
Small attack surface. No send tools (no exfiltration path for prompt-injected mail), optional read-only mode, no telemetry, no open ports by default, symlink-safe download fencing, injection-fenced output. And no code path that could send: every Gmail request passes an egress checkpoint that refuses messages.send, every draft endpoint, permanent deletion and forwarding settings, whatever a compromised or careless caller asks for. One deliberate exception: unsubscribe / bulk_unsubscribe (manage tier) contact the opt-out endpoint named in a message's own header — the only non-Google host mailwarden ever reaches, and a read-tier deployment makes no outbound request at all. Details under Security & privacy and Unsubscribing.
Correct with real-world mail. RFC 2047 headers decoded (=?UTF-8?B?…?= → readable text), bodies decoded in their declared charset (no mojibake for ISO-8859-1/Shift_JIS mail), 429/5xx retried with exponential backoff.

Related MCP server: Gmail MCP

Why

Connectors that sync or cache your mailbox can lag behind it — and even Gmail's own search index is sometimes loose (see below). mailwarden talks straight to the live Gmail API (no cached snapshot) and re-verifies what the index returns, so what you see is what's actually there. It's a generic Gmail capability layer — keep your own rules/logic in your AI client, not in the server.

search goes one step further than the raw API: Gmail's threads.list index can answer read-state operators from a stale copy of that state, so is:unread returns threads you finished reading weeks ago — in one measured mailbox, the large majority of what came back. Since every hit is fetched live anyway, search re-checks the unambiguous predicates (is:unread/is:read/is:starred/in:inbox/category:…, with negation) against each thread's true labels and drops the index's false positives.

Compared to other Gmail MCP servers

Most Gmail MCP servers cover the same read/label/send surface. Three capabilities are still unique to mailwarden (mailbox-side snooze, search re-verification, sender authentication), and one deliberate omission is a security feature, not a gap. Google's own server is also narrower than it looks: draft-only, and no trash, filters or unsubscribe.

Capability	mailwarden	Google official	taylorwilsdon	a-bonus	klodr
Mailbox-side snooze — archive now, resurface in the inbox on a date/time or preset	✅	—	—	—	—
Search-result re-verification — drops the thread index's false positives against live labels	✅	—	—	—	—
Sender authentication — SPF/DKIM/DMARC as the receiving server recorded them, on every message	✅ first header only, values token-validated	—	—	—	—
Sweep / bulk over a query — one action across every thread a search returns	✅ 1000/req, partial-success	—	⚠️ batch by explicit ids	—	⚠️ batch by explicit ids
Unsubscribe — per-sender overview + RFC 8058 one-click opt-out, no send scope needed	✅	—	⚠️ header shown, no action	—	—
Inbox triage overview — one call that buckets what is waiting	✅ sender/label/age + header signals	—	—	✅ heuristic flags + stats	—
Server-side filters — rules that keep triaging with no assistant in the loop	✅ never forwarding	—	✅	—	✅
No send tools — by design — a prompt-injected mail has no exfiltration path	✅ no compose at all	⚠️ draft-only	❌ sends	❌ sends	❌ sends
Least-privilege tool tiers — OAuth scopes derived from the tools you enable	✅	⚠️ scope split	⚠️ `--read-only` narrows scopes; tiers narrow tools only	—	⚠️ inverse: tools gated by granted scopes
Token encryption at rest	✅ AES-256-GCM, opt-in (`MAILWARDEN_TOKEN_PASSPHRASE`)	n/a (hosted)	⚠️ file mode `0600`; bucket CMEK on GCS	—	—
No vendor cloud — you operate the server	✅	❌ Google-hosted	✅	✅	✅
Structured outputs — every tool declares an `outputSchema`	✅	—	—	—	⚠️ one tool (`download_email`), more planned

Snapshot as of 3 September 2026, when every column was checked again against that day's state of each project — the three repositories by diff against the revision recorded in docs/comparison-sources.json, Google's by re-reading the tool reference; — = not offered / not documented. Columns are the servers a reader is most likely to reach for — Google's first-party one, plus the two largest community servers still under maintenance — and klodr, which comes closest to mailwarden's own least-privilege design. The most installed Gmail server is absent for that reason and not by oversight: GongRzhe/Gmail-MCP-Server is archived, its last commit dating to August 2025, and it still drew 112,163 npm downloads in the month to 29 August 2026. Reach and currency are different questions, and a comparison of what a server does today can only answer the second. Send capability is listed as a security property: mailwarden's lack of it is intentional (see Security & privacy). The encryption row asks who holds the key: mailwarden encrypts the token itself from a passphrase you set — and does nothing without one, which is why the cell says opt-in rather than showing a bare tick; taylorwilsdon relies on file permissions locally and on the storage bucket's own CMEK when hosted on GCS — protection against a stolen file in the first case, against a stolen disk in the second. The last row asks who operates the server, not where it happens to run: self-hosting is common ground here, and every community server on this table offers some remote deployment except klodr (stdio only) — mailwarden via --http, taylorwilsdon over streamable HTTP with OAuth 2.1, a-bonus on Cloud Run. Running one of them on your own host is not a cloud copy; running it on the vendor's is.

The moat isn't any single row — it's snooze + live re-verification together: an actual inbox-workflow layer that acts on the mailbox's current state, not a cached snapshot. Where others have caught up it's noted honestly above: at-rest encryption (taylorwilsdon), scope-driven tool gating (klodr inversely; taylorwilsdon in our direction but not as far — his --read-only really does switch the OAuth flow to the read-only scope map, but the requested set is built per service, not per tool, so a tier narrows which tools register without narrowing what the token may do: --tool-tier core --tools gmail still asks for the full Gmail scopes. Checked in his auth/scopes.py and main.py on 26 August 2026, and corrected there the same day by csitte.at, who verified it against their own clone rather than taking our word for it), a richer per-message triage heuristic (a-bonus), and bulk organize over a mailbox (the hosted mcpemails.com, which has no snooze either). What none of them do is act on a query and check the mailbox's answer before acting on it.

Running it next to a Workspace server

mailwarden is a Gmail server, not a Workspace suite — if you want Calendar, Drive, Docs and Sheets from one place, a broad server like taylorwilsdon/google_workspace_mcp covers ground this one never will, and the two are not mutually exclusive. Adding both is a reasonable setup, and the reason to is the token, not the tool count: a suite server that can send mail holds a credential that can send mail, for every mailbox it is pointed at. Giving Gmail to mailwarden instead means the mail half of your setup has no compose, reply, forward or send tool at all. Where that promise rests differs by tier, and the distinction matters: on read Google enforces it at the token (gmail.readonly, which the send endpoints reject), while on manage it rests on the tool surface — Gmail does accept gmail.modify for sending, so the scope alone is no guarantee. In both cases the egress guard refuses messages.send and every draft endpoint in the server itself, so an injected message in your inbox has no tool to reach for and no endpoint to reach.

Practical shape: point the suite server at the services you want and disable its Gmail tools (--disabled-tools, or a tier that omits them), and run mailwarden alongside for mail. Keep the tier rule in mind — at most one mailbox per client config should carry writing tiers.

Why re-verification matters — a concrete case

Ask an assistant to "archive the unread promotional mail that's already skipped my inbox" and it will reach for the obvious query, category:updates is:unread -in:inbox. A server that trusts Gmail's index now archives threads you had already read — mail you never meant to touch, gone in a bulk action you can't easily reverse.

Measured, not asserted. In one real mailbox (~70,000 messages), category:updates is:unread returned 131 threads through threads.list, and only 17 of them held an unread message — 87% stale. The same query, same mailbox, same minute, asked through messages.list instead: 19 messages, none stale. So this is not "Gmail search is unreliable" — the thread view of read state lags while the per-message view does not, and search goes through threads.list. A second mailbox, measured identically on the same day, drifted not at all.

Method, all three queries, the controls, and what the finding is not (it is not the index dropping the predicate, and not a quirk of exotic operator combinations): Gmail's thread index can answer is:unread from a stale read state — a standalone report, every figure traced to a recorded measurement.

Which is the whole point: a server cannot know which kind of mailbox it is in. Re-verification costs nothing where nothing drifts, and saves you where it does — in the measurement above, every thread search dropped was genuinely read, and it discarded no genuinely unread mail.

Where it is not free: the bulk tools. search re-verifies because it fetches every hit anyway; bulk_modify (and create_filter's applyToExisting sweep) is sized in thousands of messages, where one fetch per hit is a different order of cost. Those act on what the index returns — so they now report unverifiedPredicates, the conditions from your query that were taken on the index's word (+UNREAD, -INBOX, …). Empty means there was nothing to distrust. Non-empty and the result has to be read-state-precise? Resolve the set with search first and act on those thread ids. A dryRun does not close this gap: it re-reads the same index, so it confirms how big the set is, never whether it is right.

A cheaper half-measure, honestly labelled. bulk_modify also takes crossCheck: true, which asks Gmail the same question a second way before writing: every derived predicate is re-run as a label filter (labelIds) rather than as a query operator, and any message the two routes disagree about is left untouched and reported. The cost is one extra list call per predicate — flat, independent of how many messages match — where re-verification costs one fetch per hit. What it buys is bounded and worth stating plainly: a disagreement is real evidence, agreement is none at all, because both routes read the same index and an index can be consistently wrong. So unverifiedPredicates still reports what it always did, cross-check or not, and only search re-checks against the mailbox itself. Whether the two routes ever diverge in practice is unmeasured — node scripts/probe-crosscheck.mjs measures exactly that in your own mailbox, read-only and ids only.

mailwarden fetches every hit live anyway, so search re-checks the unambiguous predicates (is:unread, is:read, in:inbox, category:…, with negation) against each thread's true labels and drops the index's false positives before any tool sees them. The bulk action then runs on exactly the set you asked for. This is the difference between acting on what Gmail indexed and acting on what's actually in the mailbox right now — and it's why snooze/sweep are safe to hand to an assistant: the sweep resurfaces only threads whose snooze is genuinely due, verified against live labels at run time.

See it yourself — no Gmail account needed. From a clone of the repo (the demo is a repo-only verification script, not part of the npm package):

git clone https://github.com/csitte/mailwarden && cd mailwarden
npm install && npm run build
node scripts/demo-reverify.mjs

There is a second script next to it, node scripts/probe-reverify.mjs, which measures the same thing in your mailbox instead of a fake one — read-only, metadata only (no subject, sender or body is fetched), printing counts and label names. It is how the numbers above were produced, and how you can check whether your mailbox drifts at all.

The demo drives the real search() against a fake Gmail API whose index is deliberately stale (returns a read thread for an is:unread query, exactly as Gmail does) and shows mailwarden dropping the false positive. It asserts the outcome, so it exits non-zero if the behavior ever regresses. The same case is locked by unit tests in test/gmail.test.ts ("drops index false positives via live-label re-verify").

Asking again without asking for everything

A recurring check — what came in since I last looked — is the expensive shape for a live server: the obvious way to answer it is to search the whole slice again and compare. what_changed (read tier) answers it from Gmail's own event log instead. Hand it the historyId a previous call or get_profile returned, and it comes back with what arrived, what left, and which labels went on or came off, plus the next id to keep.

This is not a cache, and the distinction is the whole design. The only thing that persists between calls is one number, and it persists in the caller. mailwarden still stores nothing about the mailbox, keeps no mirror and no index, and every call remains live against the Gmail API — the same rule as everywhere else here.

Two properties worth knowing before relying on it. It reports events, not state: a message marked unread and then read appears under both, and both are true — for how the mailbox looks now, ask search. And Gmail keeps roughly a week of history, after which an id is refused; mailwarden turns that refusal into an error rather than an empty result, because nothing changed and I can no longer tell you what changed call for opposite reactions and only one of them is safe to act on.

Judging a sender — what `authentication` answers, and what it doesn't

Every message from get_thread carries an authentication object: the SPF, DKIM and DMARC results the receiving server recorded, plus the domains each check actually validated.

{
  "spf": "pass",   "mailedBy":   "forwarder.example",        // envelope sender SPF checked
  "dkim": "pass",  "signedBy":   "routing.example",           // domain whose key signed it
  "dmarc": "pass", "headerFrom": "authority.example",        // the From domain DMARC evaluated
  "authservId": "mx.google.com",                             // who asserts all of the above
  "returnPath": "srs0=…=authority.example=…@forwarder.example"
}

Read dmarc first. It is the only one of the three that ties a passing check to the From address a human sees. spf: "pass" on its own says an envelope sender was authorised to send — something a lookalike domain gets in minutes.

The three domains do not have to match, and a mismatch is not a finding. The object above is a real message from a public authority, forwarded through a custom domain on a mail-routing service before it reached the mailbox. Every domain differs from the others, and the mail is genuine: forwarding rewrites the envelope sender (mailedBy becomes the forwarder), the forwarder signs with its own key (signedBy), and only headerFrom still names the original sender — which is exactly why DMARC, not SPF, is the check that carries meaning here. Treat the domains as the explanation of a result, not as a test of their own.

What a pass does not mean. That the mail really came from that domain — not that the domain deserves anything. A phisher holds perfect SPF, DKIM and DMARC on the lookalike domain he registered this morning; authentication tells you who sent it, and the answer can be "exactly who it claims to be, and that is the problem".

What unchecked: true means. The message carried no Authentication-Results header at all — nobody looked. It is not a failure, and it is not a pass. The header is written by a server that receives a message, so anything that never arrived from outside — your own sent mail, for instance — should be expected to have none.

Forged reports. A message can carry Authentication-Results headers of its own — an attacker writes whatever he likes into the mail he sends. Only the first such header is read, because each hop prepends its own and the first one is therefore the receiving server's; authservId names who is asserting the result (for Gmail, mx.google.com) and otherReports counts the ones that were not read. Values are validated as tokens rather than passed through, so a field that reads like a verdict cannot carry a sentence. If two results for the same method disagree — a second DKIM signature that failed — the disagreement shows up in alsoReported instead of being swallowed.

Tools

Tool	What it does
`search`	Gmail query syntax → thread summaries (from/subject/date/labels/snippet); read-state/category predicates are re-verified against each hit's live labels; paginated via `pageToken`/`nextPageToken`. Each hit carries `signals` — `newsletter` (List-Id / List-Unsubscribe / Precedence bulk or list), `automated` (Auto-Submitted, auto-reply/suppress headers, no-reply-style senders), `calendar` (text/calendar or .ics part), `replyToMismatch` (Reply-To on another domain than From; a subdomain of the same domain counts as the same) — read off the first message's headers/MIME, no extra call. Spam and trash are excluded unless the query says `in:spam` / `in:trash` — see Looking in spam
`get_thread`	Full thread: headers, plaintext + HTML bodies, attachment metadata. Every message also carries `authentication` — SPF/DKIM/DMARC as the receiving server reported them, plus the domains each check validated (`signedBy`/`mailedBy`/`headerFrom`), who asserts it (`authservId`), the `returnPath`, `alsoReported` for results that contradict each other, `otherReports` for reports that were not read, and `unchecked: true` when the message carried no report at all — see Judging a sender. `full: false` fetches headers and labels only — it then omits `plaintextBody`/`htmlBody`/`attachments` and sets `metadataOnly: true`, rather than reporting them empty for a request that never looked
`list_labels`	All labels (system + user)
`get_profile`	Connected account's address, total message/thread counts and the mailbox's current `historyId` — confirm which mailbox is wired up before acting
`what_changed`	Mailbox events since a `historyId` you hold — arrivals, removals, labels on and off, in one call
`triage_digest`	Structured overview of a mailbox slice for decisions: top senders (each with the signals its threads carry), label and age buckets, unread + attachment counts, and how many threads are newsletters / automated / calendar invites / reply-to mismatches — instead of a raw thread list
`list_unsubscribe`	What opt-out options a thread advertises (`List-Unsubscribe`), plus body links when it advertises none — contacts nobody
`list_subscriptions`	A mailbox slice grouped by sender: thread/unread counts, the date span each was seen over, and each one's opt-out options — one header fetch per sender, contacts nobody. `sendersFound` reports how many senders there were before `topN` truncated the list
`create_label`	Create a user label (idempotent; nested via `Parent/Child`) and return its id; an optional `backgroundColor`/`textColor` pair colours it, including one that already exists
`modify_labels`	Add/remove labels by name or id — an unknown name in `add` is auto-created (archive = remove `INBOX`, read = remove `UNREAD`)
`bulk_modify`	Batch label changes for every message matching a query — 1000 messages per API request, partial success reported per chunk (thread-id list capped at 500, `submittedThreadCount` has the total). Counts say `submitted`, because `messages.batchModify` answers `204` with no body and ignores unknown ids silently; `verify: true` reads the labels back and returns `verified` `{applied, notApplied, unverifiable}` — the only observed outcome on offer. Acts on the raw index, so `unverifiedPredicates` names the conditions it could not vouch for (see below). `dryRun: true` resolves the query and reports the matched threads and the labels it would create, touching nothing
`archive` / `mark_read` / `mark_unread`	Convenience wrappers
`trash` / `untrash`	Move to / restore from Trash
`download_attachment`	Save an attachment to a local path (never overwrites — collisions get a numeric suffix)
`unsubscribe`	One-click opt-out (RFC 8058) using the endpoint from the message's own header — the only tool that contacts a non-Google host (details)
`bulk_unsubscribe`	The same for several threads, sequentially and at most one request per sender (remembered across calls for as long as the server runs, so a retry contacts nobody twice); partial success reported per thread. `dryRun: true` runs the same header reads and dedupe and reports the endpoint each thread `wouldCall` — contacting nobody
`snooze`	Archive now, resurface on/after a date (`YYYY-MM-DD`), a date+time (`2026-06-20 9am`), or a preset (`tomorrow`, `tomorrow 9am`, `weekend`, `next week`, a weekday name, `in N days`, `in N hours`)
`unsnooze`	Cancel a snooze, return to inbox now
`list_snoozed`	All snoozed threads + due dates
`sweep_snoozed`	Resurface threads whose snooze is due (run on demand, via cron, or the daemon); batched, with partial-failure reporting. `dryRun: true` answers "what is due right now?" (`dueLabels`/`dueThreads`) without waking anything
`list_filters`	All Gmail filters (criteria + label actions); surfaces any `forward` address on existing filters for auditing
`create_filter`	Create a server-side auto-triage rule (criteria → label actions only; no forwarding — see below). Optionally `applyToExisting` to also sweep matching mail already in the mailbox
`delete_filter`	Delete a filter by id

All tools declare an outputSchema and return structured content (validated, machine-readable) alongside the same JSON as fenced text — clients never have to parse prose.

A failure is structured too: isError plus a fenced JSON body with a code (not_authorized, needs_reauth, insufficient_scope, forbidden_operation, not_found, rate_limited, upstream_unavailable, network_error, invalid_input, internal_error) and a retryable flag, alongside the sentence a human reads. So "wait and try again" versus "re-run mailwarden --auth" is something a client can decide, not something it has to infer from wording that may be reworded next release. (No structuredContent on errors: that is validated against the tool's outputSchema, which describes a success.)

How snooze works (no Gmail API snooze exists — we build it)

snooze removes INBOX and applies a dated label MCP/Snoozed/<key>, where the key is either YYYY-MM-DD (due all day) or YYYY-MM-DDTHHMM (due at that local minute). The until argument takes an explicit date, a date+time (2026-06-20 9am, …T17:00), or a preset resolved server-side — today, tomorrow, weekend (next Saturday), next week (next Monday), a weekday name (monday–sunday, next occurrence), in N days, or in N hours — and a date preset may carry a trailing time (tomorrow 9am, monday 8:30), so the caller never has to compute the moment itself. sweep_snoozed finds due labels and returns those threads to the inbox (marked unread); a timed snooze wakes at the first sweep on/after its minute, so wake latency equals your sweep interval. Run the sweep:

on demand (sweep_snoozed tool),
via cron: mailwarden --sweep,
or automatically: set MAILWARDEN_AUTO_SWEEP=1 (hourly sweep while the server runs).

Filters (persistent auto-triage rules)

create_filter sets up a Gmail server-side rule: mail matching the criteria automatically gets the given label actions — the mailbox keeps triaging itself with no assistant in the loop.

Criteria: from, to, subject, query (full Gmail search syntax), negatedQuery, hasAttachment, excludeChats, and size + sizeComparison (smaller/larger, given together). At least one is required.
Actions (label only): addLabels / removeLabels, by name or id (an unknown name in addLabels is auto-created, nested via /). Common recipes: skip the inbox → removeLabels: ["INBOX"]; auto-mark-read → removeLabels: ["UNREAD"]; auto-trash → addLabels: ["TRASH"]; star → addLabels: ["STARRED"]; never-spam → removeLabels: ["SPAM"]; file under a label → addLabels: ["Receipts"].
Existing mail: a filter only runs on messages arriving after it's created. Pass applyToExisting: true to also apply the same actions once to mail already in the mailbox — mailwarden builds a Gmail search from the criteria and runs a bulk modify (up to maxMessages, default 1000; same unverified-index caveat as bulk_modify, and the one-off pass excludes Spam/Trash). This requires at least one positive criterion (from/to/subject/query/hasAttachment:true/size): an exclusion-only rule (negatedQuery or hasAttachment:false) is refused for applyToExisting because it would match almost the whole mailbox — create such a filter without the flag. The outcome comes back under applied (the query used, matchedMessages/submittedMessages/submittedThreadCount counts, capped when the match set hit maxMessages, per-chunk failed, and an error string if the whole pass failed); it's null when applyToExisting was not set. The backlog pass does not verify what landed — bulk_modify's verify does; re-run it with the same query when the sweep's outcome has to be certain. The filter is created first, so a partial or failed backlog pass is reported in applied, never raised — the rule still stands.
No forwarding — see Security & privacy.
Requires the gmail.settings.basic scope; re-run --auth once if you authorized an older version. Not available in read-only mode.

Unsubscribing — the one outbound request

list_unsubscribe (read tier) reports what the sender offers, without contacting anyone. It reads the newest message that actually carries a List-Unsubscribe header — a reply threaded onto a newsletter sits at the end and advertises nothing, which would otherwise read as "this list has no opt-out". When a thread advertises no opt-out header at all, list_unsubscribe looks in the message body and reports the unsubscribe links it finds there as bodyCandidates — plenty of senders put the link only in the footer, and answering "no opt-out options" for them is true about the headers and wrong about the mail. Those links are reported, never fetched, they cannot be handed to unsubscribe, and hasUnsubscribe stays false for them, because that flag has always described the headers. The search costs one full thread fetch and happens only in that case. list_subscriptions (read tier) does the same across a whole slice, grouped by sender, so you can see who keeps writing and which of them can actually be left — one header fetch per sender rather than per thread. unsubscribe and bulk_unsubscribe (manage tier) act on it — and that is the only place mailwarden ever talks to a host that isn't Google, so the rules are tight:

There is no URL parameter. The endpoint comes from the message's own header and nowhere else. A URL argument would let a prompt-injected mail turn the tool into an exfiltration channel (mailbox content in a query string); the header cannot carry data the model chose. This is also why a body link is only ever reported: it is a URL the sender wrote into the text, and fetching one would reintroduce exactly the request this rule exists to prevent — by a path that never passes the guard. Another Gmail server, navbuildz/gmail-mcp-server, does fetch them, following redirects, when the header is missing.
Only RFC 8058 one-click is performed — the sender must have opted in via List-Unsubscribe-Post. A plain https: link is meant for a human in a browser and is handed back, not fetched.
mailto: opt-outs are never performed. They would require sending mail, which mailwarden cannot do. The address is reported so you can act on it yourself.
Fixed request, discarded response. The POST body is always List-Unsubscribe=One-Click and is never derived from anything; the response body is cancelled unread. What returns to the model is the status code and the URL actually called — no content from the endpoint, so it cannot answer with instructions. (A 301/302/303 redirect is followed as a GET, i.e. with no body at all.)
One request per sender, sequentially, inside one budget. bulk_unsubscribe takes thread ids (never a query — a query-driven bulk would fire off a request per matched sender before anyone had looked). Threads from a sender whose request already went out are reported with duplicateOf and cost no second request: two threads from one list share an opt-out, and calling it twice only confirms your address twice. A sender is only recorded once a request actually reached an endpoint, so a refusal or a dropped connection still leaves the next thread its own try — and if the skipped thread advertises a different endpoint, the reason says so, since one sender can run several lists. That memory spans calls for as long as the server runs, and unsubscribe shares it: a call that times out is safe to repeat, and asking twice for the same newsletter contacts the sender once. Pass force: true to unsubscribe for a deliberate second attempt — after an endpoint answered 500, say. It is kept in memory only: persisting it would mean a second kind of local state beside the token, which this server deliberately does not keep, so a restart forgets. Capped at 25 threads and 60 seconds per call; whatever the budget doesn't cover comes back as skippedOutOfTime rather than silently undone. None of it can be reversed, which is why all three limits exist.
SSRF guards. https only, default port only, no credentials in the URL, and every hop — including redirects, followed at most 3 times — must resolve exclusively to globally reachable addresses. The check parses each address to its bytes and matches it against the IANA special-purpose registry, so every spelling of the same address gets the same verdict (::1 and 0:0:0:0:0:0:0:1 alike); an address that does not parse is refused. DNS resolution and all hops share one 10-second budget. Not rebinding-proof (fetch resolves again when it connects) — see SECURITY.md; what survives that gap is a blind POST whose response is never read.

Check it against your own mail before you trust it. From a repo clone (repo-only, not in the npm package), after npm run build and mailwarden --auth:

node scripts/probe-unsubscribe.mjs --vet          # category:promotions, 25 threads
node scripts/probe-unsubscribe.mjs "from:substack.com" --max 50 --vet

It prints each real List-Unsubscribe header next to what the parser made of it, and --vet also runs the endpoint through the URL vetting and the address guard — so you see both whether the parser understood the header and whether the guards would have let that opt-out through. Strictly read-only: no request is ever made to a sender, and nothing in the mailbox changes.

What it can't undo: the request tells the sender your address is live. A sender that ignores its own opt-out is beyond any client's reach — pair unsubscribe with create_filter or trash for those. Not offering an automatable option is reported as unsubscribed:false with the alternatives, not as an error. A read-only deployment gets list_unsubscribe and list_subscriptions, and never makes the request at all.

Looking in spam

A query that does not name a place never sees spam or trash. Gmail excludes both from any search that does not say in:spam / in:trash, so from:someone returns nothing for a mail that is sitting in the spam folder — and nothing in the answer says so. Measured against a live mailbox: the same from: query returned 0 hits by default and 1 with spam included.

This matters because of why mail gets misfiled. A spam filter judges a message on its own; it cannot know that you signed up for something a minute ago, requested a password reset, or placed an order — so the confirmation you are waiting for is exactly the kind of mail that lands there. You know what you just did. The filter does not.

So when mail someone expects is missing, ask again with the place named:

search("in:spam newer_than:2d")          # what got filed as spam recently
search("in:spam from:example.com")       # the confirmation that never arrived

A thread returns to the inbox with modify_labels (remove SPAM, add INBOX), and a sender that keeps being misjudged is best fixed for good with a never-spam rule — create_filter with removeLabels: ["SPAM"] (see Filters).

Two things this server deliberately does not do. It does not scan the spam folder and judge what belongs there: measured over one real spam folder, 89% of it carries no mailing-list machinery at all, so "looks unlike bulk mail" flags nearly the whole folder and filters nothing. And it does not act on that judgement by itself — releasing mail from spam is a decision, and the context that makes it obvious ("I just registered there") lives in the conversation, not in the mailbox.

Security & privacy

For the full threat model — trust boundary, per-threat mitigations, explicit non-goals, and how to report a vulnerability — see SECURITY.md. The highlights:

No telemetry. Nothing phones home — no analytics, no crash reporting, no tracking.
No open ports by default. stdio only. The optional --http listener binds to 127.0.0.1 (not the LAN) and refuses to start without a MAILWARDEN_TOKEN bearer token — set MAILWARDEN_ALLOW_NO_TOKEN=1 to override on a trusted, isolated network. On a loopback bind it also validates the Host header (DNS-rebinding defense). For remote hosting, set MAILWARDEN_HOST and front it with TLS.
No send tools — by design. mailwarden cannot compose, reply, or forward. A prompt-injected instruction inside an email has no exfiltration path through this server. create_filter follows the same rule: it can label, archive, trash, star or mark mail, but never creates a forwarding filter (which would be an exfiltration path). list_filters still surfaces any forwarding filter already on the account, so you can spot one. This holds because no such tool exists and none can be registered at runtime; for the stronger variant, where Google refuses to send rather than mailwarden declining to, see Read-only mode below.
One outbound host, no model-chosen URL. The unsubscribe tool is the only code path that contacts a non-Google host. Its endpoint is read from the message's List-Unsubscribe header — never from a tool argument — the request body is fixed and the response body is discarded, so it cannot become a data channel. https/default-port only, redirects re-validated, and any hop resolving to a private, loopback, link-local or metadata address is refused. See Unsubscribing.
Tool tiers (progressive disclosure + least scope). MAILWARDEN_TOOLS advertises only the tiers you name — read (the read tools), manage (mailbox mutations, snooze, downloads), filters (server-side filter CRUD, the only tier whose tools need gmail.settings.basic). Default is all three; e.g. read,manage gives a full triage surface without filter management. The OAuth scopes requested at --auth are derived from the enabled tiers — a read deployment asks only for gmail.readonly, and gmail.settings.basic is requested only when the filters tier is on. And the filter tools are hidden automatically when the stored token doesn't carry gmail.settings.basic (e.g. a token authorized before you enabled the tier) — re-run --auth to grant it. Older tokens without a recorded scope are advertised as before, with the runtime insufficient-scope message as the fallback.
Read-only mode. Set MAILWARDEN_READONLY=1 (shorthand for MAILWARDEN_TOOLS=read) and only the read tools (search, get_thread, list_labels, list_snoozed, get_profile, what_changed, triage_digest, list_unsubscribe, list_subscriptions) are registered — nothing that can change the mailbox or write files is even advertised to clients (the filter tools, which need the broader gmail.settings.basic scope, are excluded too). Recommended for shared/HTTP deployments that only triage. It is also the only tier whose no-send property Google enforces: it holds a gmail.readonly token, which Gmail's send endpoints reject outright. manage needs gmail.modify, and Gmail does accept that scope for sending — mailwarden simply exposes no tool that would. So a read deployment could not send even if this binary were replaced; a manage one cannot send because there is nothing to call. (There is no send-free write scope to switch to — see SECURITY.md, threat 1.)
Egress guard. "Nothing to call" is no longer only a statement about the tool list. Every authenticated Gmail request passes one checkpoint that allows exactly the endpoints mailwarden uses and refuses the rest — with messages.send, drafts.*, messages.import/insert, permanent deletion and every non-filter settings endpoint named in a deny list checked first, so a later edit to the allowlist cannot reopen them by accident — including through the /upload/gmail/v1/... route googleapis takes when a method is handed media. A request whose host was rewritten (GOOGLE_CLOUD_UNIVERSE_DOMAIN, a rootUrl option) is refused before the token leaves the process. Every method in Gmail's discovery document is tested against the guard. It guards this server, not the token: a stolen gmail.modify token can still send from elsewhere.
Fenced downloads. With MAILWARDEN_DOWNLOAD_DIR set, attachment writes are confined to that directory (realpath-canonicalized, symlink-aware) and never overwrite an existing file. Without it there is nothing to resolve the client-supplied path against, so download_attachment can write anywhere this process can — which matters for --http, where the client is remote. Starting --http without the fence therefore prints a warning naming the exposure (it stays a warning, not a refusal: unlike a missing bearer token this needs an authorized client, and existing deployments depend on the current behaviour). A read-tier deployment is silent — it never registers the tool.
Untrusted-content fencing. Every tool result is wrapped in <untrusted-tool-output> markers and stripped of invisible/BiDi-override characters, so clients can tell quoted mail content from instructions. The strip also covers Unicode tag characters and the variation selectors supplement (invisible ASCII smuggling), and it applies to structuredContent as well as the text copy — a client reading the machine-readable half gets the same sanitized content.
Live API, no copy. No mailbox mirror or search index is stored anywhere. The only local state is your OAuth token in ~/.mailwarden/.
Optional token encryption at rest. token.json holds a refresh token; on disk it is protected only by mode 0o600 (a no-op on Windows). Set MAILWARDEN_TOKEN_PASSPHRASE to a passphrase and the token is stored AES-256-GCM-encrypted (scrypt-derived key), so a copy of the file — a backup, a synced folder, another machine — is useless without the passphrase. Re-run mailwarden --auth once after setting it to encrypt the existing token. Note the boundary: this defends against file theft, not against malware running as your user (which can read the passphrase from the environment too).

Quick start

claude mcp add mailwarden -- npx -y mailwarden

That's the whole install — npx fetches and runs the published package, no clone or build step. You only need Google OAuth credentials once (below).

Setup

First time setting up a Google OAuth app? Follow the step-by-step setup guide — it walks through the Google Cloud Console with exact click paths, explains the "unverified app" screen, and covers the trap that makes tokens die after 7 days. The short version:

Google Cloud: create a project → enable the Gmail API → configure the OAuth consent screen and publish it to Production (in Testing status, Google expires refresh tokens after 7 days) → create an OAuth client ID of type Desktop app → download it as credentials.json.
Put credentials.json in ~/.mailwarden/ (or set MAILWARDEN_CREDENTIALS=/path/to/credentials.json).
Authorize once — opens a browser, stores a refresh token in ~/.mailwarden/token.json:
```
npx -y mailwarden --auth
```
Scopes requested: gmail.modify (read + label/archive/trash) and gmail.settings.basic (filter management only). If you authorized a version before filters existed, re-run --auth once to grant the added scope. To hold a token that Gmail itself refuses to send with, authorize with MAILWARDEN_TOOLS=read — see Read-only mode above.
Verify the setup any time with the built-in doctor:
```
npx -y mailwarden --check
```
It checks credentials.json, whether a token exists (and if it's encrypted), whether the granted scopes cover your enabled tiers, and makes one live Gmail call to prove the token still works — printing a concrete fix for anything that's wrong, and exiting non-zero if so (handy in CI/health checks). Diagnoses the common traps: no/wrong credentials file, never authorized, an encrypted token with no MAILWARDEN_TOKEN_PASSPHRASE, a missing scope, or the 7-day "Testing"-consent token expiry.

Connect

Claude Code (local stdio):

claude mcp add mailwarden -- npx -y mailwarden

Claude Code plugin — the same server plus two skills: /mailwarden:setup walks you through the OAuth setup and diagnoses a broken one, and /mailwarden:triage carries the operating rules an assistant needs while working a mailbox — above all that search re-verifies and bulk_modify does not, so a non-empty unverifiedPredicates means resolving the set with search before acting on it. That rule protects the user only if the assistant follows it, and a tool description is read once per call while a skill is read before the plan. The repo root is the plugin (.claude-plugin/plugin.json), so from a clone:

claude --plugin-dir /path/to/mailwarden

It is submitted to Anthropic's community marketplace; once listed, /plugin marketplace add anthropics/claude-plugins-community then /plugin install mailwarden@claude-community does the same without a clone. The plugin runs the full tool surface — for a narrower tier (MAILWARDEN_TOOLS=read) or a second account, use claude mcp add with the env you want instead (see Config and Multiple accounts).

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "mailwarden": { "command": "npx", "args": ["-y", "mailwarden"] }
  }
}

Or install the MCPB bundle (mailwarden-<version>.mcpb, attached to GitHub releases from 0.10.0 on) as a Desktop extension — Settings → Extensions → Install extension… — the same server, self-contained at run time (no npx; Claude Desktop brings the Node runtime), with the tool tiers as a setting. The bundle is built from the packed npm package (same file set as published; npm run mcpb, verified in CI: validated, unpacked and booted) and is the same file set Smithery distributes. The one-time npx -y mailwarden --auth still applies (Node needed once for that) — the bundle reads the same ~/.mailwarden/ token.

Smithery — listed as csitte/mailwarden, which serves that bundle:

npx -y @smithery/cli install csitte/mailwarden --client claude   # local stdio entry in the client's config

Note which of Smithery's two paths you take. The install above writes a plain local server entry: the process, your token and your mail stay on your machine, exactly as with npx. Adding it to Smithery's toolbox instead (smithery mcp add) also runs the bundle locally, but relays the tool traffic through Smithery's gateway so a remote client can reach it — the mailbox content in those responses then passes through a third party. That is a property of the gateway, not of mailwarden; if you want the no-third-party guarantee, use the local install, the npm package, or the .mcpb from the release page.

Remote (Streamable HTTP) — for a VPS / claude.ai custom connector:

# Loopback + token required by default. For real hosting, bind outward and keep the token:
MAILWARDEN_TOKEN=<secret> MAILWARDEN_HOST=0.0.0.0 npx -y mailwarden --http   # :8787/mcp

Then in claude.ai: Settings → Connectors → Add custom connector → your https://your-host/mcp URL. In Claude Code: claude mcp add --transport http mailwarden https://your-host/mcp.

Multiple accounts

One OAuth app (one credentials.json) can authorize several Gmail accounts. Each account keeps its own refresh token in a separate file, selected by MAILWARDEN_ACCOUNT:

mailwarden --auth --account work        # stores token.work.json
mailwarden --auth --account personal    # stores token.personal.json

Run them side by side by registering the server once per account, each with its own MAILWARDEN_ACCOUNT. Every instance carries its own token, its own granted scopes and its own tool surface, and a tool call acts on the account of the entry that carries it and on no other:

{
  "mcpServers": {
    "gmail-work":     { "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "work" } },
    "gmail-personal": { "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "personal" } }
  }
}

Account names are case-insensitive — they become filenames, so Work and work would be the same file on Windows/macOS. mailwarden lower-cases them (--account Work → token.work.json) so a name always maps to exactly one mailbox.

Which file --auth writes depends only on --account / MAILWARDEN_ACCOUNT — never on the account you pick in the browser. Authorizing a second mailbox without --account would therefore aim straight at the first one's token file, so --auth checks first and refuses rather than replacing another mailbox's token; --force overrides it deliberately. The two knobs are not interchangeable: MAILWARDEN_ACCOUNT is the one for several mailboxes out of one config directory (it picks token.<name>.json), while MAILWARDEN_DIR moves the whole directory — useful to keep setups apart entirely, but it does not give you a second account inside one. npm run auth from a repo clone passes neither, i.e. it always serves the default account.

mailwarden --check shows the active account and lists the others it finds. With no MAILWARDEN_ACCOUNT set, everything uses the default token.json exactly as before — this is fully backward compatible.

More than two accounts

Two entries are the easy case. Past that, two properties of this design start to matter.

Each instance brings its own tools. The tier split is 8 read + 14 manage + 3 filters, so a full instance advertises 25 tools and four of them advertise 100. Clients that search their tool surface on demand absorb that; clients that hold every definition in context do not.

Several accounts in one client share one model context. The account boundary binds a call to one mailbox — it does not stop text read from one mailbox from prompting a call against another, because all of those tool surfaces are in front of the same model. That is a limit of the boundary, not a defect in it; see threat 8 in SECURITY.md.

One move answers both: give exactly one mailbox write tools and leave the rest on read.

{
  "mcpServers": {
    "gmail-main":   { "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "main" } },
    "gmail-work":   { "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "work",   "MAILWARDEN_TOOLS": "read" } },
    "gmail-club":   { "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "club",   "MAILWARDEN_TOOLS": "read" } },
    "gmail-archive":{ "command": "npx", "args": ["-y", "mailwarden"], "env": { "MAILWARDEN_ACCOUNT": "archive","MAILWARDEN_TOOLS": "read" } }
  }
}

Three things follow at once: the read entries only ever ask for gmail.readonly, the one scope in which no-send is enforced by Google rather than by mailwarden's tool surface; the four instances add up to 49 tools rather than 100; and an instruction injected into any of them finds no write tool for another mailbox to reach for. When one of the read-only mailboxes does need cleaning up, hand that entry manage for as long as the work takes instead of permanently.

Separate clients — or separate sessions — remove the shared context entirely, at the price of never having two mailboxes in view at once. Worth it when several mailboxes genuinely need write tools; otherwise the tier split is the cheaper boundary.

No tool reads across mailboxes. search, triage_digest and list_subscriptions each serve the one account their instance was configured with, so a question like "which newsletter writes to all four" is four calls whose answers the caller combines. In a setup this size it is worth calling get_profile before the first action that changes anything — it names the mailbox actually on the other end.

From source

git clone https://github.com/csitte/mailwarden && cd mailwarden
npm install && npm run build
node dist/index.js --auth

A clone deliberately arrives without a CLAUDE.md: the working instructions for this repository are an internal document and are not tracked here. Nothing in the build, the tests or npm run smoke needs them. The rules a contributor — or a coding agent — actually has to know are in CONTRIBUTING.md (design rules that are not up for grabs, the build/test loop) and SECURITY.md (the threat model those rules come from).

Config (env)

Var	Meaning
`MAILWARDEN_DIR`	config dir (default `~/.mailwarden`)
`MAILWARDEN_CREDENTIALS`	path to `credentials.json`
`MAILWARDEN_ACCOUNT`	select a named account (its token is `token.<name>.json`; names are lower-cased); unset = the default `token.json`. See Multiple accounts
`MAILWARDEN_TOKEN_PASSPHRASE`	passphrase → encrypt `token.json` at rest (AES-256-GCM); re-run `--auth` after setting
`MAILWARDEN_AUTO_SWEEP`	`1` → snooze sweep at startup + hourly while running (writes labels — needs the `manage`/`gmail.modify` scope; a `read`-only grant can't sweep)
`MAILWARDEN_DOWNLOAD_DIR`	restrict `download_attachment` to this directory. Unset, the client picks any path this process can write to — `--http` warns at startup unless the `manage` tier is off
`MAILWARDEN_READONLY`	`1` → register only the read tools (search/get_thread/list_labels/list_snoozed/get_profile/triage_digest/list_unsubscribe/list_subscriptions). Shorthand for `MAILWARDEN_TOOLS=read`
`MAILWARDEN_TOOLS`	comma-separated tool tiers to advertise: `read`, `manage`, `filters` (default: all). Also derives the OAuth scopes requested at `--auth`. E.g. `read,manage` drops the filter tools and their `gmail.settings.basic` scope
`MAILWARDEN_DEBUG`	`1` → print full errors with stack traces instead of a one-line message (for bug reports)
`PORT`	HTTP port (default 8787)
`MAILWARDEN_HOST`	HTTP bind address (default `127.0.0.1`; set e.g. `0.0.0.0` for remote hosting)
`MAILWARDEN_TOKEN`	bearer token for the HTTP endpoint — required for `--http` unless overridden
`MAILWARDEN_ALLOW_NO_TOKEN`	`1` → allow `--http` without a token (trusted/isolated networks only)
`MAILWARDEN_ALLOWED_HOSTS`	extra comma-separated `host:port` values accepted by the loopback `Host` allowlist

Status

Working and used in daily mailbox automation. Core Gmail tools + snooze implemented against googleapis, covered by a vitest suite (1192 tests — npm run coverage). Current version: see the npm badge above, the changelog, or releases. PRs welcome — CONTRIBUTING.md covers the build/test loop and the design rules that are not up for grabs.

License

MIT © C.Sitte Softwaretechnik

Available Tools

26 tools

archiveA

Idempotent

Archive a thread (remove it from the inbox). USE WHEN: inbox triage — the thread is handled and should leave the inbox. DO NOT USE: to delete (use trash) or to defer to a date (use snooze). SIDE EFFECTS: thread leaves the inbox; reversible via modify_labels add INBOX.

ParametersJSON Schema

Name	Required	Description	Default
`threadId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

Discloses side effect 'thread leaves the inbox' and reversibility via 'modify_labels add INBOX', adding value beyond annotations (idempotentHint=true, destructiveHint=false). No contradiction.

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?

Concise, front-loaded with action, then usage, then side effects. Every sentence contributes meaning with no waste.

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 purpose, usage guidelines, side effects, and reversibility; output schema exists so return values need not be explained. Complete for a simple tool.

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?

Only one parameter (threadId) with 0% schema coverage, but the description does not elaborate on it beyond the schema; the parameter is self-explanatory, so minimal added value.

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?

Clearly states 'Archive a thread (remove it from the inbox)' with specific verb and resource, and distinguishes from siblings 'trash' and 'snooze' by naming them.

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?

Explicitly provides when-to-use ('inbox triage') and when-not-to-use ('to delete use trash, to defer use snooze'), with alternatives named.

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

bulk_modifyA

DestructiveIdempotent

Bulk-apply label changes to every message matching a Gmail query, batched at 1000 messages per API request. Labels may be given by name or by id: an unknown name in add is created automatically (use '/' for nested labels), an unknown name in remove is ignored. Returns matched/submitted counts, matched and submitted thread IDs (both lists capped at 500 — matchedThreadCount/submittedThreadCount hold the true totals), and per-chunk failures (partial success is reported, not hidden). IMPORTANT: submittedMessages is how many ids were handed to the API, NOT how many messages changed — messages.batchModify answers 204 with no body and ignores ids it does not recognise without a word, so an accepted request is not a performed one. Set verify:true to read the labels back afterwards and get verified {applied, notApplied[], unverifiable[]} — the only field here that reports an observed outcome. It costs one extra read per affected thread, so it is off by default; use it when a wrong 'done' would be acted on (trashing, or anything the user is told completed). If more messages match than maxMessages, only the first maxMessages are processed and 'capped' is true — raise maxMessages or re-run to finish the rest. NOTE: the query hits Gmail's search index as-is, WITHOUT the live re-verification search performs. The staleness that makes search re-verify was measured on threads.list (132 threads returned, 114 carrying no unread message at all); the same query through the message index this tool uses returned 19 hits, none stale — same mailbox, same minute. So the known drift does not reach this path, but that is one measurement, not a guarantee: unverifiedPredicates in the result names the conditions taken on the index's word, and when the outcome must be read-state-precise, resolve the set with search (which verifies against live labels) and act on those thread ids instead. Set crossCheck:true to ask Gmail the same question a second way before writing: each derived predicate is re-run as a label filter (labelIds) instead of a query operator, and any message the two routes disagree about is left untouched and listed in crossChecked.dropped. It costs one extra list per predicate — flat, not per message — so unlike verify it stays cheap on a large sweep. Read it as a contradiction detector: a disagreement is real, agreement proves nothing, because both routes read the same index. unverifiedPredicates therefore stays as it is even when this runs. A capped match set is not cross-checked at all (crossChecked.capped), since a message missing from a page is not a message missing the label. Set dryRun:true to rehearse: the same query resolution, matched counts/threads and the labels that would be created — and no message or label is touched. A dry run reads the SAME unverified index, so it confirms the size of the set, never its correctness. USE WHEN: mass operations — 'archive all newsletters older than 30 days' (query + remove INBOX), bulk labeling, bulk mark-read; dryRun first when the query is broad or the user should see the set before it changes. DO NOT USE: for a single thread (use modify_labels or the dedicated tools), or with neither add nor remove. SIDE EFFECTS: modifies up to maxMessages messages in one call (none with dryRun); label changes are reversible by the inverse call.

ParametersJSON Schema

Name	Required	Description	Default
`add`	No
`query`	Yes
`dryRun`	No
`remove`	No
`verify`	No
`crossCheck`	No
`maxMessages`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`capped`	Yes
`dryRun`	Yes
`failed`	Yes
`verified`	No
`crossChecked`	No
`labelsToCreate`	No
`matchedThreads`	Yes
`matchedMessages`	Yes
`submittedThreads`	Yes
`submittedMessages`	Yes
`matchedThreadCount`	Yes
`submittedThreadCount`	Yes
`unverifiedPredicates`	Yes

TDQS

A5/5.0

Behavior5/5

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

The description goes far beyond the annotations by disclosing partial success reporting, the 204-with-no-body caveat of messages.batchModify, the difference between submitted and applied changes, verification costs, index staleness measurements, and the exact meaning of verified and crossChecked results. The destructiveHint and idempotentHint annotations are consistent with the described reversible but mutating behavior.

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?

Though long, the description is information-dense with no filler; every sentence addresses a real operational concern for a high-risk bulk mutation tool. It is structured with clear sections (IMPORTANT, USE WHEN, DO NOT USE, SIDE EFFECTS) that make the content scannable, and the core purpose is front-loaded.

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?

Given 7 parameters, bulk effects, subtle Gmail API behavior, and a rich output schema, the description is exceptionally complete: it covers result fields, capping behavior, failure reporting, verification options, costs, index staleness, alternatives, and side effects. An agent has enough context to decide whether to call it, set flags appropriately, and interpret results correctly.

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 description coverage is 0%, so the description fully compensates by explaining every parameter: query, add/remove label creation and unknown-name handling, maxMessages capping, dryRun rehearsal behavior, verify's read-back semantics, and crossCheck's second query route. It adds meaning far beyond the bare schema types and defaults.

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?

The description opens with a specific verb and resource: 'Bulk-apply label changes to every message matching a Gmail query, batched at 1000 messages per API request.' It clearly differentiates from sibling tools in DO NOT USE, naming modify_labels and dedicated single-thread tools, so an agent can select it correctly.

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?

The USE WHEN section explicitly lists the intended scenarios ('mass operations — archive all newsletters older than 30 days, bulk labeling, bulk mark-read') and advises dryRun first for broad queries. The DO NOT USE section gives concrete exclusions and alternatives, including not using it for a single thread and requiring at least one of add or remove.

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

bulk_unsubscribeA

Idempotent

Unsubscribe from several mailing lists in one call, one thread id per list. Threads are processed SEQUENTIALLY, and at most ONE request is made per sender — a second thread from a sender whose request already went out is reported with duplicateOf and no request (and says so when it advertises a DIFFERENT endpoint, i.e. is probably a separate list from the same sender). The whole call shares a 60-second budget; threads left over when it runs out come back with skippedOutOfTime and a reason, so re-running with the remaining ids finishes the job. Like unsubscribe, there is no URL parameter: every endpoint comes from that thread's own List-Unsubscribe header. Only RFC 8058 one-click senders are contacted; the rest come back with their alternatives in options. Partial success is reported, never hidden: a thread that cannot be read or whose endpoint fails becomes an entry with a reason, and the remaining threads still run. Set dryRun:true to rehearse: same header reads, same per-sender dedupe (as a real run with every request succeeding), and each entry a real run would contact reports the endpoint it wouldCall; refusals and duplicates carry none — and nobody is contacted. USE WHEN: clearing out several newsletters at once — pair with list_subscriptions, which gives you the sender rows and their newestThreadId; dryRun first to show the user which senders would be contacted. DO NOT USE: for one thread (use unsubscribe), or to find candidates (use list_subscriptions — it contacts nobody). SIDE EFFECTS: up to one outbound HTTPS request per DISTINCT sender (plus up to 3 redirects each) — the only non-Google hosts mailwarden ever contacts (none with dryRun). Each confirms to that sender that the address is live, and none of it can be undone. The mailbox itself is not changed.

ParametersJSON Schema

Name	Required	Description	Default
`dryRun`	No
`threadIds`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`dryRun`	Yes
`results`	Yes
`requests`	Yes
`attempted`	Yes
`requested`	Yes
`unsubscribed`	Yes
`skippedOutOfTime`	Yes
`skippedDuplicates`	Yes

TDQS

A4.8/5.0

Behavior5/5

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

Discloses sequential processing, per-sender deduplication, a 60-second time budget, dryRun behavior, external HTTP requests (with redirects), confirmation of address liveness, and irreversibility. These details go well beyond the annotations (readOnlyHint:false, openWorldHint:true, idempotentHint:true) and provide necessary caveats about side effects. No contradiction with annotations is apparent.

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?

The description is lengthy but well-structured with bolded section headers (USE WHEN, DO NOT USE, SIDE EFFECTS). It front-loads the core purpose and packs each sentence with meaningful details. Slightly verbose, but each part contributes to understanding a complex tool.

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 all major edge cases: duplicateOf, skippedOutOfTime, options for non-RFC 8058, partial failure handling, dryRun output, and side effects. Given the complexity and the existence of an output schema, the description provides comprehensive operational knowledge for correct usage.

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?

Although schema coverage is 0%, the description explains the meaning of threadIds ('one thread id per list') and dryRun ('rehearse' with no contact). It also clarifies that no URL parameter is used and that endpoint comes from List-Unsubscribe headers. This adds useful context beyond the raw schema, though it could be more explicit about max 25 items and preconditions.

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?

The description clearly states the action (unsubscribe) and the scope (several mailing lists in one call, one thread id per list). It distinguishes itself from the sibling tool 'unsubscribe' by explicitly noting it is for multiple threads, and the phrase 'one thread id per list' adds specificity.

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?

Provides explicit 'USE WHEN' and 'DO NOT USE' sections, naming alternative tools (list_subscriptions for candidate discovery, unsubscribe for single thread) and pairing recommendations with list_subscriptions. This gives agents clear decision criteria.

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

create_filterA

Destructive

Create a Gmail filter: matching incoming mail automatically gets the given label actions. Give at least one criterion and at least one action. Actions are label add/remove only (labels by name or id; an unknown name in addLabels is auto-created). Common recipes: skip the inbox → removeLabels ['INBOX']; auto-mark-read → removeLabels ['UNREAD']; auto-trash → addLabels ['TRASH']; star → addLabels ['STARRED']; file under a label → addLabels ['Receipts']. A filter only affects mail arriving AFTER it's created; set applyToExisting:true to ALSO apply the same actions once to mail already in the mailbox (builds a Gmail search from the criteria and runs a bulk modify — same unverified-index caveat as bulk_modify — the sweep acts on what the index returns, which can be badly stale on read state; up to maxMessages, default 1000). USE WHEN: setting up a persistent auto-triage rule (e.g. 'always archive + label newsletters from x'), optionally cleaning up the existing backlog too. NOTE: forwarding filters are intentionally not supported — mailwarden creates no send/exfiltration path. SIDE EFFECTS: adds a server-side rule affecting future mail (reversible via delete_filter); with applyToExisting also modifies existing messages. Requires gmail.settings.basic.

ParametersJSON Schema

Name	Required	Description	Default
`to`	No
`from`	No
`size`	No
`query`	No
`subject`	No
`addLabels`	No
`maxMessages`	No
`excludeChats`	No
`negatedQuery`	No
`removeLabels`	No
`hasAttachment`	No
`sizeComparison`	No
`applyToExisting`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`applied`	Yes
`forward`	No
`criteria`	Yes
`addLabelIds`	Yes
`removeLabelIds`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

The description goes well beyond the destructiveHint annotation by disclosing that a server-side rule is created, affecting future mail, and that it is reversible via delete_filter. It also explains the applyToExisting behavior, the unverified-index caveat, the default maxMessages, label auto-creation, and the required permission gmail.settings.basic.

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?

The description is dense but well-organized with clear sections: common recipes, USE WHEN, NOTE, and SIDE EFFECTS. Every sentence adds actionable information, and the most important usage constraints are front-loaded.

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?

For a tool with 13 optional parameters and significant side effects, the description covers the core contract: at least one criterion and one action, action types, persistence behavior, backlog modification, caveats, permissions, and reversibility. The output schema exists, so return-value documentation is not needed here.

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 0% schema description coverage, the description adds crucial meaning for addLabels/removeLabels, including label auto-creation and the special label shortcuts like INBOX, UNREAD, TRASH, and STARRED. It also clarifies applyToExisting and maxMessages semantics, though individual criteria parameters like negatedQuery, excludeChats, and sizeComparison are left to their self-explanatory names.

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?

The description opens with a specific verb and resource: 'Create a Gmail filter' and then explains exactly what it does with matching incoming mail. It distinguishes this tool from siblings by focusing on persistent filter creation, labeling actions, and the applyToExisting backlog sweep.

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?

The 'USE WHEN' section explicitly identifies the intended scenario: setting up persistent auto-triage rules and optionally cleaning up existing mail. It also notes forwarding filters are unsupported, but it does not name an alternative tool for one-off bulk actions, so it stops just short of full when-not/alternative guidance.

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

create_labelA

Idempotent

Create a user label and return its id. Idempotent: if the name already exists (case-insensitive), its existing id is returned and nothing is created. Nested labels: separate levels with '/' (e.g. 'Clients/Acme') — each missing parent level is created too. Colour: pass backgroundColor AND textColor together as '#rrggbb' (Gmail rejects one without the other, and accepts only colours from its own palette). Giving a colour for a label that already exists RECOLOURS it — that is how an existing label, such as the snooze label, gets a colour. Gmail colours only labels you created yourself; system labels like INBOX or CATEGORY_UPDATES refuse one. USE WHEN: you want a label's id up front, to pre-create a label without applying it to anything, or to make an existing label visible at a glance in Gmail. DO NOT USE: just to file mail under a new label — modify_labels/bulk_modify already auto-create an unknown name passed in add. SIDE EFFECTS: creates the label if missing, and sets its colour when one is given; no mail is changed.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`textColor`	No
`backgroundColor`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`name`	Yes
`color`	No

TDQS

A5/5.0

Behavior5/5

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

The annotations only declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description goes far beyond this by explaining case-insensitive name matching, nested label creation, recoloring existing labels, system label color restrictions, and the fact that no mail is changed. This is rich behavioral context with no contradiction.

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?

The description is long but every section earns its place: core action, idempotency, nesting, color behavior, usage guidance, and side effects. It is front-loaded with the most important information and uses clear section markers to keep the density navigable.

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?

Given the complexity of label creation in Gmail, the description covers all relevant caveats: idempotency, color pairing, palette restrictions, recoloring, system label refusals, and side effects. Since an output schema exists, the return value need not be further explained. Nothing essential is missing.

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 description coverage is 0%, so the description carries the full burden of explaining parameters. It explains name with nesting syntax, and describes that textColor and backgroundColor must be passed together as '#rrggbb' and must come from Gmail's palette. This is far more than the schema provides.

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?

The description opens with a specific verb and resource: 'Create a user label and return its id.' It also distinguishes itself from modify_labels by explicitly stating that filing mail under a new label should use modify_labels/bulk_modify, which auto-create unknown names.

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?

The description includes explicit USE WHEN and DO NOT USE sections, giving clear conditions for tool selection. It names the exact alternative tools (modify_labels/bulk_modify) and explains when they should be used instead, leaving no ambiguity.

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

delete_filterA

Delete a Gmail filter by id (get ids from list_filters). USE WHEN: removing an auto-triage rule. SIDE EFFECTS: removes the server-side rule; future mail is no longer auto-processed by it. Requires gmail.settings.basic.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	Yes

TDQS

A3.8/5.0

Behavior1/5

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

Annotation Contradiction: The description says 'removes the server-side rule' and the tool is named delete_filter, indicating destructive behavior, yet annotations declare destructiveHint=false. This is a direct contradiction and severely undermines trust in safety-critical metadata.

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?

The description is compact and well-structured, with labeled sections (USE WHEN, SIDE EFFECTS) that immediately convey the core action, when to use it, and consequences. Every sentence contributes valuable information without redundancy.

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 simple single-parameter delete operation, the description covers purpose, usage context, side effects, and required permissions. An output schema exists so return values are not required. It lacks explicit error-handling/idempotency details, but annotations and simplicity compensate.

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 zero schema description coverage, the description adds essential meaning to the 'id' parameter by explaining it is a Gmail filter id obtainable from list_filters. This gives the agent a clear source and purpose, going beyond just the schema's string type.

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?

The description starts with 'Delete a Gmail filter by id', a specific verb and resource, and directly distinguishes itself from sibling tools like create_filter and list_filters by noting how to obtain ids. It clearly states the tool's scope.

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?

The 'USE WHEN: removing an auto-triage rule' provides a clear context. It also instructs the agent to get ids from list_filters, implicitly guiding when to use this tool vs its sibling. However, it does not explicitly state when not to use it or mention alternatives beyond listing filters.

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

download_attachmentA

Download an attachment to a local file path. If MAILWARDEN_DOWNLOAD_DIR is set, destPath is resolved inside (and restricted to) that directory. USE WHEN: the user wants an attachment saved to disk (IDs come from get_thread's attachment metadata). SIDE EFFECTS: writes a local file; never overwrites — an existing file gets a numeric suffix (file-1.pdf). The response's 'saved' field is the path actually used. Mailbox unchanged.

ParametersJSON Schema

Name	Required	Description	Default
`destPath`	Yes
`messageId`	Yes
`attachmentId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`saved`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

Discloses critical behaviors beyond annotations: writes a local file, never overwrites (numeric suffix file-1.pdf), explains the MAILWARDEN_DOWNLOAD_DIR path restriction, confirms mailbox unchanged. The 'saved' field semantics are explained. Slight gap: doesn't mention permission/error behavior for the download operation, but coverage is strong given annotations already signal non-readOnly, non-destructive, non-idempotent.

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?

Four tight sentences, each earning its place: definition, directory restriction, usage trigger, side effects with concrete example, and response field meaning. Zero waste, well front-loaded with the primary action.

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 non-readOnly, non-idempotent write tool with zero param documentation, the description provides strong behavioral disclosure: overwrite policy, path resolution, mailbox unaffected. An output schema exists, so return details needn't be enumerated. Minor gap: no mention of failure modes (unresolvable path, missing attachment) but solid overall.

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 coverage is 0% and there are 3 required parameters with no descriptions. The description does explain destPath semantics well (directory resolution, suffix behavior) and touches on IDs coming from get_thread. However, messageId and attachmentId meanings are only implied via the get_thread reference, not explicitly defined. Description partially compensates but doesn't fully cover all three params.

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?

Clear verb+object: 'Download an attachment to a local file path.' It distinguishes from siblings by noting IDs come from get_thread's attachment metadata, explicitly differentiating from search/read-only tools. Purpose is immediately unambiguous.

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' statement defines the trigger condition (user wants attachment saved to disk) and cites the exact source of input IDs (get_thread's attachment metadata). This gives strong selection guidance among the sibling tools.

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

get_profileA

Read-only

Return the authorized account: email address plus total message/thread counts. USE WHEN: confirming WHICH mailbox is connected before a bulk or filter action, or as a cheap liveness check. DO NOT USE: to enumerate messages — this returns only counts, not a listing (use search). SIDE EFFECTS: none.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`historyId`	Yes
`emailAddress`	Yes
`threadsTotal`	Yes
`messagesTotal`	Yes

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'SIDE EFFECTS: none.' It adds useful behavioral context beyond the annotation by stating the tool returns only counts, not a message listing, and positions it as a liveness check.

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?

The description is compact and well-structured: the core function is first, followed by USE WHEN, DO NOT USE, and SIDE EFFECTS. Every sentence carries actionable information with no redundancy.

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?

For a simple no-parameter, read-only tool with an output schema present, the description provides all necessary context: what it returns, when to use it, when not to use it, and that there are no side effects. Nothing important is missing.

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?

The tool has zero parameters and full schema description coverage, so there are no parameter semantics to document. The description usefully clarifies what the response contains, satisfying the baseline for no-parameter tools.

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?

The description opens with a specific verb and resource ('Return the authorized account') and specifies exactly what is returned: email address plus total message/thread counts. It also explicitly distinguishes itself from message enumeration by pointing to 'search' as the tool for listings.

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?

The description provides explicit USE WHEN guidance (confirming which mailbox is connected, cheap liveness check) and explicit DO NOT USE guidance (enumerating messages), with an alternative named. This gives clear decision criteria for an agent.

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

get_threadA

Read-only

Fetch a thread by ID: headers, plaintext + HTML bodies, and attachment metadata. full defaults to true and should stay true whenever content matters. full: false is a headers-and-labels fetch for when a thread is too large to read or only its metadata is of interest — it does NOT fetch bodies or attachment metadata, and the result then omits plaintextBody, htmlBody and attachments entirely and sets metadataOnly: true. The fields are omitted rather than empty on purpose: an empty attachment list from a request that never looked is indistinguishable from a message that truly has none, and treating it as 'no attachment' has already nearly caused an invoice to be archived as attachment-less. If search reported hasAttachments: true, or the sender matters, use full: true. EVERY MESSAGE CARRIES authentication — SPF/DKIM/DMARC as the RECEIVING server reported them, for answering 'is this mail really from who it says?'. Read dmarc first: it is the only one of the three that ties a passing check to the visible From domain, so spf: pass alone proves nothing about the sender the user sees (a lookalike domain gets that trivially). signedBy/mailedBy/headerFrom name the domains each check actually validated. They do NOT have to match each other or the From address, and a mismatch is not by itself suspicious: a forwarded message legitimately shows the forwarder in mailedBy (the envelope sender is rewritten in transit) and in signedBy (the forwarder signs with its own key), while only headerFrom still names the original sender — which is exactly why dmarc is the result that carries meaning. Read those three as the explanation of a result, not as a test of their own. authservId says WHO asserts all this: a message can carry forged Authentication-Results headers of its own, and only the receiving server's report (for Gmail, mx.google.com) counts; otherReports counts further reports that were NOT read, and alsoReported lists results that disagree with the ones above. unchecked: true means the message carried no report at all — that is 'nobody looked', NOT 'nothing wrong'; unauthenticated does not imply forged, and authenticated does not imply honest (a phisher can hold a passing DMARC on his own lookalike domain). USE WHEN: reading a thread's content after finding it via search. DO NOT USE: with a message ID — this takes thread IDs. SIDE EFFECTS: none (does not mark as read).

ParametersJSON Schema

Name	Required	Description	Default
`full`	No
`threadId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`messages`	Yes
`threadId`	Yes
`metadataOnly`	No

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare `readOnlyHint: true`, and the description reinforces this with 'SIDE EFFECTS: none (does not mark as read).' It goes well beyond annotations by disclosing that `full: false` omits fields entirely and sets `metadataOnly: true`, explaining the rationale for omission rather than empty lists. It also warns about authentication-header forgery and how to interpret `authservId`, which is valuable behavioral context for downstream decisions.

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?

The description is front-loaded and well structured, with the core purpose in the first sentence and clear USE WHEN / DO NOT USE / SIDE EFFECTS sections. It is verbose, especially the detailed authentication-fields discussion, which goes beyond what is strictly needed for tool selection and invocation. Still, the extra detail is purposeful and organized rather than redundant.

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?

Given the output schema exists and the two-parameter input schema is minimal, the description is thorough: it covers both parameters, side effects, use cases, exclusions, and even edge-case semantics like omitted fields and authentication-result interpretation. An agent has everything needed to call this tool correctly and interpret the result safely.

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 description coverage is 0%, so the description carries full parameter-semantics responsibility. It thoroughly explains `full` semantics, including defaults, behavior differences, omitted fields, and when to set it. For `threadId`, it clarifies that this tool expects thread IDs and not message IDs. Both parameters are meaningfully documented beyond the bare schema.

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?

The first sentence states a specific verb and resource: 'Fetch a thread by ID: headers, plaintext + HTML bodies, and attachment metadata.' It also distinguishes this from message-level or search tools with 'DO NOT USE: with a message ID — this takes thread IDs.' The purpose is unmistakable and well differentiated from siblings.

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?

The description gives explicit usage guidance: 'USE WHEN: reading a thread's content after finding it via search' and 'DO NOT USE: with a message ID.' It also provides clear conditions for when to use `full: true` vs `full: false`, including the case where search reported `hasAttachments: true`. This is exactly the kind of actionable selection guidance an agent needs.

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

list_filtersA

Read-only

List all Gmail filters — the server-side rules that auto-apply label actions to incoming mail. Shows each filter's criteria and label actions, and (for auditing) any forward address an existing filter carries. USE WHEN: reviewing existing automation, or to get a filter's id before delete_filter. SIDE EFFECTS: none. Requires the gmail.settings.basic scope — re-run mailwarden --auth if you authorized an earlier version.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`filters`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

The description explicitly declares 'SIDE EFFECTS: none' and adds the required scope ('gmail.settings.basic') with a re-authentication note ('re-run mailwarden --auth'). This goes beyond the readOnlyHint annotation by providing operational auth context and confirming no side effects, which is valuable for an agent deciding to invoke the tool.

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?

The description is concise, structured with clear segments (purpose, output details, usage, side effects/scope), and front-loaded with the core action. Every sentence earns its place without repetition, and the formatting improves readability.

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?

Given zero parameters and an existing output schema, the description provides ample context: it explains what filters are, what information is returned, when to use the tool, that there are no side effects, and what scope is required. This is complete for a simple list tool with no input complexity.

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?

There are zero parameters, so the baseline is 4 per the rubric. The description adds no parameter-specific details but instead clarifies what the tool returns (criteria, label actions, forward addresses), which compensates for the lack of parameters and enriches the agent's understanding of the output.

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?

The description clearly states the action ('List all Gmail filters') and the resource (filters), with a definition of what filters are and what information is shown (criteria, label actions, forward addresses). It distinguishes the tool from siblings like create_filter and delete_filter by focusing on listing and auditing existing filters.

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?

The description provides explicit 'USE WHEN' guidance: reviewing existing automation or getting a filter's id before delete_filter. It gives clear context but does not explicitly name alternative tools for exclusion, so it falls short of the highest calibration example. The intent is clear enough for an agent to select this tool appropriately.

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

list_labelsA

Read-only

List all Gmail labels (system + user). USE WHEN: inspecting the mailbox structure, or to get exact label names/ids — though modify_labels/bulk_modify/create_label all accept a plain label name directly, so a lookup is rarely required. SIDE EFFECTS: none.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`labels`	Yes

TDQS

A4.9/5.0

Behavior5/5

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

Annotations include readOnlyHint=true, and the description adds the explicit 'SIDE EFFECTS: none' statement, reinforcing the safe read-only nature. It also provides behavioral context that the listing includes both system and user labels, which is not in the structured annotations. This adds value beyond the annotations without contradicting them.

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?

The description is extremely concise: two short segments ('List all Gmail labels (system + user)' and 'SIDE EFFECTS: none') plus a focused usage clause. It is front-loaded with the core action, with no wasted words, making it easy to parse quickly.

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?

Given the tool's simplicity (no parameters, read-only, output schema exists), the description covers all necessary context: purpose, usage, side effects, and scope. It explicitly mentions the labels' scope (system + user) and when to use it, making it fully complete for an agent to select and invoke correctly.

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?

The tool has zero parameters, and the schema is empty, so schema description coverage is 100%. With 0 params, the baseline is 4. The description doesn't discuss parameters because none exist, which is appropriate. No additional parameter semantics are needed.

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?

The description clearly states the tool's function: 'List all Gmail labels (system + user).' It uses a specific verb ('List') and resource ('Gmail labels'), and the scope is explicit. This distinguishes it from sibling tools like modify_labels, bulk_modify, and create_label, which perform mutations.

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?

The description includes an explicit 'USE WHEN' clause, specifying appropriate contexts (inspecting mailbox structure, getting exact label names/ids). It also names alternative tools (modify_labels/bulk_modify/create_label) and notes that a lookup is rarely required because they accept plain label names. This is clear guidance on when to use the tool vs. alternatives.

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

list_snoozedA

Read-only

List all snoozed threads with their due dates. SIDE EFFECTS: none.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`snoozed`	Yes

TDQS

A4/5.0

Behavior4/5

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

Explicitly states 'SIDE EFFECTS: none', which complements the readOnlyHint=true annotation and adds clarity beyond the annotation alone.

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?

Two sentences with no fluff. Front-loads the main function and includes side-effect note concisely.

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?

Given no parameters and an existing output schema, the description adequately covers the tool's behavior. Mentions 'due dates' hinting at output content.

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?

No parameters exist, so baseline is 4. The description adds no param info, but none is needed.

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?

The description clearly states the tool lists snoozed threads with due dates, distinguishing it from sibling tools like snooze or trash which perform actions.

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 tool versus alternatives such as search or sweep_snoozed. The description is purely descriptive without usage context.

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

list_subscriptionsA

Read-only

Who keeps writing, how often, and whether you can get off the list — a mailbox slice grouped by SENDER, each row carrying its opt-out options. Contacts nobody: opt-out options come from the List-Unsubscribe header of each sender's newest thread (one metadata fetch per sender, not per thread). optOut is 'one-click' (the unsubscribe tool can perform it), 'link' (a human opens it in a browser), 'mailto' (would need sending, which mailwarden never does), 'none', or 'unknown' when that sender's header fetch failed. oldestDate/newestDate bound what the SAMPLE saw of that sender, not the sender's whole history — a query capped at max reaches back only as far as those threads go, which on a busy mailbox is days. There is deliberately NO precomputed frequency: judge it from threads across that span, with the sampling caveat in view. newestThreadId is what to hand to unsubscribe or bulk_unsubscribe. sendersFound is how many DISTINCT senders the sample held — when it exceeds topN, the list is truncated and raising topN shows more. USE WHEN: 'what am I subscribed to', 'which newsletters flood me', or picking targets before a bulk unsubscribe. DO NOT USE: for a general inbox overview (use triage_digest — it buckets by label and age too), or for one known thread (use list_unsubscribe). SIDE EFFECTS: none.

ParametersJSON Schema

Name	Required	Default
`max`	No
`topN`	No
`query`	No	category:promotions

Output Schema

ParametersJSON Schema

Name	Required	Description
`query`	Yes
`hasMore`	Yes
`sampled`	Yes
`sendersFound`	Yes
`subscriptions`	Yes

TDQS

A4.9/5.0

Behavior5/5

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

The description goes beyond annotations by detailing optOut types ('one-click', 'link', 'mailto', etc.), explaining the sampling caveat (oldestDate/newestDate bound the sample, not full history), noting no precomputed frequency, and specifying side effects as 'none'. This aligns with readOnlyHint=true and provides context not in structured data.

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?

The description is long but every sentence contributes: it front-loads the core purpose, then systematically covers edge cases, use cases, and side effects. The 'USE WHEN' and 'DO NOT USE' paragraphs provide clear structure without waste.

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?

Given the tool's complexity (sender grouping, opt-out scanning, sampling limits), the description thoroughly covers return value semantics, behavioral caveats, and relationships to sibling tools. It even explains output fields like sendersFound and newestThreadId, making it complete despite having an output schema.

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 0% schema description coverage, the description compensates by explaining what each parameter controls: max caps the query scope, topN truncates the list, and query defines the mailbox slice. It doesn't enumerate parameters directly, but the context adds meaningful semantics beyond raw schema.

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?

The description clearly states the tool lists a mailbox slice grouped by SENDER with opt-out options, which directly conveys a specific verb+resource. It also distinguishes from siblings by mentioning alternatives like triage_digest and list_unsubscribe in the use cases.

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' and 'DO NOT USE' sections provide clear guidance: use for subscription understanding or targeting before bulk unsubscribe, avoid for general inbox overview (use triage_digest) or one known thread (use list_unsubscribe). This offers both when and when-not scenarios with named alternatives.

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

list_unsubscribeA

Read-only

Report the opt-out options a thread advertises (List-Unsubscribe / RFC 8058), without contacting anyone. Reads the newest message that carries the header, so a reply threaded onto a newsletter does not hide it. oneClick means the sender supports the automatable one-click opt-out — the unsubscribe tool can perform it. httpsUrls without oneClick are links for a human to open in a browser; mailtos would require sending mail, which mailwarden never does. bodyCandidates appears only when the headers advertise nothing: unsubscribe links found in the message TEXT, which is written by the sender and therefore untrusted. Show them to the user to open; never fetch one, and do not treat them as an opt-out that happened. hasUnsubscribe stays false for them — it describes the headers. USE WHEN: checking whether a newsletter can be unsubscribed from, or showing the user the link to click. SIDE EFFECTS: none — no request is made to the sender.

ParametersJSON Schema

Name	Required	Description	Default
`threadId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`from`	Yes
`mailtos`	Yes
`subject`	Yes
`oneClick`	Yes
`threadId`	Yes
`httpsUrls`	Yes
`messageId`	Yes
`bodyCandidates`	Yes
`hasUnsubscribe`	Yes

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, and the description strongly reinforces this with 'without contacting anyone' and 'SIDE EFFECTS: none — no request is made to the sender.' It also discloses important nuances: it reads the newest message carrying the header, bodyCandidates come from untrusted message text, and they must not be treated as an actual opt-out. This goes well beyond the 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?

The description is long but every major section earns its place: field meanings, safety warnings, use cases, and side effects. It is front-loaded with the core purpose before diving into details. There is minor redundancy between 'without contacting anyone' and 'SIDE EFFECTS: none,' but overall the length is justified by the nuanced output behavior.

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?

The description covers the tool's purpose, when to use it, how it behaves regarding headers and body text, safety constraints, side effects, and relationships to sibling tools. It also explains the special cases of `hasUnsubscribe`, `bodyCandidates`, and untrusted content. Given the output schema exists, no important gap remains for an agent to invoke this tool correctly.

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?

The schema only defines `threadId` as a required string with no description, so the description carries the burden. It adds meaning by explaining that the tool operates on a thread and reads the newest message in that thread, even noting how a reply threaded onto a newsletter is handled. This gives enough context for an agent to understand what `threadId` represents, though no explicit format guidance is provided.

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?

The description opens with a specific verb and resource: 'Report the opt-out options a thread advertises (List-Unsubscribe / RFC 8058), without contacting anyone.' It clarifies this is a read-only inspection tool and distinguishes it from the sibling `unsubscribe` tool by explicitly noting that `unsubscribe` can perform the one-click opt-out.

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?

The description provides an explicit 'USE WHEN' section: 'checking whether a newsletter can be unsubscribed from, or showing the user the link to click.' It also gives alternative routing by pointing to the `unsubscribe` tool for oneClick cases and instructs the agent to never fetch bodyCandidates, establishing clear boundaries for safe use.

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

mark_readA

Idempotent

Mark a thread as read. SIDE EFFECTS: removes UNREAD; reversible via mark_unread.

ParametersJSON Schema

Name	Required	Description	Default
`threadId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	Yes

TDQS

A4.5/5.0

Behavior5/5

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

The description goes beyond annotations by detailing the specific side effect and reversibility, fully disclosing the tool's behavior.

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?

The description is concise with two sentences, front-loading the purpose and listing side effects efficiently.

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?

For a simple tool with one parameter, clear annotations, and an output schema, the description covers all necessary context including side effects and reversibility.

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?

The single parameter 'threadId' is self-explanatory given the tool name, and with 0% schema coverage the description adds no extra meaning, which is adequate for this simple case.

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?

The description clearly states the action 'Mark a thread as read', which directly matches the tool name and distinguishes it from siblings like 'mark_unread'.

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?

It explains the side effect (removes UNREAD) and reversibility via mark_unread, providing clear context for usage, though it does not explicitly state when not to use it.

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

mark_unreadA

Idempotent

Mark a thread as unread. SIDE EFFECTS: adds UNREAD; reversible via mark_read.

ParametersJSON Schema

Name	Required	Description	Default
`threadId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	Yes

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already indicate idempotent and non-destructive behavior. The description adds value by explicitly stating the side effect 'adds UNREAD' and noting reversibility, which aligns with and supplements the annotations.

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?

The description is extremely concise: one sentence plus a bullet for side effects. Every word is necessary, and the structure immediately conveys the core action and notable consequences.

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?

Given the simplicity of the tool (1 parameter, no enums, output schema present), the description covers the essential behavior. It could benefit from explaining what 'threadId' represents, but the context from sibling tools and the name likely suffices for an AI agent.

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

Parameters2/5

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

The input schema has one parameter 'threadId' with no description, and schema description coverage is 0%. The description does not explain the parameter meaning, format, or constraints. While the name is self-explanatory, the description should add more context to compensate for the schema 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?

The description clearly states the action: 'Mark a thread as unread.' The verb 'Mark' and resource 'thread' are specific. It distinguishes from sibling 'mark_read' implicitly through the opposite action, and the name itself clarifies the purpose.

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

Usage Guidelines3/5

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

The description mentions reversibility via 'mark_read,' which hints at when not to use it (if you want to undo). However, it does not provide explicit context on when to use this tool over alternatives like 'archive' or 'trash,' leaving some ambiguity.

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

modify_labelsA

Idempotent

Add/remove labels on a thread. Archive = remove 'INBOX'; mark read = remove 'UNREAD'. Labels may be given by name or by id: an unknown name in add is created automatically (use '/' for nested labels), an unknown name in remove is ignored. USE WHEN: applying custom labels or label combinations in one call. DO NOT USE: for plain archive/read/unread — the dedicated tools are clearer. SIDE EFFECTS: changes the thread's labels (and may create a label named in add); reversible by the inverse call.

ParametersJSON Schema

Name	Required	Description	Default
`add`	No
`remove`	No
`threadId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	Yes

TDQS

A5/5.0

Behavior5/5

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

Beyond annotations, the description discloses side effects ('changes the thread's labels'), the auto-creation of labels in 'add', the ignoring of unknown names in 'remove', and reversibility via inverse call. This adds meaningful behavioral context not present in the idempotentHint or readOnlyHint annotations.

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?

The description is tightly written with front-loaded purpose and structured segments (USE WHEN, DO NOT USE, SIDE EFFECTS). Every sentence conveys needed information without fluff, making it easy for an agent to parse quickly.

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?

Given the tool's simple scope (single thread labels) and the presence of an output schema, the description covers all essential usage aspects: operation semantics, edge cases (unknown labels), side effects, and reversibility. It is complete enough to guide correct invocation without requiring external knowledge.

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 description coverage is 0%, so the description must bear the full weight of parameter explanation. It does so by explaining that labels can be given by name or id, describing the special INBOX/UNREAD mapping, and clarifying the behavior of unknown names in each array. This goes well beyond the bare schema.

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?

The description opens with 'Add/remove labels on a thread,' a specific verb and resource. It distinguishes itself from siblings by explicitly mapping archive to removing 'INBOX' and mark read to removing 'UNREAD,' and by pointing out that dedicated tools exist for simpler operations.

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?

The description provides explicit 'USE WHEN' and 'DO NOT USE' guidance, naming alternatives ('dedicated tools') for plain archive/read/unread. This clearly tells an agent when to select this tool over similar ones like mark_read or archive.

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

searchA

Read-only

Search Gmail with native query syntax (e.g. 'in:inbox from:foo@bar.com newer_than:7d'). Returns thread summaries; read-state/category predicates are re-verified against each hit's live labels. Each summary carries signals derived from the thread's first message headers/MIME — newsletter (List-Id/List-Unsubscribe/Precedence bulk or list), automated (Auto-Submitted, auto-reply/suppress headers, no-reply-style senders), calendar (text/calendar or .ics part), replyToMismatch (a Reply-To on another domain than From — a subdomain of the same domain counts as the same); empty when nothing is declared. Paginated: when more results exist, the response carries a nextPageToken — pass it back via pageToken to fetch the next page. A page can come back with FEWER threads than maxResults and still have a nextPageToken: false positives from the index consume the scan window, and on a mailbox whose read state the index has fallen behind on, most candidates for an is:unread query can be already-read mail. A short page is therefore not evidence that the result set is exhausted — only an absent nextPageToken is. SPAM AND TRASH ARE EXCLUDED unless the query names them. Gmail leaves both out of any query that does not say in:spam / in:trash, so a plain from:someone returns nothing for a mail that is sitting in spam — measured against a live mailbox, not assumed. Nothing in the result marks the omission, so treat 'no hits' as 'none outside spam and trash'. When mail the user expects is missing, retry with in:spam before reporting that it does not exist: mail is often filed as spam because of something the user just did — a signup, a password reset, an order confirmation — which is precisely what a spam filter cannot know and the caller often can. USE WHEN: locating threads by sender, subject, date, label, or read state. DO NOT USE: to fetch a thread you already have the ID of (use get_thread). SIDE EFFECTS: none.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`pageToken`	No
`maxResults`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`threads`	Yes
`nextPageToken`	No

TDQS

A4.8/5.0

Behavior5/5

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

The description goes far beyond the readOnlyHint annotation, disclosing that spam/trash are excluded unless named, that pages can be short with a nextPageToken, that signals are derived from headers, and that no hits may mean 'none outside spam/trash'. It also explicitly states 'SIDE EFFECTS: none', aligning with readOnlyHint. No contradiction.

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?

The description is long but every sentence earns its place, covering critical behavioral nuances. It is front-loaded with the core purpose and query syntax, then dives into pagination and spam/trash caveats. The USE WHEN/DO NOT USE structure aids scannability. Slightly verbose but justified by the complexity.

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?

Given the tool's complexity (pagination, spam/trash exclusion, signals derivation, false positives), the description is remarkably complete. It covers return values (signals, nextPageToken), edge cases (short pages, spam), and usage guidance. The output schema exists, so return format details are not needed in the description.

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 description coverage is 0%, so the description must compensate. It explains the query parameter with examples and describes the pageToken behavior and maxResults pagination semantics. It doesn't detail maxResults bounds (schema has that), but it adds crucial context about short pages and nextPageToken, which is more valuable than repeating schema constraints.

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?

The description clearly states the tool searches Gmail with native query syntax and returns thread summaries. It distinguishes itself from siblings by explicitly noting it is for locating threads by sender, subject, date, label, or read state, and not for fetching a thread by ID (which is get_thread's job).

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?

The description provides explicit 'USE WHEN' and 'DO NOT USE' sections, naming the alternative tool (get_thread) and clarifying when not to use this tool. It also gives detailed guidance on handling spam/trash exclusions and pagination, which are critical usage contexts.

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

snoozeA

Idempotent

Snooze a thread until a date or time: archives it now, resurfaces when it comes due and sweep_snoozed runs. until accepts an explicit date (YYYY-MM-DD), a date+time (YYYY-MM-DD HH:MM or e.g. '2026-06-20 9am'), OR a preset resolved server-side: today, tomorrow, weekend (next Saturday), next week (next Monday), a weekday name (monday–sunday, next occurrence), 'in N days', or 'in N hours'. A preset may carry a trailing time ('tomorrow 9am', 'monday 8:30'). A timed snooze wakes at the next sweep on/after that minute. USE WHEN: deferring a thread to a later date/time instead of leaving it in the inbox. DO NOT USE: for permanent removal (use archive or trash). SIDE EFFECTS: removes INBOX, adds a dated MCP/Snoozed label; reversible via unsnooze.

ParametersJSON Schema

Name	Required	Description	Default
`until`	Yes
`threadId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`threadId`	Yes
`snoozedUntil`	Yes

TDQS

A5/5.0

Behavior5/5

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

Explains side effects in detail ('removes INBOX, adds a dated MCP/Snoozed label'), notes reversibility ('reversible via unsnooze'), and describes the resurfacing trigger ('sweep_snoozed runs'). This goes well beyond the annotations (readOnly=false, destructive=false, idempotent=true) and is consistent with them.

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?

Structured and front-loaded: one-sentence summary, then detailed `until` format, then usage guidance, then side effects. Every sentence adds value; the length is justified by the complexity of the `until` parameter.

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 operation, timing semantics, side effects, reversibility, and usage boundaries. With an output schema present, no return-value explanation is needed, and the description is sufficient for an agent to select and invoke the tool correctly.

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 has no descriptions for either parameter (0% coverage), but the description provides exhaustive detail for `until`, including explicit date/time formats, presets, and trailing times. `threadId` is self-explanatory from its name, so the description compensates fully.

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?

Clearly identifies the operation ('Snooze a thread') and its resource ('thread'), and explains the mechanism (archives now, resurfaces later). It also distinguishes from siblings by stating 'DO NOT USE for permanent removal (use archive or trash).'

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?

Explicitly states when to use ('USE WHEN: deferring a thread to a later date/time instead of leaving it in the inbox') and when not to ('DO NOT USE: for permanent removal (use archive or trash)'), naming alternatives.

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

sweep_snoozedA

Idempotent

Resurface all snoozed threads whose date is due (<= today), batched at 1000 messages per API request. Set dryRun:true to rehearse: reports the due labels and threads (dueLabels/dueThreads) as the sweep would find them (from the live label listing; a single snooze label with more than 5000 messages is under-counted in the rehearsal), and wakes nothing. USE WHEN: the user asks to process due snoozes, or as a scheduled maintenance call; dryRun to answer 'what is due right now?' without acting. SIDE EFFECTS: due threads return to the inbox marked unread (none with dryRun); safe to run repeatedly. failedCount/errors report messages a batch could not wake (their label is kept for the next sweep).

ParametersJSON Schema

Name	Required	Description	Default
`dryRun`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`date`	Yes
`woken`	Yes
`dryRun`	Yes
`errors`	Yes
`dueLabels`	Yes
`dueThreads`	Yes
`wokenCount`	Yes
`failedCount`	Yes
`dueThreadCount`	Yes

TDQS

A4.8/5.0

Behavior5/5

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

The description goes well beyond the annotations by disclosing concrete side effects: due threads return to the inbox marked unread, dryRun wakes none, and failures keep the label for the next sweep. It also discloses a real limitation (under-counting in rehearsal for labels with >5000 messages), the batch size, and idempotence, giving the agent an accurate behavioral model.

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?

The description is well-structured with labeled sections (USE WHEN, SIDE EFFECTS) and front-loaded with the core function. Every sentence adds value—batch size, dryRun behavior, side effects, and error handling—without fluff. It is longer than ideal but earns its length through density of useful information.

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?

Given the tool's complexity and the presence of an output schema, the description covers all critical aspects: behavior, batch limits, dryRun rehearsal details, side effects, idempotence, and failure handling ('failedCount/errors report messages a batch could not wake'). No significant gaps remain for the agent to make an informed invocation decision.

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?

Even though the schema only defines a single boolean dryRun, the description thoroughly explains its purpose and outcome: setting dryRun:true produces a rehearsal that reports dueLabels/dueThreads and wakes nothing. This fully compensates for the schema's minimal parameter info, adding essential semantics for correct invocation.

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?

The description opens with a specific verb ('Resurface') and a precise target ('all snoozed threads whose date is due (<= today)'), making it unmistakable what the tool does. It clearly differentiates from sibling tools such as list_snoozed, snooze, and unsnooze by focusing on acting on due threads rather than listing or individual operations.

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?

The description includes an explicit 'USE WHEN' section stating clear triggers: 'the user asks to process due snoozes, or as a scheduled maintenance call,' and also covers the dryRun rehearsal use case for answering 'what is due right now?' without acting. It lacks an explicit 'when not to use' or direct alternative names, but the context is sufficiently clear.

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

trashA

DestructiveIdempotent

Move a thread to Trash. USE WHEN: the thread should be discarded. DO NOT USE: for inbox cleanup of mail worth keeping (use archive). SIDE EFFECTS: thread moves to Trash; recoverable via untrash for ~30 days, then Gmail deletes it permanently.

ParametersJSON Schema

Name	Required	Description	Default
`threadId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already indicate destructiveHint=true, but the description adds critical context: thread is recoverable via untrash for ~30 days, then permanently deleted. This goes beyond annotations.

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?

The description is three sentences, front-loaded with the action, and every sentence adds value with no redundancy.

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?

For a simple tool with one parameter and an output schema present, the description covers purpose, usage guidelines, and side effects completely.

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?

The schema has 0% description coverage for the single required string parameter 'threadId'. While the description doesn't detail its format, the tool's context makes it clear. A format hint (e.g., 'Gmail thread ID') would improve clarity.

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?

The description explicitly states 'Move a thread to Trash' with a specific verb and resource, and distinguishes from the sibling 'archive' tool by noting when not to use it.

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?

The description provides clear USE WHEN ('the thread should be discarded') and DO NOT USE conditions ('for inbox cleanup of mail worth keeping') with explicit alternative (archive). This is exemplary guidance.

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

triage_digestA

Read-only

Structured overview of a mailbox slice for triage DECISIONS — sender / label / age buckets, unread and attachment counts, and header-derived signals (newsletter / automated / calendar / replyToMismatch — thread counts overall, and per sender the set of signals its threads carry), instead of a raw thread list. USE WHEN: deciding what to bulk-archive/snooze/label, or summarizing inbox state ('what's in my inbox?'). DO NOT USE: to read a specific thread (use search/get_thread). Samples up to max most-recent matches; hasMore flags that more matched than were sampled. byAge buckets by each thread's FIRST message date (thread age, not last activity). SIDE EFFECTS: none.

ParametersJSON Schema

Name	Required	Default
`max`	No
`topN`	No
`query`	No	in:inbox

Output Schema

ParametersJSON Schema

Name	Required	Description
`byAge`	Yes
`query`	Yes
`unread`	Yes
`hasMore`	Yes
`sampled`	Yes
`signals`	Yes
`topLabels`	Yes
`topSenders`	Yes
`withAttachments`	Yes

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, but the description adds valuable behavioral details: sampling up to 'max' with hasMore, age bucketing by first message date, and explicit 'SIDE EFFECTS: none'. This goes beyond annotations and answers likely agent questions.

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?

The description is dense yet well-organized into clear sections: overview, use cases, behavior, and side effects. Every sentence contributes new information, with no redundancy or filler.

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?

The description covers the tool's purpose, usage, sampling, age bucketing, and side effects, while an output schema likely handles return-value documentation. However, it leaves parameter semantics incomplete (especially topN/query), a notable gap given the low schema coverage.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must explain parameters. It only mentions 'max' (sampling limit) but leaves 'topN' and 'query' undefined. This forces the agent to infer their meaning, which is insufficient for correct invocation.

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?

The description clearly states it provides a structured overview of a mailbox slice for triage decisions, listing specific aggregated fields (sender/label/age buckets, counts, signals) and explicitly contrasts with a raw thread list. It also distinguishes from reading a specific thread by referencing search/get_thread.

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?

Includes explicit 'USE WHEN' and 'DO NOT USE' sections, naming alternatives (search/get_thread) and giving concrete examples like bulk-archiving/snoozing/labeling. This provides clear guidance on when to choose this tool over siblings.

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

unsnoozeA

Idempotent

Cancel a snooze: return the thread to the inbox now. SIDE EFFECTS: removes the snooze label, restores INBOX.

ParametersJSON Schema

Name	Required	Description	Default
`threadId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`threadId`	Yes
`unsnoozed`	Yes

TDQS

A4.1/5.0

Behavior5/5

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

The description discloses side effects beyond annotations: 'removes the snooze label, restores INBOX'. Annotations already indicate idempotentHint=true and destructiveHint=false, and the description aligns with these, adding valuable behavioral context without contradiction.

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?

The description is extremely concise with two sentences. The first sentence front-loads the primary action, and the second lists side effects. No wasted words.

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 simple one-parameter tool with an output schema (though not shown), the description covers the essential effect. However, it omits any mention of error conditions or prerequisites (e.g., thread must be snoozed). Still, given low complexity and presence of output schema, it is largely complete.

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

Parameters1/5

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

The single parameter threadId has no description in the schema (0% coverage) and the tool description does not add any meaning beyond the name. It fails to explain what threadId represents or its format, which is necessary for correct usage.

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?

The description clearly states the action: 'cancel a snooze' and 'return the thread to the inbox', with a specific verb and resource. It distinguishes from sibling tools like snooze (the reverse operation).

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?

The description explicitly states when to use the tool (to cancel a snooze) and mentions side effects, but does not explicitly state when not to use it or list alternatives like mark_read or archive. However, the sibling list includes snooze as the inverse, making usage clear.

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

unsubscribeA

Idempotent

Unsubscribe from the mailing list a thread came from, via the sender's RFC 8058 one-click endpoint. There is deliberately no URL parameter: the endpoint is taken from the message's own List-Unsubscribe header and nowhere else. Only https one-click endpoints are called (fixed request body, response body discarded); a plain link is reported for the user to open, and a mailto: opt-out is never performed because mailwarden cannot send mail. If the sender offers nothing automatable this returns unsubscribed:false with the alternatives in options — it is not an error. USE WHEN: the user wants off a newsletter. Pair with archive/trash or create_filter to deal with mail already in the mailbox. DO NOT USE: to check whether unsubscribing is possible (use list_unsubscribe — it contacts nobody). A sender already contacted in this session is reported with duplicateOf and NOT contacted again — safe to retry after a timeout. Pass force:true for a deliberate second attempt (e.g. the endpoint answered 500). SIDE EFFECTS: makes an outbound HTTPS request to the sender's unsubscribe endpoint (plus up to 3 redirects) — the only non-Google host mailwarden ever contacts. This confirms to the sender that the address is live, and it cannot be undone. The mailbox itself is not changed.

ParametersJSON Schema

Name	Required	Description	Default
`force`	No
`threadId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	No
`from`	Yes
`reason`	No
`status`	No
`options`	Yes
`threadId`	Yes
`messageId`	Yes
`duplicateOf`	No
`unsubscribed`	Yes

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description discloses crucial side effects: makes an outbound HTTPS request, confirms the address is live, cannot be undone, and never modifies the mailbox. It also details the duplicateOf behavior and force:true for retries. No contradictions with annotations.

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?

The description is dense but well-organized with 'USE WHEN', 'DO NOT USE', and 'SIDE EFFECTS' sections. Every sentence adds value: security protocol, lacking URL parameter, redirect limits, non-error on failure. Despite length, it remains front-loaded and efficiently structured.

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?

Given the tool's complexity (external network call, alternative handling, duplicate prevention), the description covers all aspects: side effects, alternatives, failure modes, and output semantics (duplicateOf, options). An output schema exists, so return values are covered. No significant gaps remain.

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 0%, so the description must explain parameters. It implicitly defines threadId as the thread containing the mailing list email. It explicitly explains force:true for a deliberate second attempt. While it doesn't specify threadId's exact format, it adds meaningful context beyond the bare schema. Slight room for more explicit parameter documentation.

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?

The description states a specific action: 'Unsubscribe from the mailing list a thread came from, via the sender's RFC 8058 one-click endpoint.' It clearly distinguishes from sibling tools (e.g., list_unsubscribe) by emphasizing it actually performs the subscription removal. The scope and method are precise.

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 guidance is given: 'USE WHEN: the user wants off a newsletter' and 'DO NOT USE: to check whether unsubscribing is possible (use list_unsubscribe — it contacts nobody).' It also suggests pairing with archive/trash or create_filter for post-processing. This fully covers when and when not to use, with alternative tools named.

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

untrashA

Idempotent

Restore a thread from Trash. SIDE EFFECTS: removes the TRASH label; user labels are preserved, but INBOX is NOT re-added — use modify_labels (add INBOX) to return it to the inbox.

ParametersJSON Schema

Name	Required	Description	Default
`threadId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`ok`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

Annotations (readOnlyHint=false, destructiveHint=false) already indicate mutation and non-destructive nature. Description adds critical context: side effects on labels (TRASH removal, INBOX not re-added). No contradiction with annotations.

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?

Two sentences: first provides core action, second details side effects and follow-up. No superfluous words. Efficient and front-loaded.

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?

Output schema exists, so return values are documented externally. Description covers side effects, usage, and follow-up. With one simple param and clear annotations, the description is fully adequate.

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?

Only one parameter 'threadId' with 0% schema description coverage. Description does not explicitly detail the parameter, but context from 'Restore a thread from Trash' implies its purpose. Adequate for a simple string param, but could be more explicit.

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?

Description clearly states 'Restore a thread from Trash.' verb+resource pair. Distinguishes from sibling tools like 'trash' (opposite action) and 'archive' (different destination).

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?

Explicitly notes side effects: removes TRASH label, preserves user labels, but does NOT re-add INBOX. Recommends using 'modify_labels (add INBOX)' to return to inbox. Provides clear when-to-use and follow-up action.

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

what_changedA

Read-only

What happened in the mailbox since a point you already hold: messages that arrived or were removed, and labels applied or taken off — from Gmail's own event log, in one call. Pass the historyId a previous what_changed or get_profile returned; the reply carries the next one to keep. mailwarden stores NOTHING between calls, so the id lives with you. Reports EVENTS, not current state: a message that was marked unread and then read appears under both, and both are true. For how the mailbox looks NOW, use search or get_thread. Gmail keeps roughly a week of history. An id older than that is an ERROR, never an empty result — it means the question can no longer be answered incrementally, so take a fresh historyId from get_profile and re-establish state with search. labelId narrows the feed to events touching one label (e.g. 'INBOX', or a snooze label). Counts are complete even when the id lists are cut at 200 (truncated). USE WHEN: a recurring check — 'what came in since I last looked', watching a label, or confirming a bulk action landed. Far cheaper than re-running a search over the whole slice. DO NOT USE: for a first look at a mailbox (there is no id yet — start with triage_digest or search), or to read content: this returns ids only, no sender, subject or body. SIDE EFFECTS: none.

ParametersJSON Schema

Name	Required	Description	Default
`max`	No
`labelId`	No
`sinceHistoryId`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`added`	Yes
`deleted`	Yes
`records`	Yes
`historyId`	Yes
`truncated`	Yes
`labelsAdded`	Yes
`labelsRemoved`	Yes

TDQS

A4.9/5.0

Behavior5/5

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

Goes far beyond the annotations: explains events vs current state, history retention limits, error-on-stale-id behavior, truncation semantics, count completeness, and side-effect-free behavior. No contradiction with readOnlyHint=true.

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?

The description is long but every sentence earns its place: mechanics, semantics, error handling, use cases, and exclusions are all present. Critical context is front-loaded before the extended guidance.

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?

For a delta-reporting tool with one required parameter, the description covers return shape, state management, error behavior, filter behavior, and alternatives. Even with an output schema present, nothing important is left ambiguous.

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 description coverage is 0%, but the description adds deep semantics for sinceHistoryId (how to obtain, carry, and refresh it) and labelId (narrowing to label events). max is not explicitly described, though its schema constraints make it largely self-explanatory.

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?

The description states exactly what the tool reports — mailbox changes (arrivals, removals, label changes) from Gmail's event log since a held historyId. It explicitly contrasts with search and get_thread, so an agent can distinguish this from siblings immediately.

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?

Provides explicit USE WHEN guidance for recurring checks and DO NOT USE guidance for first looks and content reading, naming alternatives like triage_digest, search, and get_thread. This is exemplary routing information.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

5 tool updatesv0.18.0Sep 4, 2026

Changedbulk_modify2 fields changed

addedInput schema / properties / crossCheck

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedOutput schema / properties / crossChecked

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "capped": {
+      "type": "boolean"
+    },
+    "dropped": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "predicate": {
+            "type": "string"
+          },
+          "threadId": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "threadId",
+          "predicate"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "droppedMessages": {
+      "type": "number"
+    },
+    "predicates": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "skipped": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "predicates",
+    "droppedMessages",
+    "dropped",
+    "capped"
+  ],
+  "type": "object"
+}

Changedcreate_label3 fields changed

addedInput schema / properties / backgroundColor
```
Added value: +{
+  "type": "string"
+}
```
addedInput schema / properties / textColor
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / color

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "backgroundColor": {
+      "type": "string"
+    },
+    "textColor": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "backgroundColor",
+    "textColor"
+  ],
+  "type": "object"
+}

Changedget_profile2 fields changed

addedOutput schema / properties / historyId
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / required

Previous value: -[
-  "emailAddress",
-  "messagesTotal",
-  "threadsTotal"
-]New value: +[
+  "emailAddress",
+  "messagesTotal",
+  "threadsTotal",
+  "historyId"
+]

Changedlist_unsubscribe2 fields changed

addedOutput schema / properties / bodyCandidates

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "evidence": {
+        "enum": [
+          "link-text",
+          "url"
+        ],
+        "type": "string"
+      },
+      "text": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "url",
+      "evidence",
+      "text"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "threadId",
-  "messageId",
-  "from",
-  "subject",
-  "hasUnsubscribe",
-  "oneClick",
-  "httpsUrls",
-  "mailtos"
-]New value: +[
+  "threadId",
+  "messageId",
+  "from",
+  "subject",
+  "hasUnsubscribe",
+  "bodyCandidates",
+  "oneClick",
+  "httpsUrls",
+  "mailtos"
+]

Addedwhat_changed

1 tool updatev0.17.0Sep 3, 2026

Changedget_thread2 fields changed

addedOutput schema / properties / messages / items / properties / authentication

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "alsoReported": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "authservId": {
+      "type": "string"
+    },
+    "dkim": {
+      "type": "string"
+    },
+    "dmarc": {
+      "type": "string"
+    },
+    "headerFrom": {
+      "type": "string"
+    },
+    "mailedBy": {
+      "type": "string"
+    },
+    "otherReports": {
+      "type": "integer"
+    },
+    "returnPath": {
+      "type": "string"
+    },
+    "signedBy": {
+      "type": "string"
+    },
+    "spf": {
+      "type": "string"
+    },
+    "unchecked": {
+      "const": true,
+      "type": "boolean"
+    }
+  },
+  "type": "object"
+}

changedOutput schema / properties / messages / items / required

Previous value: -[
-  "id",
-  "threadId",
-  "labelIds",
-  "from",
-  "to",
-  "subject",
-  "date",
-  "snippet"
-]New value: +[
+  "id",
+  "threadId",
+  "labelIds",
+  "from",
+  "to",
+  "subject",
+  "date",
+  "snippet",
+  "authentication"
+]

3 tool updatesv0.15.1Aug 26, 2026

Changedbulk_modify9 fields changed

addedInput schema / properties / verify

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

removedOutput schema / properties / modifiedMessages
```
Removed value: -{
-  "type": "number"
-}
```
removedOutput schema / properties / modifiedThreadCount
```
Removed value: -{
-  "type": "number"
-}
```

removedOutput schema / properties / modifiedThreads

Removed value: -{
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

addedOutput schema / properties / submittedMessages
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / submittedThreadCount
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / submittedThreads

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / verified

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "applied": {
+      "type": "number"
+    },
+    "notApplied": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "unverifiable": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "applied",
+    "notApplied",
+    "unverifiable"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "dryRun",
-  "matchedMessages",
-  "matchedThreadCount",
-  "matchedThreads",
-  "modifiedMessages",
-  "modifiedThreadCount",
-  "modifiedThreads",
-  "capped",
-  "unverifiedPredicates",
-  "failed"
-]New value: +[
+  "dryRun",
+  "matchedMessages",
+  "matchedThreadCount",
+  "matchedThreads",
+  "submittedMessages",
+  "submittedThreadCount",
+  "submittedThreads",
+  "capped",
+  "unverifiedPredicates",
+  "failed"
+]

Changedcreate_filter1 field changed

changedOutput schema / properties / applied / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "capped": {
-        "type": "boolean"
-      },
-      "error": {
-        "type": "string"
-      },
-      "failed": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "error": {
-              "type": "string"
-            },
-            "messageIds": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            }
-          },
-          "required": [
-            "messageIds",
-            "error"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "matchedMessages": {
-        "type": "number"
-      },
-      "modifiedMessages": {
-        "type": "number"
-      },
-      "modifiedThreadCount": {
-        "type": "number"
-      },
-      "query": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "query",
-      "matchedMessages",
-      "modifiedMessages",
-      "modifiedThreadCount",
-      "capped",
-      "failed"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "capped": {
+        "type": "boolean"
+      },
+      "error": {
+        "type": "string"
+      },
+      "failed": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "error": {
+              "type": "string"
+            },
+            "messageIds": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "messageIds",
+            "error"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "matchedMessages": {
+        "type": "number"
+      },
+      "query": {
+        "type": "string"
+      },
+      "submittedMessages": {
+        "type": "number"
+      },
+      "submittedThreadCount": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "query",
+      "matchedMessages",
+      "submittedMessages",
+      "submittedThreadCount",
+      "capped",
+      "failed"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changedget_thread2 fields changed

changedOutput schema / properties / messages / items / required

Previous value: -[
-  "id",
-  "threadId",
-  "labelIds",
-  "from",
-  "to",
-  "subject",
-  "date",
-  "snippet",
-  "plaintextBody",
-  "htmlBody",
-  "attachments"
-]New value: +[
+  "id",
+  "threadId",
+  "labelIds",
+  "from",
+  "to",
+  "subject",
+  "date",
+  "snippet"
+]

addedOutput schema / properties / metadataOnly

Added value: +{
+  "const": true,
+  "type": "boolean"
+}

1 tool updatev0.14.0Aug 22, 2026
- Changedunsubscribe2 fields changed
  - addedInput schema / properties / force
```
Added value: +{
+  "default": false,
+  "type": "boolean"
+}
```
  - addedOutput schema / properties / duplicateOf
```
Added value: +{
+  "type": "string"
+}
```

5 tool updatesv0.11.0Aug 16, 2026

Changedbulk_modify7 fields changed

addedInput schema / properties / dryRun

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedOutput schema / properties / dryRun
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / labelsToCreate

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / matchedThreadCount
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / matchedThreads

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / unverifiedPredicates

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "matchedMessages",
-  "modifiedMessages",
-  "modifiedThreadCount",
-  "modifiedThreads",
-  "capped",
-  "failed"
-]New value: +[
+  "dryRun",
+  "matchedMessages",
+  "matchedThreadCount",
+  "matchedThreads",
+  "modifiedMessages",
+  "modifiedThreadCount",
+  "modifiedThreads",
+  "capped",
+  "unverifiedPredicates",
+  "failed"
+]

Changedbulk_unsubscribe5 fields changed

addedInput schema / properties / dryRun

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedOutput schema / properties / dryRun
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / requests
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / results / items / properties / wouldCall
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / required

Previous value: -[
-  "requested",
-  "attempted",
-  "unsubscribed",
-  "skippedDuplicates",
-  "skippedOutOfTime",
-  "results"
-]New value: +[
+  "dryRun",
+  "requested",
+  "attempted",
+  "unsubscribed",
+  "skippedDuplicates",
+  "skippedOutOfTime",
+  "requests",
+  "results"
+]

Changedsearch2 fields changed

addedOutput schema / properties / threads / items / properties / signals

Added value: +{
+  "items": {
+    "enum": [
+      "newsletter",
+      "automated",
+      "calendar",
+      "replyToMismatch"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / threads / items / required

Previous value: -[
-  "threadId",
-  "messageCount",
-  "from",
-  "subject",
-  "date",
-  "labelIds",
-  "snippet",
-  "hasAttachments"
-]New value: +[
+  "threadId",
+  "messageCount",
+  "from",
+  "subject",
+  "date",
+  "labelIds",
+  "snippet",
+  "hasAttachments",
+  "signals"
+]

Changedsweep_snoozed8 fields changed

addedInput schema / $schema

Added value: +"http://json-schema.org/draft-07/schema#"

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / dryRun

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedOutput schema / properties / dryRun
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / dueLabels

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / dueThreadCount
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / dueThreads

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "date",
-  "wokenCount",
-  "woken",
-  "failedCount",
-  "errors"
-]New value: +[
+  "date",
+  "dryRun",
+  "dueLabels",
+  "dueThreadCount",
+  "dueThreads",
+  "wokenCount",
+  "woken",
+  "failedCount",
+  "errors"
+]

Changedtriage_digest4 fields changed

addedOutput schema / properties / signals

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "automated": {
+      "type": "number"
+    },
+    "calendar": {
+      "type": "number"
+    },
+    "newsletter": {
+      "type": "number"
+    },
+    "replyToMismatch": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "newsletter",
+    "automated",
+    "calendar",
+    "replyToMismatch"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / topSenders / items / properties / signals

Added value: +{
+  "items": {
+    "enum": [
+      "newsletter",
+      "automated",
+      "calendar",
+      "replyToMismatch"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / topSenders / items / required

Previous value: -[
-  "sender",
-  "name",
-  "count",
-  "unread"
-]New value: +[
+  "sender",
+  "name",
+  "count",
+  "unread",
+  "signals"
+]

changedOutput schema / required

Previous value: -[
-  "query",
-  "sampled",
-  "hasMore",
-  "unread",
-  "withAttachments",
-  "byAge",
-  "topSenders",
-  "topLabels"
-]New value: +[
+  "query",
+  "sampled",
+  "hasMore",
+  "unread",
+  "withAttachments",
+  "byAge",
+  "signals",
+  "topSenders",
+  "topLabels"
+]

4 tool updatesv0.9.0Aug 14, 2026
- Addedbulk_unsubscribe
- Addedlist_subscriptions
- Addedlist_unsubscribe
- Addedunsubscribe
8 tool updatesv0.6.0Aug 7, 2026
- Changedbulk_modify1 field changed
  - addedInput schema / properties / query / minLength
```
Added value: +1
```
- Addedcreate_filter
- Addedcreate_label
- Addeddelete_filter
- Addedget_profile
- Addedlist_filters
- Changedsnooze2 fields changed
  - addedInput schema / properties / until / minLength
```
Added value: +1
```
  - removedInput schema / properties / until / pattern
```
Removed value: -"^\\d{4}-\\d{2}-\\d{2}$"
```
- Addedtriage_digest

1 tool updatev0.1.9Aug 3, 2026

Changedbulk_modify2 fields changed

addedOutput schema / properties / capped
```
Added value: +{
+  "type": "boolean"
+}
```

changedOutput schema / required

Previous value: -[
-  "matchedMessages",
-  "modifiedMessages",
-  "modifiedThreadCount",
-  "modifiedThreads",
-  "failed"
-]New value: +[
+  "matchedMessages",
+  "modifiedMessages",
+  "modifiedThreadCount",
+  "modifiedThreads",
+  "capped",
+  "failed"
+]

15 tool updatesv0.1.8Jul 24, 2026
- First observedarchive
- First observedbulk_modify
- First observeddownload_attachment
- First observedget_thread
- First observedlist_labels
- First observedlist_snoozed
- First observedmark_read
- First observedmark_unread
- First observedmodify_labels
- First observedsearch
- First observedsnooze
- First observedsweep_snoozed
- First observedtrash
- First observedunsnooze
- First observeduntrash

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Disambiguation4/5

Most tools target a distinct resource and action, and the extensive USE WHEN / DO NOT USE guidance resolves most potential confusion. A few closely related pairs (search vs triage_digest, list_unsubscribe vs list_subscriptions, modify_labels vs bulk_modify) could be misselected, but their descriptions draw clear boundaries.

Naming Consistency4/5

The tool names largely follow a clear verb_noun or verb_object pattern, such as create_label, list_filters, delete_filter, mark_read, and bulk_unsubscribe. Minor deviations like what_changed, triage_digest, list_snoozed, and bulk_modify break the pattern slightly but remain readable and predictable.

Tool Count4/5

26 tools is on the heavy side, but the server covers a broad Gmail management domain: search, labels, bulk actions, archive/trash/snooze, filters, and unsubscribe workflows. Although a few convenience tools like archive and mark_read overlap with modify_labels, they still serve common triage actions clearly.

Completeness3/5

The tool set covers most core workflows: finding and reading threads, applying labels, bulk operations, snoozing, filtering, and unsubscribing. However, there are notable lifecycle gaps: labels can be created and listed but not deleted, filters can be created and deleted but not updated, and there is no permanent-delete or empty-trash operation.

Maintenance

ActivityActive

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

gmail AOAuth
com.mintmcp
A MCP server for Gmail that lets you search, read, and draft emails and replies.
Communication App Automation Workplace & Productivity
48
MCP Emails AOAuth
com.mcpemails
Read, search, send, organize, draft and schedule email across your inboxes from any MCP client.
Communication Email
25
email A
dev.primitive
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email Communication
302
Email Server
live.alpic.staging
An MCP server that provides email capabilities, hosted on Alpic platform
Communication App Automation
2

Related MCP Servers

Gmail Plugin MCP Server
Communication App Automation
sanchisingh01
A
license
Not graded
quality
D
maintenance
An MCP server that enables Gmail integration, allowing users to manage emails (send, receive, read, trash, mark as read) directly through MCP clients like Claude Desktop.
Updated a year ago (2025-04-23 18:09 UTC)
1
MIT
Gmail MCP
Communication App Automation
shinzo-labs
A
license
B
quality
D
maintenance
Manage your emails effortlessly with a standardized interface for drafting, sending, retrieving, and organizing messages. Streamline your email workflow with complete Gmail API coverage, including label and thread management.
Updated 9 months ago (2025-11-25 09:52 UTC)
64
1,723
57
MIT
gmail-mcp
Email App Automation Developer Tools
klodr
A
license
Not graded
quality
A
maintenance
Gmail MCP server — scope-gated tools (readonly / send / modify), path jails for attachments + downloads, hardened OAuth credentials, Sigstore-signed releases.
Updated 13 days ago (2026-08-24 06:46 UTC)
306
11
MIT
gmail-mcp-multi
Email Communication
dmorrill
A
license
A
quality
F
maintenance
A Gmail MCP server with native multi-account support, enabling management of multiple Gmail accounts from a single server instance.
Updated 6 months ago (2026-03-08 13:09 UTC)
7
5
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/csitte/mailwarden'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

mailwarden

Highlights

Why

Compared to other Gmail MCP servers

Running it next to a Workspace server

Why re-verification matters — a concrete case

Asking again without asking for everything

Judging a sender — what authentication answers, and what it doesn't

Tools

How snooze works (no Gmail API snooze exists — we build it)

Filters (persistent auto-triage rules)

Unsubscribing — the one outbound request

Looking in spam

Security & privacy

Quick start

Setup

Connect

Multiple accounts

More than two accounts

From source

Config (env)

Status

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

Judging a sender — what `authentication` answers, and what it doesn't