Proton Safe MCP

Overview Schema Source Related Servers Discussions Admin

List Proton messages

list_messages

Read-onlyIdempotent

List newest-first message metadata for a folder to browse or triage. Includes sender, subject, date, unread state, size. Does not mark messages as read.

Instructions

List newest-first message metadata for one folder. Use it to browse or triage a folder; to find messages by keyword use search_messages instead, and to obtain a body use read_message with a UID returned here. Each entry carries uid, sender, recipients, subject, date, message_id, unread state, and size, and never a body or attachment bytes. Fetches use BODY.PEEK, so listing never marks a message as read.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of messages to return, newest first. Defaults to 20. Older messages are simply omitted: there is no continuation cursor, so reach them with search_messages rather than by paging.
`folder`	No	Folder to list, spelled exactly as list_folders reports it. Defaults to INBOX. An unknown name is refused rather than falling back to INBOX.	INBOX
`unread_only`	No	Return only messages currently flagged unread. Defaults to false. The flag is read, never written: listing leaves every message's unread state unchanged.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.3.0Sep 16, 2026

addedInput schema / properties / folder / description

Added value: +"Folder to list, spelled exactly as list_folders reports it. Defaults to INBOX. An unknown name is refused rather than falling back to INBOX."

addedInput schema / properties / limit / description

Added value: +"Maximum number of messages to return, newest first. Defaults to 20. Older messages are simply omitted: there is no continuation cursor, so reach them with search_messages rather than by paging."

addedInput schema / properties / unread_only / description

Added value: +"Return only messages currently flagged unread. Defaults to false. The flag is read, never written: listing leaves every message's unread state unchanged."

First observedv0.1.0Aug 29, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds concrete behavioral details beyond them: fetches use BODY.PEEK so listing never marks messages as read, and there is no continuation cursor (a real limitation). This is exactly the kind of contextual disclosure that helps an agent predict side effects and plan calls.

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

Conciseness5/5

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

Three sentences, each earning its place: the first states purpose and scope, the second routes to alternatives, the third details the returned metadata and the non-mutating behavior. Front-loaded with the core purpose, no fluff or repetition.

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?

With an output schema present and annotations covering safety, the description fills the remaining gaps: what fields are returned (metadata list), what is never returned (body/attachments), the side-effect-free behavior, and the lack of a continuation cursor. An agent has everything needed to call this tool correctly and to decide between it and siblings.

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 description coverage is 100%, and the schema entries are themselves detailed (limit explains no-cursor behavior, folder requires exact spelling, unread_only is read-only). The tool description adds no parameter-specific information beyond what the schema already provides, so the baseline of 3 is appropriate.

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 description opens with a specific verb and resource ('List newest-first message metadata for one folder'), then immediately differentiates from siblings by naming search_messages and read_message as alternatives for other needs. It also states what entries carry and never carry, making the tool's purpose unambiguous.

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 states when to use this tool ('to browse or triage a folder') and when not to ('to find messages by keyword use search_messages instead', 'to obtain a body use read_message with a UID returned here'). Also clarifies that older messages are not reachable via paging and require search_messages. No inference needed.

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

Deploy Server