mcp-proton-mail

Overview Schema Source Related Servers Discussions Admin

Save an attachment to a file

save_attachment

Saves one email attachment as a new file in an allowed folder (max 25 MiB) without changing the mailbox; use to keep a file or when reading is refused.

Instructions

Save one attachment as a new file in the allowed folder, at most 25 MiB; nothing in the mailbox changes.

Use it when the user wants to keep a file, or for a file read_attachment refuses. To put an attachment in a draft, create_draft's attachments_from copies it directly, though a saved filename also works in attachments. Take attachment, the index, from list_attachments. It needs no preview.

The only place it can write is the folder in PROTON_MCP_ATTACHMENTS_DIR, by default a private per-user folder. An existing file is never overwritten: each call writes a new file, and the result's filename says the name used. The file is private to this user and not executable; removing it is manual.

Returns saved, filename, index, type, size and sha256. Refuses a file over 25 MiB, a filename that is not one plain name, or an allowed folder that cannot be used.

Input Schema

Name	Required	Description
`filename`	No	One plain file name; by default the sender's cleaned name.
`attachment`	Yes	The attachment's index from list_attachments, counted from 1.
`message_id`	Yes	The message's RFC Message-ID, as search_mail returns it, such as <a@example.test>. Not an IMAP UID.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 2, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, and the description explains the non-obvious consequences: writes go only to PROTON_MCP_ATTACHMENTS_DIR, existing files are never overwritten so each call produces a new file, the result filename reports the name actually used, files are private/non-executable, and cleanup is manual. It also lists the three refusal conditions, which is behavior an agent needs 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 the action and its guardrails, and every sentence carries operational content (limits, alternatives, side effects, refusals). It is on the longer side for a three-parameter tool, with a slight overlap between 'nothing in the mailbox changes' and the folder-only write constraint, but nothing is filler.

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 write-to-disk tool with an output schema covering saved/filename/index/type/size/sha256, the description supplies everything else an agent needs: size ceiling, destination folder resolution, no-overwrite semantics, permissions, and failure modes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all three parameters are documented in the schema already. The description adds the provenance of 'attachment' (the index from list_attachments) and reinforces the plain-name constraint on filename, but this largely restates schema text, so baseline 3 is right.

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 names a specific verb and resource ('Save one attachment as a new file'), plus scope limits ('in the allowed folder', 'at most 25 MiB') and a non-effect ('nothing in the mailbox changes') that separates it from read_attachment and create_draft.

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?

It gives explicit when-to-use ('when the user wants to keep a file, or for a file read_attachment refuses') and names the alternative path for drafts ('create_draft's attachments_from copies it directly, though a saved filename also works'). It even states where the index comes from (list_attachments) and that no preview step is needed.

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