mcp-proton-mail

Overview Schema Source Related Servers Discussions Admin

Preview a mailbox change

preview_action

Read-only

Preview one mail change and return a single-use approval token; mail is unchanged. Use before moves, archives, label/read-state changes, unsubscribes, or draft deletions; redeem with matching action.

Instructions

Preview one change to existing mail and return a single-use approval token; changes no mail.

Use it first for any move to Trash, Archive or a folder, read-state or label change, unsubscribe or draft deletion; use preview_rules for folder rules. Show the result, wait for the user's explicit approval, then redeem the token only with its action's tool and selector: move(target=the preview's target) for move_to_trash, archive and move_to_folder; set_read_state(state="read" or "unread") for mark_read or mark_unread; label(op="add" or "remove") for add_label or remove_label; delete_draft and unsubscribe under their own names.

A token is issued only for a complete, unprotected clean batch of at most 200 messages, or of at most approval_max_messages when limit asks for more (a bounded approval, run in chunks of at most 200); delete_draft takes at most 200 and unsubscribe at most 50. Any protected sender blocks the whole batch; read-state changes refuse Drafts and Sent. Item-level failures are left out before approval, in excluded_count, excluded_ids (at most 20), excluded_truncated and excluded_reasons; all excluded means no token. create_folder_if_missing=true on a missing Folders/ name returns folder_creation: the one token then binds creating that folder and the move set, and move creates it first.

Returns count, samples (search_mail's canonical handles; partial=true beside a token means only some stayed null), blocked, personal_provider_bypass_count (the batch relies on an approved sender exemption), estimated_calls (confirmations needed), token, expires_at and action_hash; without a token, reason or the blocked rows say why. Move, archive, delete_draft and unsubscribe previews add log_id: that record authorizes nothing and cannot be undone. A partial run may return resume=true and a single-use continuation_token for the same set: redeem it with the same tool and selector, with no new approval; it never widens the set, and its fixed 30-minute window (expires_at) starts at the first successful claim.

Input Schema

Name	Required	Description
`ids`	No	RFC Message-IDs from search_mail, including bare identifiers without a domain. Not IMAP UIDs. Pass exactly one of query and ids.
`limit`	No	Approve only the first clean messages, by folder and numeric UID: 1 to 200, or up to approval_max_messages for one bounded approval. Without it a batch above 200 gets no token. delete_draft and unsubscribe refuse it.
`query`	No	Filters selecting the complete matching set: folder, from_ (or from), to, subject, since and before. text refuses. Pass exactly one of query and ids.
`action`	Yes	One of move_to_trash, archive, move_to_folder, mark_read, mark_unread, add_label, remove_label, delete_draft or unsubscribe.
`params`	No	move_to_folder needs folder, with optional mark_read=false and create_folder_if_missing=false. add_label and remove_label need label. The others take none.

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 only declare readOnlyHint=true and destructiveHint=false; the description adds the substantive behavioral rules the agent actually needs: batch caps (200, 50 for unsubscribe, approval_max_messages with 200-message chunks), protected-sender blocking, Drafts/Sent refusal for read-state, partial issuance with excluded_count/ids/reasons, and that a log_id record 'authorizes nothing and cannot be undone'. It also discloses token lifecycle details (single-use, 30-minute continuation window starting at first successful claim, never widens the set).

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 correctly: purpose and the no-mutation guarantee come first, then when-to-use, then limits, then return fields. It is dense and sentence-heavy with nested parentheticals, but nearly every clause carries a distinct operational fact rather than filler; readability, not redundancy, is the only cost.

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 token-issuing gate in front of nine mutation actions, the description covers eligibility, refusal reasons, exclusions, partial/continuation redemption, and expiry — everything needed to call it correctly and interpret a no-token result. An output schema exists, yet the return fields (token, expires_at, action_hash, excluded_*, resume) are still explained, which is a bonus rather than a gap.

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-parameter meaning the schema can't express: the relationship between limit and approval_max_messages, the action-to-params binding (move(target=...), set_read_state(state=...), label(op=...)), and the special create_folder_if_missing=true path that returns folder_creation and binds folder creation into the same token.

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 — 'Preview one change to existing mail' — and immediately bounds the effect with 'changes no mail'. It also distinguishes itself from the rule-preview sibling by name ('use preview_rules for folder rules'), so an agent can route without opening 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?

Explicitly enumerates the triggering cases (move to Trash/Archive/folder, read-state or label change, unsubscribe, draft deletion) and the exclusion (folder rules go to preview_rules). It goes further and prescribes the workflow — show result, wait for explicit approval, then redeem the token with the matching tool and exact selector for each action — leaving nothing to inference.

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