mcp-proton-mail

Overview Schema Source Related Servers Discussions Admin

Search a mail folder

search_mail

Read-onlyIdempotent

Find messages in a Proton Mail folder by sender, recipient, subject, text, date, or unread status, and return paged results with message IDs for reading threads or attachments.

Instructions

Search one mail folder for messages matching the filters and return a page of rows, newest first; nothing is changed or marked read.

Use it to find messages and the message_id that read_thread, show_thread, list_attachments and preview_action(ids=...) take. Use count_mail when only a number is needed, and preview_action(query=...) to select a whole set for a change, not pages.

All filters apply together. from_, to and subject are case-insensitive header substrings; text searches the raw message, so on a large folder give since or before or it times out, and each message in that range is then read; query adds and, or and not. To continue, pass next_cursor with identical filters; it follows one UID snapshot.

Returns messages (message_id; folder, uidvalidity and uid, the canonical real-folder handle, with alias added for a view such as All Mail; from, to, subject, date, date_local, seen and a snippet), next_cursor, total, total_is_exact and partial. A null next_cursor means finished only when partial=false; partial=true has partial_reason. text_scan_limited with a next_cursor means follow it; the same reason with a null cursor and a hint means a message was left undecided; otherwise narrow the search or reindex. skipped_uids names, by UID in the searched folder, messages skipped on this page because their read stalled. Unbounded All Mail may apply a 30-day applied_since; timeouts add timed_out and error; incomplete index coverage adds index_note and index_status. Malformed INTERNALDATE values are left out of matches and totals.

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, which a large folder cannot finish in time, whatever the dates. There, give since or before: the messages in that range are read one by one, and next_cursor continues the reading.
`from_`	No	Sender contains this text, ignoring case.
`limit`	No	Messages per page; above 100 is capped at 100.
`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.
`cursor`	No	next_cursor from the previous page, with identical filters.
`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.
`include_snippets`	No	false omits snippets and avoids body and structure retrieval.

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 readOnly/idempotent/non-destructive, and the description adds substantive behavior beyond them: cursor paging follows one UID snapshot, null next_cursor means finished only when partial=false, All Mail may silently apply a 30-day applied_since, timeouts add timed_out/error, skipped_uids reports stalled reads, and malformed INTERNALDATE values drop out of matches and totals. These are exactly the surprises an agent needs warned about before calling.

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 alternatives before the mechanics, and the timeouts/partial-cursor rules are stated as actionable conditionals rather than prose. The return-field enumeration is dense and partly overlaps the output schema, so it could be trimmed without losing 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 14-parameter search tool with zero required params, the description covers selection, pagination continuation, failure modes, and the All Mail date caveat — everything needed to call it correctly. The presence of an output schema means the return-value listing is a bonus rather than a gap-filler.

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; the description still adds cross-parameter meaning the schema cannot, notably that all filters apply together, that text forces a read of each message in the date range, that query supports and/or/not nesting, and that next_cursor requires identical filters. Some of this restates schema text, which keeps it off a 5.

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

Purpose5/5

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

States a specific verb and resource ("Search one mail folder for messages matching the filters") plus the scope (one page, newest first) and the non-mutating effect. It names the siblings that consume its output (read_thread, show_thread, list_attachments, preview_action(ids=...)) so an agent can place it in the workflow without opening other schemas.

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 routing rules: use it to obtain message_ids for downstream tools, use count_mail when only a number is needed, and use preview_action(query=...) to select a whole set for a change rather than paging. It also gives a when-not caveat for the text filter on large folders and the exact rule for continuing with cursor and identical filters.

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