mcp-proton-mail

Overview Schema Source Related Servers Discussions Admin

Preview a folder rule (beta)

preview_add_rule

Read-only

Preview a custom INBOX folder rule before saving it. Returns the normalized rule and a single-use approval token without changing anything.

Instructions

Beta: Preview saving one custom folder rule that this server applies to INBOX; returns the rule and a single-use token, and changes nothing.

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

Use it for a rule this server applies to INBOX whenever preview_rules and apply_rules run, or the operator's optional timer; use preview_sieve_filter when the user wants Proton itself to file mail as it arrives, and preview_action for a one-off move. Show the rule and obtain explicit user approval before add_rule. Saving moves no mail; list_rules shows the existing rules.

The rule model is preview_sieve_filter's: conditions are 1 to 10 objects such as {"field": "subject", "contains": "invoice"}; from and to match each address, subject the decoded header, case-insensitively. A saved rule runs after every existing rule (the first match wins). mark_read applies when apply_rules runs it; the timer never marks mail read. include_matches=true adds a read-only count and samples from one search over at most 200 newest INBOX candidates.

Returns the normalized rule, rule_sha256, the same rule as a Proton Sieve script (informational, for Proton's own filter settings) with script_sha256, apply, token, expires_at and action_hash. A name an existing rule uses, in any letter case, refuses. With 20 saved rules the store is full: apply.available is false and add_rule refuses.

Input Schema

Name	Required	Description	Default
`name`	Yes	A name for the rule. A name an existing saved rule uses, in any letter case, refuses.
`match`	No	all needs every condition to match; any needs one.	all
`folder`	Yes	An existing real Folders/ name, as search_mail reports it.
`mark_read`	No	Also mark matching mail read.
`conditions`	Yes	1 to 10 objects, each {"field": "from"\|"to"\|"subject"} plus exactly one of contains or is.
`include_matches`	No	true adds a read-only count and samples of current INBOX matches.

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?

Goes well beyond the readOnly/destructive annotations: discloses beta unreliability, the single-use token with expires_at, the 20-rule store cap that makes apply.available false and add_rule refuse, case-insensitive name collisions, first-match-wins ordering after existing rules, and that mark_read applies only under apply_rules, never the timer. It also bounds the cost of include_matches (one search over at most 200 newest INBOX candidates).

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?

Beta status, effect, and the never-mutates guarantee are front-loaded, and the routing alternatives follow immediately. It is long, and "changes nothing" is restated later as "Saving moves no mail" — small redundancy for a dense but well-ordered description.

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 preview/mint-token tool the agent needs the token lifecycle, the downstream add_rule dependency, the capacity ceiling, and the match semantics — all present, even though an output schema already documents return shape. Nothing an agent needs to call this correctly and interpret the result 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?

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the condition model the schema only gestures at — 1-10 objects, field/contains-or-is, from/to matched per address, subject against the decoded header, case-insensitive. It does not add much for match or folder beyond what the schema already says.

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 saving one custom folder rule") plus the scope ("this server applies to INBOX") and the key guarantee ("changes nothing"). It also distinguishes itself from preview_sieve_filter, preview_action, and add_rule by name, so an agent can route without opening 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 when-to-use for the server-side rule engine, an explicit alternative (preview_sieve_filter when the user wants Proton to file mail itself; preview_action for a one-off move), and a required workflow step (obtain explicit approval before add_rule). list_rules is named as the read path for existing rules.

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