mcp-proton-mail

Overview Schema Source Related Servers Discussions Admin

Count matching mail

count_mail

Read-onlyIdempotent

Count messages in a folder that match search filters and return only the total, without listing messages or marking them read.

Instructions

Count the messages in one folder that match search_mail's filters; returns a number, not messages, and marks nothing read.

Use it for "how many" questions and to size a change before preview_action; use search_mail to list or read the messages. It takes search_mail's filters, unread_only, exclusions and query, with no paging.

Cheap: IMAP UID SEARCH only (one command, plus one per extra non-ASCII value); it never fetches headers or bodies. Bridge matches every condition itself: from, to and subject compare raw header text, so encoded non-ASCII headers can count lower than search_mail finds. Header and text conditions make Bridge read each message in the folder; dates and unread_only do not. All Mail gets no default date window here. Counts come from live IMAP, not the header cache, so index_note and index_status never appear, even during a rebuild. It uses at most 20 seconds overall and 10 seconds per IMAP command (shorter configured limits win).

Returns folder and count. A timeout returns count=0 with partial=true, timed_out=true, partial_reason and error: the count is incomplete and must not be read as an empty folder. Narrower dates do not help a timeout with these conditions: use search_mail.

Input Schema

Name	Required	Description	Default
`to`	No	To header contains this text, ignoring case.
`text`	No	Raw message contains this, ignoring case. Bridge reads the whole folder to answer, whatever the dates, which a large folder may not finish in time.
`from_`	No	Sender contains this text, ignoring case.
`query`	No	Conditions joined with and, or and not; the entries of one object all apply. from, to, subject and text match substrings; and and or take a list of 1 to 20 queries, not takes one query. At most 20 conditions in 5 nested levels. For example {"or": [{"from": "a@example.test"}, {"subject": "invoice", "not": {"text": "unsubscribe"}}]}.
`since`	No	Earliest date, inclusive, as YYYY-MM-DD.
`before`	No	Latest date, exclusive, as YYYY-MM-DD.
`folder`	No	The mailbox to search, by its exact LIST name, such as INBOX, Archive, Sent, All Mail, Folders/Receipts or Labels/Work.	INBOX
`subject`	No	Subject contains this text, ignoring case.
`unread_only`	No	Only unread messages. Takes only a JSON boolean.
`exclude_text`	No	Leave out messages whose text contains this, as Bridge matches it.
`exclude_subject`	No	Leave out messages whose subject contains this text.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare read-only, idempotent, non-destructive, but the description adds substantive behavior: UID SEARCH-only cost model, no header/body fetches, per-value command overhead, and the fact that header/text conditions force a full folder read. The timeout contract (count=0 with partial=true, timed_out=true, and an explicit warning not to read it as an empty folder) is exactly the kind of trap disclosure annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the sibling routing, then cost, then return shape — a logical order. It is dense but long, and a few points (the encoded-header undercount, the All Mail date-window quirk) repeat caveats already present in the parameter descriptions, costing a little tightness.

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 what an agent needs for an 11-parameter count tool: cost model, matching semantics, encoding caveat, folder default behavior, deadline limits, and the partial/timeout return contract. With a rich schema and output schema already present, nothing material is left to inference.

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 100%, so the baseline is 3, but the description adds cross-tool semantics the schema lacks: it accepts search_mail's filters, unread_only, exclusions and query, with no paging. It also clarifies which parameter classes (dates, unread_only) avoid the expensive full-folder read, which the schema does not say.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Count the messages in one folder') plus the crucial negative scope: returns a number, not messages, and marks nothing read. This immediately separates it from search_mail without needing to open either schema.

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

Usage Guidelines5/5

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

Gives explicit when-to-use ('how many' questions, sizing a change before preview_action) and names the alternative with its condition ('use search_mail to list or read the messages'). It even routes back to search_mail when a timeout occurs, which is a real decision point for the agent.

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