Proton Suite Agent

Search emails

proton_search_emails

Read-onlyIdempotent

Find specific emails in a Proton Mail mailbox by searching keywords across any field or limiting to subject, sender, recipient, or body. Refine results with date ranges or unread status.

Instructions

Keyword-search emails in a mailbox. Filter by text in any field, or restrict to subject/from/to/body. Combine with date range and unseen flag. Returns newest matches first, up to 'limit'. Use 'text' for a broad 'anywhere' match.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	No	Keyword to search for
`since`	No	ISO date — only messages on/after this date
`before`	No	ISO date — only messages before this date
`fields`	No	Which fields to search. 'text' = anywhere.
`mailbox`	No		INBOX
`to_address`	No	Restrict to messages to this address
`unseen_only`	No	Only return unread messages
`from_address`	No	Restrict to messages from this address
`response_format`	No	markdown table, json, or concise bullet list (fewer tokens)	markdown

Output Schema

TableJSON Schema

Name	Required	Description	Default
`count`	Yes
`items`	Yes
`mailbox`	Yes
`matched`	Yes
`has_more`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.6.0Sep 30, 2026

addedInput schema / properties / response_format / description

Added value: +"markdown table, json, or concise bullet list (fewer tokens)"

changedInput schema / properties / response_format / enum

Previous value: -[
-  "markdown",
-  "json"
-]New value: +[
+  "markdown",
+  "json",
+  "concise"
+]

First observedv0.8.0Jul 28, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), and the description adds real behavioral context beyond them: results are ordered newest-first and capped by 'limit'. It stops short of stating default mailbox scope beyond the bare word 'mailbox' or any pagination continuation behavior.

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?

Four short sentences, front-loaded with the core action and then the filtering dimensions; no filler. Slightly list-like rather than explanatory, but every sentence carries information.

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?

An output schema exists, so return-value shape needn't be described, and the description still notes ordering and the limit cap. With 10 parameters and no required ones, the coverage is adequate, though the bare 'mailbox' parameter is never explained in either the schema or the description.

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 80%, so the schema carries most parameter meaning and the baseline is 3. The description does clarify that field targeting can be narrowed to subject/from/to/body and that 'text' means anywhere, but adds little syntactically beyond what the schema descriptions already say.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Keyword-search emails in a mailbox') and enumerates the filterable dimensions, so the agent knows exactly what the tool does. It does not name or contrast with the closest sibling, proton_list_emails, so sibling differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: search when you need keyword matching, list when you don't. The description gives useful in-tool guidance ('Use text for a broad anywhere match') but never states when to prefer this over proton_list_emails or any other sibling, and offers no exclusions.

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

Deploy Server