mcp-proton-mail

Overview Schema Source Related Servers Discussions Admin

Preview applying folder rules (beta)

preview_rules

Read-only

Preview which INBOX messages saved folder rules would move, with per-rule counts and skipped senders. Get a single-use approval token for a batch without changing mail.

Instructions

Beta: Preview which INBOX mail the folder rules would move now, skipping protected senders, and return a single-use token for one batch; changes no mail.

The rules engine is not fully reliable yet; preview first and check the results.

Use it when the user asks to apply the folder rules, which list_rules shows; it is for manual use only. Show per-rule counts, samples and skipped senders, wait for the user's explicit approval, then call apply_rules with the token. Use preview_action for a one-off change. It does not edit Proton's own filters.

A token covers one batch of up to limit reviewed matches; remaining counts what is left, and further batches need separate approval. Saved rules (add_rule) follow the packaged ones and report their name, conditions, match and mark_read; a saved rule with mark_read=true marks its own matches read. A message with inconsistent sender copies or ambiguous label memberships is left out of the batch and token and reported in excluded_count, excluded_ids, excluded_truncated and excluded_reasons; total_matches counts it, remaining does not. All excluded means no token.

The call budget is 20 seconds (or the shorter configured budget). When reviews are slow, a call may review one whole batch of a single rule, so each rule needs its own approval and order holds only within a rule; a deadline without a complete batch returns partial=true and no token. Pass next_cursor as cursor with the same options to continue. A call that fails keeps the cursor it was given, so retry with it; a reply spends it. Cursors expire after ten minutes or restart and never authorize changes.

Returns per-rule counts and samples, total_matches, batch_count, remaining, partial, total_is_exact, reason, token, expires_at, action_hash, next_cursor and excluded_*. Other refusals end the call.

Input Schema

Name	Required	Description	Default
`limit`	No	Reviewed matches this batch's token may cover, 1 to 200.
`order`	No	Which matches come first, by INTERNALDATE then UID.	oldest
`cursor`	No	next_cursor from the previous call, with the same options. A reply spends it and it lasts ten minutes; if it came back null, start a fresh preview.
`folder`	No	Only INBOX is accepted; any other folder is blocked, with no token.	INBOX
`mark_read`	No	Also mark the moved messages read.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 2, 2026

TDQS

A4.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false, and the description is consistent with them, adding substantial context beyond them: single-use tokens, ten-minute expiry, a 20-second call budget, partial=true with no token on deadline, per-rule approval granularity, and exclusion handling. This is rich behavioral disclosure that goes well past the safety hints.

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

Conciseness3/5

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

Purpose and usage are front-loaded, but the body is five dense paragraphs and the final list of return fields (total_matches, batch_count, token, expires_at, next_cursor, excluded_*) duplicates the output schema. Some phrasing is compressed to near-opacity, such as 'A reply spends it' and 'Other refusals end the call,' costing more in parsing than it saves in length.

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 token-gated two-step preview with budgets and exclusions, the description covers nearly everything an agent needs: approval gating, batching, continuation, and failure retry semantics. Remaining gaps are small, such as the unclear relationship between the tool's mark_read parameter and a saved rule's own mark_read attribute.

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 meaning the schema does not: limit bounds what a token covers, cursor continuation must reuse the same options and shares the token's single-use/expiry semantics, and order only holds within a rule when batches split. The only muddiness is the saved-rule mark_read=true sentence, which sits close to this tool's own mark_read parameter without clearly separating them.

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: preview which INBOX mail the folder rules would move now, return a single-use token, and change no mail. It also names what it is not (preview_action for one-off changes, apply_rules for the actual move), so an agent can distinguish it from siblings without opening a 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?

Explicit routing: use when the user asks to apply folder rules (visible via list_rules), show per-rule counts and samples, wait for explicit approval, then call apply_rules with the token. It also excludes preview_action and notes it does not edit Proton's own filters, giving both when-to-use and when-not-to-use guidance.

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