A
licenseNot graded
qualityC
maintenanceEnables AI clients to interact with ProtonMail accounts through the Proton Bridge using SMTP and IMAP protocols. Provides email management capabilities via secure local bridge connections.
27
MIT
proton-bridge-mcp
by Considus
This server gives an AI assistant local, privacy-preserving read, organize, and carefully-gated send access to your Proton Mail (or other IMAP/SMTP mailboxes) via the Proton Mail Bridge. Your mail never leaves your machine, and all mutating actions require explicit confirmation and are logged.
Read and Search Mail: List folders, check status, poll for new messages. Search by sender, subject, text, date range, unread/starred status across single or all folders. Retrieve full message bodies and headers (including SPF/DKIM/DMARC verdicts). Find complete conversation threads, including messages with attachments.
Handle Attachments: List attachments, distinguishing documents from inline images. Extract text from PDFs, CSVs, JSON, and other files inline. View images directly. Save attachments to disk (ephemeral by default) and purge them.
Organize Mail: Mark messages read/unread/starred. Apply or remove labels, individually or in bulk. Move messages to folders or Trash, with bulk support. Create, delete, and manage folders and labels.
Compose and Send Mail: Create, update, delete, and send drafts. Reply, reply all (removing your own addresses from Cc), forward, and send new emails—all gated with
confirmed=true. Unsubscribe using List-Unsubscribe headers.Safety and Control: Every mutating tool offers
dry_runpreview. Strict UIDVALIDITY checks prevent acting on stale UIDs. Recipient addresses seen only in message bodies are refused as recipients to prevent injection. File attachments are restricted to allowed directories. Rate limits cap sending and organizing actions. Modes:readonly(no changes),organise(no sending), andfull. An audit log records all modifications (without logging message bodies).
Provides tools for reading, searching, organizing, and sending Proton Mail via the Proton Mail Bridge, including attachment handling, label/folder management, drafts, replies, and confirmation-gated sends.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@proton-bridge-mcpWhat's new in my inbox since yesterday?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Proton Bridge MCP
Give any AI assistant read, organise and carefully-gated send access to your Proton Mail, without handing your mail to anyone.
Proton is end-to-end encrypted, which is the whole point of it, and it's also why there's no API to plug an assistant into. Your mail is only readable on your own machine. Proton Mail Bridge is the piece that decrypts locally and speaks ordinary IMAP and SMTP to 127.0.0.1, so with Bridge in place this server never has to send your mail anywhere at all.
Unofficial, and not affiliated with or endorsed by Proton AG.
Docs · Install · Security · FAQ
What it can do
Search and read mail, pull attachments out and read them (including the text of PDF invoices), tag and file messages one at a time or in batches, reply in thread, and send or forward behind a confirmation step.
Anything that sends takes draft=true instead, which puts it in your Drafts for you to look at. That path needs no confirmation, because nothing goes anywhere.
Files can be attached to anything you send, though only from directories you've said are allowed. Reading any file on the machine and posting it out is how data walks off a computer, so the default is the attachments folder and widening it is your decision, not something an instruction in an email can talk it into.
Tool | What it does |
| Every folder and label, read live each time |
| Counts, plus the UIDVALIDITY every uid in that folder depends on |
| What has arrived since you last looked |
| Confirms a batch was handled |
| Search by text, sender, subject, date range, unread, starred; optionally report each message's other labels and folders |
| The same search across every folder and label, duplicates collapsed |
| Headers with SPF, DKIM and DMARC verdicts, and Proton metadata |
| Full headers and body |
| Real documents, kept apart from inline images and PGP keys |
| Pulls the text out, PDFs included |
| Hands back an image attachment so it can actually be looked at |
| Writes a file out, deleted again after 15 minutes unless you say otherwise |
| Deletes those files now |
| The whole conversation, and which messages carry documents |
| Read, unread, star or unstar many messages in one pass |
| One label onto many messages |
| Takes one label off many messages, gated |
| File or Trash many at once, gated |
| Replies with correct threading, gated |
| Same, with your own addresses stripped from Cc, gated |
| Writes into Drafts, never sends |
| Replaces a draft, keeping its threading |
| Moves a draft to Trash, gated |
| Sends a saved draft, gated |
| Reports how to unsubscribe, and can send the email form |
| Read, unread, star, unstar |
| Tags a message, leaves it where it is |
| Takes a label off, leaves the message where it is, gated |
| Files it somewhere else |
| New folder or label, gated |
| Deletes a label, messages keep their place and lose the tag, gated |
| The same for several labels at once, gated |
| Gated, and can carry attachments |
| Gated |
Three things it can't do, and won't pretend otherwise. Folders can be created but not deleted, because a folder is where a message actually lives and deleting one would have to decide what happens to the mail inside it, so that stays a job for the Proton app. Bridge has no access to Proton's server-side filters or auto-forwarding rules, so those stay a manual job in the Proton web app. And nothing here hard-deletes, the furthest it goes is Trash.
Watching for new mail
poll_folder hands back whatever has turned up since you last looked, which is what turns this from something that reads your mail when asked into something that can react to mail arriving.
The first poll on a folder returns nothing on purpose. It notes where the folder currently ends, so switching it on doesn't dump years of backlog into a conversation. It reads nothing as read either.
If you're doing something with each message that you'd rather not do twice, poll with advance=false. You get the batch and a checkpoint, the cursor stays where it was, and polling again hands you the same batch until you confirm with ack_folder. Crash halfway and you pick up where you left off instead of losing the lot. Confirming twice is harmless.
The cursor records the UIDVALIDITY next to the message number, so a folder that resyncs underneath you is spotted rather than acted on. When that happens it re-anchors to the current end and says so, because the alternative is replaying whatever those old numbers now point at.
Getting at attachments
Three ways in, for three different situations. read_attachment pulls the text out and is what you want almost always, invoices included, and nothing touches the disk. save_attachment writes the file out for anything that isn't text, and works if whatever you're using can read files off disk. view_attachment hands an image straight back so it can be looked at, which is the only route to a photo or a scan when the client can't reach the filesystem.
Images only for that last one, on purpose. Encoding a file to send it inline makes it a third bigger and drops it into the conversation as characters, and for a spreadsheet or a Word document that's a lot of context spent on something nothing can read. Images are different because they arrive as an image rather than as text, so they cost about what a picture costs and can actually be seen.
Searching everywhere
A message in Proton lives in one folder but also turns up under every label you've put on it, and again in All Mail. Sweep the lot naively and you get the same mail three times. search_all_mail keys on Message-ID instead, so you get one entry per message with the other places it appears listed underneath, and it scans All Mail last as a safety net rather than treating it as a source. Every hit carries the UIDVALIDITY of the folder it was found in, because those differ per folder and a uid without one isn't safe to act on.
UIDs go stale
IMAP identifies a message by a number that's only meaningful until the folder resyncs. When that happens the number quietly starts pointing at something else, which is how the wrong message gets filed or trashed. Every folder reports a UIDVALIDITY alongside its uids, and if you hand one back with a uid that no longer matches, the tool refuses and asks you to search again rather than acting on the wrong mail.
Conversations aren't messages
Worth knowing before you trust an answer about attachments. Proton's app groups mail into conversations and shows a paperclip if anything in the thread has one. IMAP hands over individual messages with no grouping at all. A reply sitting in your inbox can be completely empty while the original, filed somewhere else, is carrying the PDFs. That's why find_thread exists, and why "no attachments" from a single message is an answer worth checking.
Related MCP server: ProtonMail MCP Server
Things to actually ask it
Four that exercise different parts of it, and none of them need you to know a tool name.
"Find the invoices from my accountant this quarter and total them up." Searches, then opens the attachments and reads the text out of the PDFs. This is the one that justifies bundling a PDF library rather than telling you an invoice exists and leaving you to open it.
"What's arrived since I last checked, and what actually needs me?" Uses the checkpointed batch, so if it falls over halfway you get the same batch again rather than losing it. Poll with advance=false and nothing moves until you say so.
"File everything from Companies House into Admin, but show me the list first." A search, then a bulk move. The preview runs every check the real thing would, and the move needs confirming on top of it, because moving 50 messages somewhere you didn't intend is an afternoon.
"Draft a reply to Sam saying I'll confirm Monday. Don't send it." Goes to your Drafts and stops. That path needs no confirmation at all, because nothing has gone anywhere.
Other mail providers
Bridge is what this was built for, and it's the case with no alternative, since Proton has no API to point anything else at. The rest of it is ordinary IMAP and SMTP though, so it works against a normal mailbox too, which is useful if your business mail comes from a smaller host rather than Google or Microsoft.
Labels are the one place the two differ. Proton keeps them in their own namespace, so Marketing and Labels/Marketing both work and mean the same thing. An ordinary IMAP server has no such idea, so a label there is just another folder and tagging copies the message into it. The server works out which kind it's talking to rather than assuming, and if the name matches nothing it tells you what does exist.
Set the hostname and ports to whatever your provider gave you. There's no autodiscovery here. Nothing guesses the server name from your email domain, and there's no lookup of the usual mail. records, so you enter the exact values from your provider's IMAP/SMTP settings page, for example mail.lcn.com with its IMAP and SMTP ports. Once you've typed the name your operating system resolves it to an address the normal way. What isn't automated is working out which name to use. Security is worked out from the port, 993 and 465 mean TLS from the first byte, 143 and 587 mean it gets negotiated, and you can say which explicitly if your host is unusual. Plain unencrypted connections aren't offered, since sending your password in clear isn't a trade worth making.
Go in with your eyes open on one thing. Every guarantee in Security still holds except the first one, because your mail now lives on a server you don't control and travels over the internet to get here. That's a fair trade if the alternative is no assistant access at all, it just isn't the same promise.
Before you start
You need Proton Mail Bridge installed, signed in, and running. Bridge is a paid feature, so a free Proton account can't use this. Open Bridge and find Mailbox details, that's where the hostname, ports, username and password come from. Bridge picks its own port numbers, they aren't always 1143 and 1025, so read them rather than assuming.
You won't need to install Python first if you follow the uv route, it fetches its own. Going the plain-Python route instead, you'll want Python 3.9 or newer. Either way, two small packages go into a local virtual environment, so they don't touch anything else on your system: pypdf reads the text out of PDFs, and keyring stores your password in the credential store on Linux and Windows. macOS has its own Keychain command built in, so keyring is optional there, but installing it does no harm.
Install
It goes on this computer, the same machine as Bridge and your assistant. A cloud AI session won't do, because its commands run in a sandbox on someone else's machine, where Bridge isn't, and nothing ends up installed here.
Clone it somewhere permanent, a folder in your home directory is right. Your assistant's config will point at this exact path, and the settings, audit log and saved attachments live next to the server, so a folder that later moves is a connection that breaks. Not Downloads, not a temp folder, not anywhere a cloud drive syncs.
Both routes finish the same way. setup.py opens a small page in your browser, served from your own machine on a random port behind a single-use link. It shuts itself down when you're finished and it never logs anything you type. Copy the values across from Bridge, and it'll test both connections before it saves a thing. Your password goes into your computer's secure credential store, never into a file.
Run it again any time. It notices you've set it up before, fills in what it already knows, and a blank password field means keep the one you've got.
Have an assistant do it
Paste this into an AI assistant that runs shell commands on this computer, Claude Code or a desktop assistant with terminal access, not a chat on a website, whose commands run on a server far from your Bridge. Read what it proposes before you let it run.
Please install the Proton Bridge MCP server from https://github.com/Considus/proton-bridge-mcp
on this computer, following the Install section of its README exactly. Clone it into a permanent
folder in my home directory, create the virtual environment with pypdf and keyring installed,
then run setup.py using that environment's own Python, and tell me the local link it prints so
I can finish setup in my browser. Run the commands one at a time, not chained together, and show
me each one before you run it.Or run the commands yourself
In its own terminal, that's Terminal on macOS, PowerShell on Windows.
You'll need git and uv, both free. Macs and most Linux machines have git already; Windows has neither, and winget install Git.Git followed by winget install astral-sh.uv in PowerShell puts that right, then open a fresh PowerShell window so they're found.
macOS and Linux
git clone https://github.com/Considus/proton-bridge-mcp.git
cd proton-bridge-mcp
uv venv .venv --python 3.12
uv pip install --python .venv/bin/python pypdf keyring
.venv/bin/python setup.pyWindows (PowerShell)
git clone https://github.com/Considus/proton-bridge-mcp.git
cd proton-bridge-mcp
uv venv .venv --python 3.12
uv pip install --python .venv\Scripts\python.exe pypdf keyring
.venv\Scripts\python.exe setup.pyRun each line on its own rather than chaining them together. The stock Windows PowerShell doesn't understand && between commands, and a line that half-works is harder to unpick than five that ran one at a time.
That last line matters. Setup runs with the environment you just built, which is where keyring went, and that's how your password reaches the credential store on Windows and Linux. The system's own Python doesn't have it and can't save the password there.
No uv? Use plain Python, 3.9 or newer. On macOS and Linux that's python3 -m venv .venv then .venv/bin/python -m pip install pypdf keyring. On Windows it's python -m venv .venv then .venv\Scripts\python -m pip install pypdf keyring. Then run setup with the environment's Python exactly as shown. Drop pypdf and you lose PDF text extraction. Drop keyring and you lose saved-password storage on Linux and Windows.
Connect it to your assistant
When setup finishes it hands you a second prompt. Paste that into whichever assistant you want reading your mail, Claude, Cursor, Windsurf, Zed, Codex CLI, Gemini CLI, VS Code Copilot, whatever you're using.
It works this way round on purpose. Every client keeps its MCP config somewhere different, under a different key, and those locations move. An assistant already knows where its own config lives, so asking it beats shipping a list of paths that quietly rots. The prompt carries no password and no settings, only the name, the command and the path.
Restart the app afterwards, MCP servers load at startup.
When something goes wrong
The connection is refused. Bridge isn't running, or it isn't on the ports this is looking at. Bridge picks its own port numbers per install and they aren't always 1143 and 1025, so open it, read the real ones out of Mailbox details, and set PROTON_IMAP_PORT and PROTON_SMTP_PORT to match.
The login is rejected. This is the common one by a distance. Bridge has a password of its own, shown in Bridge under Mailbox details, and it isn't your Proton account password. The account password is refused every time, and what you get back looks like a broken install rather than the wrong credential.
It says setup is required. Run python3 setup.py and let it walk you through. Doing it by hand instead, set PROTON_USER to the address Bridge shows you, then supply the Bridge password either through the PROTON_BRIDGE_PASSWORD environment variable or through your computer's credential store.
A uid that worked ten minutes ago is refused. The folder resynced underneath you and those numbers now point at different mail, so the refusal is the tool doing its job rather than failing at it, described in UIDs go stale. Search again and act on the uid the search hands back, not the one you were holding.
An attachment you can see in Proton isn't there. Proton's app groups mail into conversations, IMAP hands over individual messages, and the reply sitting in your inbox can be completely empty while the original, filed somewhere else, carries the PDFs. find_thread is the way round it, and Conversations aren't messages is why.
It stopped and asked you before sending. Working as designed, not a fault. Nothing leaves the machine without you saying so, which is Nothing goes out quietly.
Updating
There's no package and no installer, so there's nothing to download. The server runs as server.py out of the directory you cloned into, which makes an update a pull and a restart.
The restart is the part that catches people out. A stdio MCP server is a long-running process, and it reads server.py once, when the app starts it. Changing the file underneath a server that's already running does nothing at all, so quit the app properly and open it again. Closing the window isn't enough on macOS, and neither is closing the last tab on Windows if it leaves the app in the tray.
Releases are tagged, and the releases page on GitHub says what changed in each one and whether it affects you. Plenty of what lands here only matters on a mailbox that isn't Proton, so a release you can safely ignore is a normal outcome rather than a sign something went wrong. git pull puts you on the latest main, which is sometimes ahead of the newest tag.
Have an assistant do it
Paste this into an AI assistant that runs shell commands on this computer. It can do the pull, but it can't restart the app it's running inside, so the last step stays yours.
Please update my Proton Bridge MCP server. Find where it's installed by reading the path out
of this app's MCP config rather than guessing it, run git pull in that folder, and tell me what
changed and which release that puts me on. Don't edit any of my settings or touch settings.json,
state.json or audit.log. Then remind me to quit this app completely and open it again, because
the server only reads server.py at startup.Or run the commands yourself
In the folder you cloned into.
cd proton-bridge-mcp
git pullWhere things live
Passwords sit in your operating system's credential store, Keychain, Credential Manager or Secret Service depending on what you're running. Everything else goes in settings.json next to the server, owner-readable only, no secrets in it. Environment variables override the file if you'd rather configure it that way, and .env.example covers the ones most people need. The rest are named where they come up in this README.
Using it writes three more files, all next to the server and all owner-readable only. state.json keeps polling cursors and rate counters, audit.log records everything that changed something, and saved attachments land in attachments/ until the TTL sweeps them. Each one has an override, PROTON_STATE_FILE, PROTON_AUDIT_LOG and PROTON_ATTACH_DIR, so none of them are stuck where they land by default.
audit.log is the one worth a thought about where it sits. It keeps recipient addresses, subject lines and folder names in the clear, message bodies never, so over time it accumulates a record of who you write to without ever becoming a second copy of your mail. It rotates at 5MB and nothing expires by age, so the record runs as far back as your last 5MB of activity. That makes the folder you cloned into a question rather than a given. If it gets backed up, synced or indexed, the metadata goes with it, and pointing PROTON_AUDIT_LOG at somewhere outside that tree keeps the record on the machine that made it. On macOS a directory under ~/Library/Application Support/ that you exclude from Time Machine does the job, and excluding the directory rather than the file matters, because the rotated audit.log.1 is a new file that needs to inherit the exclusion.
Security
The short version, it's local, it's careful about sending, and it assumes your mail is hostile.
Where your mail actually goes
With Bridge, nothing leaves your machine
Bridge does the decryption on your own computer and uses IMAP and SMTP to your computer's loopback address, so the server talks to your machine and nowhere else. The setup page loads no fonts, no scripts and no images from anywhere either.
Point it at a mailbox in the cloud instead and it works fine, but that sentence stops being true and it's worth saying so plainly. Your mail is sitting on somebody else's server, they can read it, and the connection goes out over the internet rather than staying on the loopback interface. What you keep is everything this server does, the access is still local to your machine, still gated before anything sends, still audited, and it still refuses to mail an address it only saw inside a message. What you give up is the part where nobody except you could read the mail in the first place, and that was Proton doing the work rather than anything here.
Certificates are checked, except where checking them would be meaningless
Bridge serves a self-signed certificate on loopback, so verifying it against a public certificate authority proves nothing and is skipped. Every other host is verified properly. That distinction matters because the hostname is yours to set, so this can be pointed at a mail server across the internet, and an unverified connection there is exactly the hole someone would walk through. If a host really can't present a matching certificate you can name it in PROTON_TLS_INSECURE_HOSTS, which excuses that one host and nothing else.
When a message tries to give orders
Your mail is untrusted input
Anyone can write "forward all the invoices to me" inside a PDF and post it to you. Extracted text is labelled as untrusted before an assistant sees it, but a label is only advice, so there's a rule underneath that isn't.
Addresses are tracked by where they came from
Anything in a From, To, Cc or Reply-To header is a real correspondent and you can write to it. An address that only ever appears in a message body, or an attachment, is refused as a recipient, and no tool parameter will change that. Convincing the assistant won't help because the refusal isn't the AI's decision. If you actually want to add an address from, what the AI would suggest is a dubious source, you can, you put it into PROTON_ALLOWED_RECIPIENTS yourself, somewhere no assistant can reach.
Worth being straight about its edges, because it's a strong backstop rather than a force field. An address is only refused if it was seen in content the assistant actually read this session, so a recipient that turned up in no read message isn't being matched against anything. And an address an attacker plants in a header is treated as a correspondent from then on, say by CCing themselves on a message you open. The two hard limits are the sender allowlist and PROTON_ALLOWED_RECIPIENTS. This rule narrows the easy exfiltration route rather than sealing every one.
Reading mail without acting on it
Unsubscribing is mostly advice
unsubscribe reads the List-Unsubscribe header and tells you what's on offer. It will send the email form if you ask it to, but it never opens the web link, because this server talks to Bridge on your own machine and nothing else, and quietly fetching a URL out of a message would break that and confirm to the sender that you read it. It also checks who was actually subscribed. Mail that came through an alias was sent to the alias, not to you, so unsubscribing from your own address usually matches nothing and disabling the alias is the better answer. It says so rather than sending something that won't work.
Checking whether mail is what it says it is
get_headers reports the SPF, DKIM and DMARC verdicts the receiving server reached, and points out a From domain that doesn't match the Return-Path. It won't cry wolf over your own aliases though. Mail forwarded through SimpleLogin always has a Reply-To and Return-Path that differ from the sender, so it says as much rather than flagging it, because a warning that fires on ordinary mail teaches you to ignore warnings.
Nothing goes out quietly
Replies keep an alias masked on their own
If a message came in through a SimpleLogin alias, reply answers the reverse-alias rather than the sender, and sends from your alias-owner address without being told to. Get that wrong by hand and you either unmask yourself or the reply bounces, so it isn't left to memory.
Mail can only go out as you
from_address is checked against an allowlist that starts as your own address and your alias-owner address, nothing else. An injected instruction can't make mail appear to come from someone else, and widening it means editing PROTON_ALLOWED_SENDERS yourself.
Sending always stops, and so does anything else you can't take back
Thirteen tools refuse to do the real thing unless the assistant passes confirmed=true, which it should only do after showing you what is about to happen.
Everything that puts mail on the wire, send, forward, reply, reply_all, send_draft and unsubscribe. Everything that destroys something, delete_draft, delete_label and bulk_delete_labels. And the changes that are tedious rather than impossible to undo, create_folder_or_label, bulk_move, remove_label and bulk_remove_label.
A preview is exempt, because a preview is harmless. dry_run=true needs no confirmation anywhere, and replying with draft=true needs none either, since a draft sits in your Drafts and goes nowhere.
The gate is a speed bump rather than a wall. An assistant that had been fully talked round could set the flag itself, which is exactly why the address rule above exists as well.
What's recorded, and what you can preview
Everything that changes something is logged
Sends, moves, labels, drafts, new folders, saved attachments, each one appended to audit.log as a single line of JSON, owner-readable only. It sits next to the server unless PROTON_AUDIT_LOG says otherwise, and Where things live is worth reading on why you might move it. Message bodies are never written, only their length, so the log tells you what happened without quietly becoming a second copy of your mailbox. Recipients and subjects are written in full though, because a log that says a send happened but not to whom is no use after something odd. Refusals are recorded too, which is the half you'd actually want. Turn it off with PROTON_AUDIT=0 if you'd rather.
Anything can be previewed first
Every tool that changes something takes dry_run=true. You get the exact message that would go out, or the actual subject and sender of the mail that would move, and nothing happens. A preview needs no confirmation, since a preview is harmless, but it still runs every check, so if the real thing would be refused the preview tells you that rather than showing you a comforting fiction.
Batches are narrower than they look
The bulk tools only accept explicit numbered messages, never "everything in this folder", and they stop at 50 a call. Bulk moves need confirming on top of the preview, because marking something read is easy to undo and moving 50 messages isn't.
Limits on what it can do at all
Three settings, not two
PROTON_MODE=readonly removes every tool that changes anything. PROTON_MODE=organise is the one most people probably want, it can file, label, tag and draft, but the tools that put mail on the wire aren't there at all. full is everything. These remove tools rather than guarding them, and a tool that isn't there can't be talked into running.
There's a ceiling on a bad hour
Sending is capped at 30 an hour and organising at 2000, both adjustable. The audit log tells you what happened after the fact, a limit stops it happening two hundred more times. Sends are capped far tighter than filing on purpose, since moving a thousand messages is tidying up and sending a thousand is an incident.
Attachments are files, not code
Nothing is ever executed. Saved files are confined to the attachments directory, written owner-only and never executable, and they delete themselves after 15 minutes. One thing to be aware of though, files written this way don't carry the quarantine flag your browser or mail client would add, so your operating system won't warn you about them. Don't open executables that arrived by email.
Tests
On macOS and Linux:
.venv/bin/python -m unittest discover -s tests -vOn Windows:
.venv\Scripts\python.exe -m unittest discover -s tests -vThey cover attachment classification, the write sandbox, the recipient rules and the MCP protocol itself. None of them need Bridge running or a real account.
Privacy Policy
There is no server on our side. Your mail goes from Proton to Bridge to this server and back again, all of it over 127.0.0.1, all of it on the computer in front of you. Considus runs nothing your mail passes through, so there is nothing for us to look at even if we wanted to, and no account to make, no telemetry, no crash reporting and no licence check that phones home.
What it reads
Whatever you ask it to, and only while it answers. Folder names, headers, message bodies and attachments, all read live over Bridge each time. There is no database and nothing is indexed, so what a tool read is in your assistant's conversation and nowhere else, and when that conversation goes it goes with it.
What it writes, and where
An audit log records anything that changed something, which is there so you can go back afterwards and see what was done in your name. It holds the tool, the time and the message it acted on, and never the body of a message or a note you wrote. It caps at 5MB and rotates, and PROTON_AUDIT=0 turns it off.
Saved attachments land in the attachments folder and nowhere else, unless you widen that yourself.
A settings file keeps the dull half of your setup, the mailbox address and the ports Bridge gave you.
A checkpoint file remembers how far the last poll got, so switching polling on doesn't replay a year of backlog at you.
All four sit next to the server on your own disk, they are yours, and you can delete any of them whenever you like. Nothing is kept anywhere else, because there is nowhere else, and that is also the answer on retention. We hold nothing, so we have nothing to keep or to delete on your behalf.
Your password is not in any of that
It goes to your operating system's credential store, Keychain on macOS and the keyring equivalent on Windows and Linux. Install the bundle instead of cloning and you can type it into the setup panel, in which case your assistant stores it the same way. Either route, it is never written to a file here, never written to the audit log, and never handed back to the model.
Nobody else gets any of it
No analytics, no error reporting, no third party of any kind, and nothing shared with Proton beyond the mail you were already sending them. The only connections this makes are to Bridge on loopback, and it will not fetch a web address it found inside a message even when that address is an unsubscribe link, because quietly reaching out to a host named in an email would confirm you read it.
If you want to ask about any of this
Write to privacy@considus.com, or open an issue at github.com/Considus/proton-bridge-mcp/issues. The Considus website policy covering considus.com itself is at considus.com/privacy, and it is a separate document because it covers a separate thing.
Support
This is free and stays that way. Apache 2.0 means you can take it, build on it, and ship it commercially without owing anything back, which is deliberate.
Something broken or behaving oddly, open an issue. Anything exploitable goes through GitHub's private reporting instead, described in SECURITY.md, not a public issue. For anything that doesn't fit either, including press and licensing, it's support@considus.com, and the rest of the ways to reach us are at considus.com/support.
If it saved you an afternoon, there's buymeacoffee.com/considus. If it didn't, opening an issue when something breaks is worth more than the coffee.
Licence
Apache 2.0. See LICENSE for the terms and NOTICE for the attribution you need to carry with it. The bundled fonts are licensed separately under the SIL Open Font License 1.1, in assets/fonts/OFL.txt.
Available Tools
34 toolsack_folderAcknowledge poll checkpointAIdempotent
Commit a checkpoint returned by poll_folder with advance=false. Repeating it is harmless.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Default INBOX. | |
| checkpoint | Yes | Exactly as poll_folder reported it. |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint and destructiveHint, and the description adds the 'advance=false' semantic (no state advancement) and reinforces harmless repetition, offering context beyond the structured annotations.
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?
Two sentences, fully front-loaded with the core action, and zero filler words. Every sentence earns its place.
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 simple 2-parameter ack operation with no output schema, the description covers purpose, usage context, and idempotency behavior completely. No additional details are necessary.
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%, with both parameters documented. The description only reiterates the checkpoint source already described in the schema, adding no extra parameter semantics.
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 clearly states a specific verb ('Commit') and resource ('checkpoint returned by poll_folder'), and distinguishes itself from siblings by referencing the exact source and advance=false behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly specifies when to use the tool (checkpoint from poll_folder with advance=false) and adds that repetition is harmless, which is useful usage guidance. However, it doesn't explicitly name alternatives or when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
apply_labelApply a labelAIdempotent
Tag a message with an existing label. The message stays where it is.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| label | Yes | An existing label. On Proton the Labels/ prefix is optional; elsewhere this is an ordinary mailbox name. | |
| folder | No | Source folder, default INBOX. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| uidvalidity | No | UIDVALIDITY reported alongside the uid. Pass it back so a mailbox resync cannot make this act on the wrong message. |
TDQS
A3.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'The message stays where it is,' which clarifies that the tool does not move the message—information not contained in the annotations. This is a useful behavioral detail beyond the non-destructive and idempotent hints already provided.
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?
Two short sentences, action front-loaded with no wasted words. Every word earns its place, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core operation but lacks guidance on alternatives, prerequisites (e.g., label must exist), and potential error conditions. Given the tool has 5 parameters and no output schema, this is minimally adequate but not comprehensive.
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 80%, so the schema already carries most parameter documentation. The description itself adds no parameter-specific meaning, staying at the baseline expected when the schema does the heavy lifting.
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?
Clearly states the action 'Tag a message with an existing label' with a specific verb and resource. It distinguishes from related tools like move_to_folder by noting the message stays in place, making the 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as bulk_apply_label or remove_label. The note that the message stays provides a contrast to moving, but it does not tell the agent when to choose this over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bulk_apply_labelApply a label in bulkAIdempotent
Apply one existing label to many messages. Messages stay where they are.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uids | Yes | Explicit message uids. No wildcards. | |
| label | Yes | An existing label. On Proton the Labels/ prefix is optional; elsewhere this is an ordinary mailbox name. | |
| folder | No | Folder the uids belong to. Default INBOX. | |
| dry_run | No | Preview which uids would be affected, change nothing. | |
| uidvalidity | No | UIDVALIDITY for that folder; refuses on mismatch. |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the useful behavioral note that 'Messages stay where they are,' which is not captured by annotations. It also states 'one existing label,' implying the label must pre-exist. However, it does not explain behavior on invalid uids, missing labels, or return values. Given that annotations already cover readOnly/idempotent/destructive hints, the description contributes some but not rich additional context.
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?
The description is two short sentences, front-loaded with the main action and a clarifying note about message placement. Every word earns its place; no unnecessary detail or repetition.
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?
Given the tool's moderate complexity (5 parameters, no output schema), the description, combined with rich schema descriptions and safety annotations, is largely complete. It clarifies the core behavior (no move) and relies on the schema for parameter details. The only gap is the absence of any mention of return/result behavior, but that is not critical for a bulk action with no output schema.
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?
The input schema has 100% coverage with detailed descriptions for all parameters (uids, label, folder, dry_run, uidvalidity). The description adds no extra parameter semantics 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 states exactly what the tool does: 'Apply one existing label to many messages.' It is specific (apply label, bulk scope) and differentiates from sibling tools like bulk_move by noting 'Messages stay where they are.' This clearly distinguishes it from move operations and from single-label tools like apply_label.
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?
The description gives clear context: it is for bulk application of an existing label. However, it does not explicitly say when to use this tool versus alternatives (e.g., apply_label for single messages or bulk_move when moving is desired). The phrase 'Messages stay where they are' implies it is not a move, but there is no direct guidance or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bulk_delete_labelsDelete labels in bulkADestructiveIdempotent
Delete several labels in one pass. Messages keep their place and lose the tags. Labels only, GATED.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| labels | Yes | Label names. On Proton the Labels/ prefix is optional. | |
| dry_run | No | Preview each one, including how many messages carry it. Changes nothing. | |
| confirmed | No |
TDQS
A3.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint: true, readOnlyHint: false), so the bar is lowered. The description adds useful context: messages keep their place and only lose the tags, clarifying that labels are removed rather than messages. However, the cryptic 'GATED' note and the lack of explanation about the 'confirmed' parameter or confirmation workflow leave behavioral gaps. This is comparable to the TDQS example where annotations covered safety and description added scoping but not full behavior, so a 3 is warranted.
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?
The description is extremely concise: two sentences plus a short fragment ('Labels only, GATED.'). Every part contributes meaning: the core action, the effect on messages, and a scope restriction. Even the cryptic 'GATED' is short and might hint at a gated operation. No wasted words, and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters, one required, and no output schema. The description explains the primary action and effect, but it does not explain the confirmation workflow (the 'confirmed' parameter), when to use dry_run, or how this relates to single-label deletion. This is a destructive bulk operation, so the absence of guidance on using dry_run or confirming the deletion is a noticeable gap, making the description only minimally complete for the tool's complexity.
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 67% (labels and dry_run have descriptions, confirmed does not). The tool description does not add parameter-specific details beyond what the schema provides, aside from the general effect on messages. According to the baseline for good schema coverage, a 3 is appropriate; the description does not compensate for the undocumented 'confirmed' parameter.
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 clearly states the tool deletes multiple labels in one pass, with the specific verb 'Delete' and resource 'labels'. It distinguishes from sibling tools like bulk_remove_label (which removes labels from messages) by clarifying that messages keep their place and only lose the tags, and it restricts scope to 'Labels only.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use when you want to delete several label definitions. It does not explicitly name alternatives (e.g., delete_label for single labels or bulk_remove_label for removing label associations), but the effect described ('Messages keep their place and lose the tags') implies a different use case than these siblings. This is clear context with no exclusions, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bulk_markMark messages in bulkAIdempotent
Mark many messages read/unread/starred in one pass. Far cheaper than one call per message.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uids | Yes | Explicit message uids. No wildcards. | |
| action | Yes | ||
| folder | No | Folder the uids belong to. Default INBOX. | |
| dry_run | No | Preview which uids would be affected, change nothing. | |
| uidvalidity | No | UIDVALIDITY for that folder; refuses on mismatch. |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds minimal behavioral context beyond the bulk nature, and no contradiction with annotations is present.
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?
A single, front-loaded sentence that states purpose and cost benefit with zero wasted words. It is appropriately concise.
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?
Given the rich schema (5 params, 80% described) and annotations, the description is sufficiently complete for a simple bulk operation. It could mention dry_run or uidvalidity safety, but these are adequately captured in structured fields.
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 80%, so the schema carries most parameter semantics. The description only reinforces action values (read/unread/starred) without adding new meaning beyond the enum.
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?
The description clearly states the tool marks many messages read/unread/starred in one pass, using a specific verb and resource. It distinguishes from per-message operations by highlighting cost efficiency, but doesn't explicitly name the sibling 'mark' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Far cheaper than one call per message' implies use for bulk marking and provides clear context. However, it lacks explicit exclusion guidance or a named alternative for single-message marking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bulk_moveMove messages in bulkAIdempotent
File or Trash many messages at once. GATED: preview with dry_run=true, show the user, then call with confirmed=true.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uids | Yes | Explicit message uids. No wildcards. | |
| folder | No | Folder the uids belong to. Default INBOX. | |
| dry_run | No | Preview which uids would be affected, change nothing. | |
| confirmed | Yes | ||
| to_folder | Yes | ||
| uidvalidity | No | UIDVALIDITY for that folder; refuses on mismatch. |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond annotations: the required dry-run/confirmation gate is disclosed. This explains safe usage despite mutation (readOnlyHint=false) and non-destructive hint, making the tool's workflow transparent.
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?
Two concise sentences, front-loaded with purpose and gate. No filler or repetition of schema details.
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?
The gated workflow is clear, and annotations cover safety profile. However, no output schema and no explanation of return values or to_folder semantics leave some ambiguity for a 6-parameter tool.
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 covers 67% of parameters. Description adds meaning for dry_run and confirmed via the gating phrase, but the required to_folder parameter remains undocumented in both schema and description. No clear explanation of how 'Trash' maps to to_folder.
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?
Description uses specific verb+resource+scope: 'File or Trash many messages at once.' This clearly distinguishes it from sibling tools like move_to_folder (singular) and bulk_apply_label (labels, not moves).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly provides a two-step usage protocol: 'preview with dry_run=true, show the user, then call with confirmed=true.' It implies bulk use but does not explicitly state when to prefer singular alternatives like move_to_folder.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bulk_remove_labelRemove a label in bulkAIdempotent
Take one label off many messages at once. The messages stay where they are. GATED, like remove_label.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uids | Yes | Explicit message uids. No wildcards. | |
| label | Yes | The label to take off. On Proton the Labels/ prefix is optional. | |
| folder | No | Folder the uids belong to. Default INBOX. | |
| dry_run | No | Preview which uids would be affected, change nothing. | |
| confirmed | No | ||
| uidvalidity | No | UIDVALIDITY for that folder; refuses on mismatch. |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond annotations: 'The messages stay where they are' clarifies that the operation is non-destructive to message location, and 'GATED, like remove_label' signals a confirmation step. However, the gating mechanism is not explained, and the annotations already convey idempotent, non-destructive, and mutating traits. The description complements annotations without contradicting them.
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?
The description is very concise: three short sentences, each serving a purpose (purpose, non-destructive clarification, gating warning). It is front-loaded with the core action and avoids filler or repetition. Excellent economy of words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters and no output schema, the description does not fully explain the gating mechanism ('GATED') or the behavior of confirmed/uidvalidity, but these are partially covered by schema descriptions. The description is minimal and relies heavily on annotations and schema. It is sufficient for tool selection but not fully self-contained for invocation details, such as what precisely 'GATED' implies beyond the boolean parameter.
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 high (83%), so the baseline is 3. The description adds only marginal parameter context—'one label' and 'many messages' align with the label string and uids array—but it does not clarify confirmed, dry_run, or uidvalidity beyond what the schema already provides. It neither adds nor omits significant parameter meaning.
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 states the action clearly with a specific verb and resource: 'Take one label off many messages at once.' This distinguishes it from removing a single label (remove_label) and from adding labels (bulk_apply_label). The additional sentence 'The messages stay where they are' clarifies that this is not a move or delete operation, reinforcing the tool's scope.
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?
The description implies the use case (bulk operation on many messages) but does not explicitly mention alternatives or exclusions. The phrase 'GATED, like remove_label' provides a hint about a confirmation requirement and points to a sibling tool for analogy, but it doesn't say when to choose this over bulk_apply_label or remove_label. No explicit 'when not to use' guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_draftCreate a draftA
Write a draft into the Proton Drafts folder. Never sends. For a reply, pass in_reply_to (the original Message-ID).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | ||
| to | Yes | ||
| body | Yes | ||
| attach | No | Files to attach, by path. Only from the allowed source directories. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| subject | Yes | ||
| references | No | ||
| in_reply_to | No |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context: it writes to a specific folder and never sends. This goes beyond what annotations state and helps avoid misuse. It does not mention side effects or return values, but the core behavior is well covered.
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?
The description is three concise sentences, each adding essential information: the action, the 'never sends' guarantee, and the reply-specific parameter guidance. No fluff or redundancy; it is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description is quite sparse. It lacks guidance on required parameters like 'to' and 'subject', attachment handling, or what the tool returns. While annotations provide some context, the description does not compensate for the low schema coverage, leaving the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 25%, so the description must compensate. It explains the semantics of in_reply_to ('the original Message-ID') but does not clarify the other parameters (to, subject, body, cc, references, attach). Given the low coverage, the description is insufficient for full parameter understanding.
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 uses a specific verb ('Write') and a clear resource ('a draft into the Proton Drafts folder'), and explicitly states 'Never sends', which distinguishes it from send-related siblings. It also mentions a specific use case for replies, further clarifying its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance for a specific scenario: 'For a reply, pass in_reply_to (the original Message-ID)'. It also implicitly indicates when not to use it via 'Never sends', but does not explicitly mention alternatives like 'update_draft' or 'send'. Still, the guidance is clear enough for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_folder_or_labelCreate a folder or labelAIdempotent
Create a new label or folder. GATED: it changes your folder and label structure, so confirm the exact name and type with the user, then call with confirmed=true.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| name | Yes | Name only, no 'Labels/' or 'Folders/' prefix. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| confirmed | Yes |
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, and idempotentHint=true. The description adds behavioral context by noting 'it changes your folder and label structure' and the need for confirmation. This goes beyond annotations, though it doesn't detail edge cases like idempotency behavior.
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?
Two sentences, front-loaded with the main purpose, then the gating instruction. No wasted words, well-structured.
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?
The description covers the essential purpose and gating requirement. It omits explicit mention of dry_run in the text, but the schema covers that. For a simple creation tool with no output schema, this is sufficiently complete for an agent to use correctly.
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 has descriptions for name and dry_run, but kind and confirmed lack descriptions. The description adds meaning for 'confirmed' by requiring confirmed=true after user confirmation, and clarifies that 'name' and 'type' (kind) must be verified. This compensates for the 50% schema coverage.
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 clearly states 'Create a new label or folder' which is a specific verb+resource, and the sibling list shows other create actions like create_draft, so it distinguishes itself. It also mentions the gated nature, adding clarity.
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 the gating condition: 'confirm the exact name and type with the user, then call with confirmed=true.' This tells the agent when to use it and what prerequisite steps are needed, including the confirmation requirement. It also implies dry_run can be used without confirmation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_draftDelete a draftADestructiveIdempotent
Move a draft to Trash. GATED. Nothing here deletes permanently.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| folder | No | Defaults to your Drafts folder. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| confirmed | No | ||
| uidvalidity | No | UIDVALIDITY of the folder; refuses on mismatch. |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable context beyond annotations: it reveals the draft goes to Trash, is gated (likely requiring confirmation), and is non-permanent. This is useful despite destructiveHint being true. No contradiction with annotations.
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?
The description is brief and front-loaded with the main action. The one-word sentence 'GATED' is cryptic but impactful, and each phrase earns its place. Could be slightly clearer but overall efficient.
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 simple draft deletion tool, the description covers key behavior (to Trash, gated, non-permanent). The annotations provide destructive/read-only hints and schema covers parameters. No output schema exists, so return value details are not required. Adequate for safe usage.
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 60%, so many parameters already have descriptions. The tool description doesn't explain individual parameters, but the schema handles most of the burden. The word 'GATED' hints at the confirmed parameter but doesn't elaborate.
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 clearly states the tool moves a draft to Trash, which is a specific verb and resource. It distinguishes itself from siblings like delete_label or purge_attachments by clarifying it's about drafts and non-permanent deletion.
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?
The description implies this tool is for soft-deleting drafts to trash, and 'Nothing here deletes permanently' suggests not to use it if permanent deletion is intended. However, it doesn't explicitly name alternatives or state when to use it over other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_labelDelete a labelADestructiveIdempotent
Delete a label outright. Every message that carried it stays exactly where it is and simply loses the tag — no mail is deleted. Labels only; folders are where messages live and are not deletable here. GATED.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes | The label to delete. On Proton the Labels/ prefix is optional. | |
| dry_run | No | Preview it, including how many messages carry the label. Changes nothing, needs no confirmation. | |
| confirmed | No |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true), the description discloses a critical behavioral trait: 'Every message that carried it stays exactly where it is and simply loses the tag — no mail is deleted.' This adds important context that the destructive action is scoped to the label only, not the messages. The phrase 'GATED' also hints at a confirmation step, which aligns with the confirmed parameter.
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 concise sentences front-load the purpose and then add necessary behavioral context. No filler or redundancy. Every sentence earns its place, including the 'GATED' marker which signals an important workflow constraint.
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?
The description is quite complete for a simple deletion tool: it explains the effect on messages, distinguishes labels from folders, and hints at gating. However, the 'GATED' term is ambiguous and the confirmed parameter is not explained, leaving some gaps. Still, it provides sufficient context for an agent to select and invoke the tool correctly.
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?
The schema already describes label and dry_run, covering 67% of parameters. The description adds context for the label parameter by clarifying labels vs. folders, but it does not explain the confirmed parameter or how dry_run interacts with the gated confirmation. Since coverage is moderate and the description does not fully compensate, a score 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 states 'Delete a label outright' with a specific verb and resource. It also distinguishes this tool from folder operations by saying 'Labels only; folders are where messages live and are not deletable here.' This clearly differentiates from sibling tools like apply_label or bulk_delete_labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use this tool: for deleting labels, not folders. It explicitly notes that folders are not deletable here, implying a boundary. However, it does not mention alternatives like bulk_delete_labels for batch operations, so it lacks explicit 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.
find_threadFind a threadARead-only
Pull every message of a conversation from All Mail, showing which ones carry documents. ESSENTIAL: Proton's UI groups conversations but IMAP exposes single messages, so an inbox 'Re:' can look attachment-free while the thread's original holds the PDFs. Run this before concluding what a thread needs.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | No | A message in the thread (its subject is used). | |
| folder | No | Folder of that uid, default INBOX. | |
| subject | No | Alternatively match on a subject directly. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context: it searches across All Mail, groups messages by conversation, and highlights which ones carry documents. This explains the thread-reassembly behavior beyond the annotations.
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?
Two sentences, each earning its place. The first sentence is a crisp summary of the action, and the second provides essential background and a usage directive. There is no fluff or redundancy.
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?
Given the tool's moderate complexity and the absence of an output schema, the description adequately conveys what the tool returns (all conversation messages with document flags). It could mention ordering or pagination, but the core scope and behavior are sufficiently covered for a read-only thread pull.
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 each parameter already has a clear description (e.g., 'uid' is 'A message in the thread (its subject is used)'). The tool description adds no further parameter semantics beyond what the schema provides, so the baseline of 3 applies.
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 uses the specific verb 'Pull' and clearly states the resource: every message of a conversation from All Mail. It also distinguishes the tool from siblings by mentioning document-carrying messages and the IMAP/UI mismatch, which is unique to this thread-finding tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context: run this before concluding what a thread needs, and explains the critical IMAP vs Proton UI distinction that makes this necessary. It doesn't name alternative tools for when not to use it, but the guidance is strong enough to signal when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
folder_statusFolder statusARead-only
Message counts plus UIDNEXT and UIDVALIDITY for a folder. UIDs are only valid within one UIDVALIDITY generation, so check this before acting on uids noted earlier.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Default INBOX. |
TDQS
A4.3/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds an important behavioral caveat about UIDVALIDITY generations, which is beyond what the readOnlyHint and openWorldHint annotations convey. It warns about the validity of UIDs across generations, giving the agent critical context for safe use.
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?
Two concise sentences: the first states the primary output, the second provides an essential caveat. No filler or redundancy, and the most important information is front-loaded.
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 simple status tool with one optional parameter and no output schema, the description adequately covers what the tool returns and the critical UIDVALIDITY caveat. It is complete enough for an agent to select and invoke the tool appropriately.
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?
The schema already describes the single 'folder' parameter as defaulting to INBOX (100% coverage), so the description adds no additional parameter-level meaning. Baseline 3 applies because the schema does the heavy lifting.
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?
The description clearly identifies what the tool returns: message counts, UIDNEXT, and UIDVALIDITY for a folder. It lacks an explicit verb like 'get' or 'retrieve', but the resource and output are specific enough to distinguish it from siblings like poll_folder or list_folders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: check UIDVALIDITY before acting on previously noted UIDs. It implies when to use this tool (before relying on stored UIDs) but does not explicitly mention alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
forwardForwardADestructive
Forward an existing message to someone on demand. GATED like send: confirm recipient with the user, then call with confirmed=true.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ||
| uid | Yes | ||
| note | No | Optional note added above the forwarded content. | |
| folder | No | Default INBOX. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| confirmed | Yes | ||
| uidvalidity | No | UIDVALIDITY reported alongside the uid. Pass it back so a mailbox resync cannot make this act on the wrong message. | |
| from_address | No | Override the From address (use your alias-owner address when forwarding via an alias reverse-address). |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructive, non-readOnly), the description discloses the confirmation gate and the need for confirmed=true, which is not implicit in the schema. It stops short of detailing other side effects, but the annotations cover the destructive nature.
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?
The description is two sentences long, front-loaded with the primary purpose, and contains zero filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and a destructive action, the description is somewhat minimal. It covers the core action and gating but leaves out guidance on constructing uid or the overall flow, relying heavily on the schema for the rest.
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?
The description adds meaning to 'to' (recipient) and 'confirmed' (gating), but a required parameter like 'uid' remains undescribed in both schema and description. Schema coverage is moderate (63%), and the description only partially compensates.
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 clearly states the specific action ('Forward an existing message to someone on demand') with a distinct verb and resource, setting it apart from sibling tools like send, reply, or 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit context that this is an on-demand action and includes a gating mechanism ('GATED like send: confirm recipient with the user, then call with confirmed=true'), but does not explicitly list exclusions or when to prefer alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_headersGet message headersARead-only
Headers plus SPF/DKIM/DMARC verdicts and Proton metadata, for judging whether a message is what it claims to be. Pass raw=true for the unparsed header block.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No | Return the full raw header block instead. | |
| uid | Yes | ||
| folder | No | Default INBOX. | |
| uidvalidity | No |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds value by revealing that the tool returns parsed verdicts and Proton metadata, and that raw=true returns the unparsed header block. No contradiction with annotations.
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?
Two concise sentences front-load the core purpose and then add the most important parameter behavior. Every sentence contributes meaningful information with no filler.
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?
With no output schema, the description appropriately summarizes return content (headers, verdicts, metadata) and the raw mode. It could be more complete by clarifying uid/uidvalidity semantics, but for a read-only header tool this is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (raw and folder have descriptions, but required uid and uidvalidity do not). The description does not compensate by explaining uid or uidvalidity; its only parameter-related addition, 'Pass raw=true for the unparsed header block,' largely restates the schema's description of raw.
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 clearly states the tool fetches message headers plus SPF/DKIM/DMARC verdicts and Proton metadata for authentication judgment. This specific verb+resource combination distinguishes it from siblings like read_message or list_attachments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for judging whether a message is what it claims to be' provides a clear use case and implicitly positions this tool for message validation. It does not explicitly name alternatives or when-not-to-use, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_attachmentsList attachmentsARead-only
List a message's attachments, separating real DOCUMENTS from inline cid: images and PGP keys (hidden by default). Call before claiming a message has no attachment — read_message shows body text only and never reveals files.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| folder | No | Default INBOX. | |
| uidvalidity | No | UIDVALIDITY reported alongside the uid. Pass it back so a mailbox resync cannot make this act on the wrong message. | |
| include_inline | No | Also list inline images / PGP keys. |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint and openWorldHint annotations, the description adds valuable behavioral context: it separates document types and hides inline cid: images and PGP keys by default. This goes beyond what annotations alone communicate and is crucial for correct invocation.
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?
Two sentences: the first front-loads the core purpose and key differentiation, the second provides a critical usage tip. No filler 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?
For a list operation with no output schema, the description covers purpose, when to use it, an alternative, and unique behavioral quirks. It is sufficient for an agent to select and invoke the tool correctly.
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 75% (3/4 params documented). The description adds meaning for include_inline by explaining the default-hidden behavior and the document categorization, but does not elaborate on uid or folder beyond what the schema already states.
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 uses a specific verb ('list') and resource ('a message's attachments'), and further distinguishes itself by separating real documents from inline cid: images and PGP keys. This clearly differentiates it from sibling tools like read_attachment or view_attachment.
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 it ('Call before claiming a message has no attachment') and names the alternative (read_message) that only shows body text and never reveals files. This is direct, actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_foldersList folders and labelsARead-only
List all Proton folders and labels available over the Bridge. Call this first to learn exact folder/label names for filing and tagging.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows it's a safe read. The description adds the 'Call this first' ordering and the purpose of learning names, but does not disclose additional behavioral details like pagination or response format. This is acceptable given annotation coverage, but not rich.
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?
Two sentences, no wasted words. The first sentence states the core functionality, the second provides usage context. Each sentence earns its place.
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 simple parameterless discovery tool with annotations, this is complete. It tells the agent what the tool returns (list of folders/labels) and why to use it (to learn exact names for filing/tagging). No output schema exists, so the description adequately covers what the agent needs to select and invoke the tool.
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?
The tool has 0 parameters, so the schema fully covers parameter semantics. Per the rubric, 0 params earns a baseline of 4. The description adds nothing parameter-related, but none is needed.
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 uses a specific verb ('List') with a clear resource ('all Proton folders and labels') and scope ('available over the Bridge'). It also distinguishes from siblings by being the discovery tool for names, unlike create_folder_or_label or delete_label which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'Call this first' to learn exact folder/label names before filing and tagging. It does not explicitly name alternatives or exclude cases, but the instruction to call first is a useful usage guideline for a discovery tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
markMark a messageAIdempotent
Mark a message read/unread or star/unstar.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| action | Yes | ||
| folder | No | Default INBOX. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| uidvalidity | No | UIDVALIDITY reported alongside the uid. Pass it back so a mailbox resync cannot make this act on the wrong message. |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint false, destructiveHint false, and idempotentHint true, covering the safety profile. The description adds no extra behavioral context about side effects, confirmation needs, or error behavior beyond the action itself.
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?
One sentence, front-loaded with the action, and no redundant words. It is appropriately concise for the tool's straightforward functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters including dry_run and uidvalidity safety mechanisms, the description is quite terse. However, schema descriptions fill in those details, and the annotations provide safety context, making the description minimally acceptable.
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 covers 60% of parameters with descriptions (folder, dry_run, uidvalidity). The description restates the action enum but adds little for uid or the purpose of dry_run, though the schema fills those gaps adequately.
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 clearly states the tool marks a single message with read/unread or star/unstar actions. The singular 'a message' distinguishes it from bulk_mark and other batch operations, and the action set differentiates it from label/move tools.
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: use this when you want to mark one message's state. However, it does not explicitly mention alternatives like bulk_mark for multiple messages or provide 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.
move_to_folderMove to folderAIdempotent
File a message: move it into another folder (e.g. 'Folders/', 'Archive', 'Trash').
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| folder | No | Source folder, default INBOX. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| to_folder | Yes | ||
| uidvalidity | No | UIDVALIDITY reported alongside the uid. Pass it back so a mailbox resync cannot make this act on the wrong message. |
TDQS
A3.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states the core action, which is already evident from the name and annotations. It does not disclose any additional behavioral traits such as folder naming conventions, side effects of moving, or the availability of dry_run. While annotations indicate readOnly=false and destructive=false, the description adds no context beyond that.
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?
The description is a single, front-loaded sentence with no redundant words. The examples are parenthetical and do not clutter the main point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters with 60% schema coverage and no output schema, so the description carries a significant burden. It omits mention of dry_run and uidvalidity, which are important safety features, and does not describe return behavior. While the schema details these parameters individually, the overall tool context is incomplete.
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?
The schema lacks descriptions for uid and to_folder, but the description's example destination values ('Folders/<name>', 'Archive', 'Trash') provide useful context for the to_folder parameter. However, it does not clarify uid or source folder semantics, leaving some gaps.
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 clearly states the action: 'move it into another folder', using the verb 'move' with the resource 'a message'. It also gives concrete destination examples ('Folders/<name>', 'Archive', 'Trash'), which differentiates it from bulk_move by implying single-message operation.
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?
The description implies usage for filing a message into a folder but does not explicitly state when to prefer this over alternatives like bulk_move, nor does it mention any exclusions. No guidance is given for selecting this tool over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
poll_folderPoll for new mailA
Messages that have arrived since the last poll. The very first poll emits nothing and just records where the mailbox ends, so turning this on does not replay the backlog. Marks nothing as read.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Most per call, 1 to 100 (default 20). | |
| folder | No | Default INBOX. | |
| advance | No | Default true. Set false to look without committing, then confirm with ack_folder. |
TDQS
A4.2/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals non-obvious stateful behavior: the first poll only records the mailbox position and returns nothing, and polling never marks messages as read. This goes beyond the annotations, which only indicate non-read-only, open-world, non-idempotent, non-destructive. The behavior about not replaying backlog is critical for correct usage.
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?
The description is two sentences, front-loaded with the core purpose, and every sentence adds value (behavior on first poll, read side-effect). No filler or repetition. It is optimally concise for the amount of useful information conveyed.
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?
With no output schema, the description states 'Messages that have arrived' but not the exact format. However, it covers the essential contexts: first poll behavior, statefulness, and read side-effects. The 'advance' parameter and its relation to ack_folder are in the schema, so the description doesn't need to repeat that. Overall, it's complete enough for a polling tool, just missing explicit output shape.
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?
The input schema already provides descriptions for all three parameters (limit, folder, advance) with 100% coverage. The tool description adds no extra parameter-specific information. Per the rubric, the baseline is 3 when schema coverage is high, which is exactly the case here.
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 clearly states that the tool emits messages arriving since the last poll, with a specific initial behavior. It distinguishes itself from sibling tools like search_mail and get_headers by focusing on incremental new-message retrieval. The title confirms the action, and the description adds the crucial 'first poll emits nothing' detail.
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?
The description implies usage for polling new mail and explains the first-call behavior, but it does not explicitly contrast with alternatives like search_mail or folder_status. There's no 'use this when' or 'instead of' guidance. While the context is clear, explicit alternatives or exclusions are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
purge_attachmentsDelete saved attachmentsADestructiveIdempotent
Immediately delete all ephemeral saved attachments. Call after reading a saved file so nothing lingers on disk.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds useful context about the scope ('all ephemeral saved attachments'), immediacy ('Immediately delete'), and the rationale (cleanup after reading). It does not contradict annotations.
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?
The description is two short sentences, front-loaded with the action statement, and includes a clear usage hint. Every word serves a purpose with no redundancy.
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?
The description covers the essential purpose and usage context for a simple destructive tool with one optional parameter. It doesn't mention return values, but for a delete operation this is usually a success indication, and the lack of an output schema lowers the burden. The dry_run parameter is sufficiently covered by the schema.
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 a baseline of 3 applies. The description does not add any additional meaning about the dry_run parameter beyond what the schema already explains. The schema fully documents the parameter, so no deduction is needed.
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 uses a specific verb ('delete') and clearly identifies the target ('all ephemeral saved attachments'). It distinguishes this tool from sibling deletion tools like delete_label or delete_draft by focusing on attachments and providing a specific usage scenario. The phrase 'Call after reading a saved file' adds further precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Call after reading a saved file so nothing lingers on disk'), giving clear context. It doesn't name alternatives or explicitly state when not to use it, but the intended use case is well defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_attachmentRead an attachmentARead-only
Extract an attachment's TEXT inline — PDFs via pypdf, plus text/csv/json/ics/eml. Use for invoices, decks, reports. Binary/image types must use save_attachment instead.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| folder | No | Default INBOX. | |
| filename | No | Which attachment (partial match OK). Optional if there is only one. | |
| uidvalidity | No | UIDVALIDITY reported alongside the uid. Pass it back so a mailbox resync cannot make this act on the wrong message. |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds behavioral context: supported formats (PDFs via pypdf, text/csv/json/ics/eml), inline text extraction, and a clear rule for binary types requiring save_attachment. This goes beyond annotation basics.
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?
Two sentences, front-loaded with the core purpose. No redundancy; every clause earns its place.
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 read-only text extraction tool with 4 parameters and no output schema, the description conveys the key behavior, supported types, and the critical alternative for binaries. Some nuances like return format or uid semantics are left to the schema, but the core usage is clear.
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 covers 75% of parameters with descriptions. The description does not clarify the remaining `uid` parameter or add syntax details. It provides no parameter-specific meaning beyond what the schema already states.
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?
Specific verb+resource: 'Extract an attachment's TEXT inline' clearly states the action and target. Lists supported formats and explicitly names save_attachment for binary types, distinguishing from the sibling tool.
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?
Provides explicit usage context ('Use for invoices, decks, reports') and an explicit exclusion: 'Binary/image types must use save_attachment instead.' Clearly directs when to use this tool vs alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_messageRead a messageARead-only
Read the full headers and body text of one message by uid within a folder.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| folder | No | Default INBOX. | |
| uidvalidity | No | UIDVALIDITY reported alongside the uid. Pass it back so a mailbox resync cannot make this act on the wrong message. |
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds scope ('full headers and body text') but does not disclose any additional behavioral traits such as error handling, rate limits, or message-not-found behavior. It adds some value beyond annotations but not rich context, consistent with a mid-range score.
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?
The description is a single sentence of 12 words, front-loaded with the verb and resource. Every word contributes meaning, including 'full', 'headers', 'body text', 'by uid', and 'within a folder'. There is no filler or redundancy.
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?
No output schema exists, so the description's mention of 'headers and body text' communicates return content. It also clarifies the folder parameter. Given the tool's low complexity and strong readOnly annotation, the description is nearly complete, though it omits edge-case behavior (e.g., missing uid) and the uidvalidity safety mechanism is only in the schema.
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 67% (uid has no description, folder has default, uidvalidity has description). The description adds 'by uid within a folder', which provides basic meaning to uid and folder, but it does not explain uidvalidity or offer syntax details. Since the schema already covers folder and uidvalidity, the description adds marginal value beyond the schema.
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 states a specific verb ('Read'), a specific resource ('message'), and explicit scope ('full headers and body text') with identifiers ('by uid within a folder'). This clearly distinguishes it from sibling tools like get_headers, which likely reads headers only, or search_mail, which finds messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this when you have a uid and want a single message's full content. It implies that get_headers would be for headers alone, but it does not explicitly name alternatives or state when not to use this tool. No exclusions are mentioned, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
remove_labelRemove a labelAIdempotent
Take a label off a message. The message itself stays where it is. GATED: removing a label ends in an expunge against the label mailbox, so confirm it or preview with dry_run=true first.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| label | Yes | The label to take off. On Proton the Labels/ prefix is optional. | |
| folder | No | Folder the message lives in, default INBOX. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| confirmed | No | ||
| uidvalidity | No | UIDVALIDITY reported alongside the uid. Pass it back so a mailbox resync cannot make this act on the wrong message. |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint false, destructiveHint false), the description discloses an important side effect: the expunge against the label mailbox. It also mentions the need for confirmation or dry_run, which is critical behavioral information not captured by annotations.
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?
The description is two sentences, front-loaded with the core action, followed by a concise warning. Every word contributes, with no redundant or filler content.
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?
Despite lacking an output schema, the description covers the key operational trait (expunge) and the required safety check. It could mention return values or error conditions, but the core usage context is sufficient given the simple operation and available sibling-tool context.
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?
The schema already describes 4 of 6 parameters (67%), and the description adds context about the purpose of 'dry_run' and 'confirmed' by mentioning preview and confirmation. This supplements the schema for the two undocumented parameters (uid and confirmed) implicitly, though not explicitly.
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 clearly states a specific action ('Take a label off a message') on a specific resource (a label on a message), and distinguishes it from related tools (e.g., apply_label, bulk_remove_label). The added detail that 'the message itself stays where it is' further clarifies that this is not a move or delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context, explicitly warning that the operation ends in an expunge and advising to 'confirm it or preview with dry_run=true first.' It does not explicitly compare to alternatives, but the sibling tool names imply the scope (single label) and the guidance on safety is valuable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
replyReplyADestructive
Reply to one message with correct threading. Replies to the Reply-To address when there is one, so alias mail stays masked. Pass draft=true to save it for review, or confirmed=true to send.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| body | Yes | Your reply text. The original is quoted beneath unless quote=false. | |
| draft | No | Save to Drafts instead of sending. Needs no confirmation because nothing goes out. | |
| quote | No | Quote the original beneath your reply. Default true. | |
| attach | No | Files to attach, by path. Only from the allowed source directories. | |
| folder | No | Folder holding the message. Default INBOX. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| subject | No | Override the auto 'Re: ...' subject. | |
| confirmed | No | Required to actually send. Not needed when draft=true. | |
| uidvalidity | No | UIDVALIDITY for that folder; refuses on mismatch. | |
| from_address | No | Must be on the sender allowlist. Left unset, alias mail automatically uses the alias-owner address. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral details beyond annotations: it replies to the Reply-To address to keep alias mail masked, and clarifies that confirmed=true is required to send. These are not derivable from the readOnlyHint/destructiveHint annotations or the schema alone.
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?
The description is two sentences, front-loaded with the core purpose, and every clause adds meaningful information. It avoids unnecessary repetition of schema details.
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?
Given the tool's complexity (11 parameters, no output schema), the description covers the essential behavioral flow (draft vs send, Reply-To masking) without needing to restate schema fields. It omits edge cases like uidvalidity or attachment restrictions, but those are documented in the schema.
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 91%, and the schema already explains draft, confirmed, quote, and other parameters. The description adds a brief note on the draft/confirmed relationship but does not materially augment parameter semantics beyond what the schema provides.
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 clearly states 'Reply to one message with correct threading,' identifying the exact verb and resource. It distinguishes from siblings like reply_all by specifying 'one message' and from send/forward by the reply context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for replying to a single message with threading and explains the draft=true vs confirmed=true modes. It does not explicitly mention alternatives like reply_all for multiple recipients, but the context is sufficiently clear for an AI agent to select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reply_allReply to allADestructive
Reply to everyone on a message, with your own addresses removed from Cc and duplicates dropped. Same draft and confirmation rules as reply.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| body | Yes | Your reply text. The original is quoted beneath unless quote=false. | |
| draft | No | Save to Drafts instead of sending. Needs no confirmation because nothing goes out. | |
| quote | No | Quote the original beneath your reply. Default true. | |
| attach | No | Files to attach, by path. Only from the allowed source directories. | |
| folder | No | Folder holding the message. Default INBOX. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| subject | No | Override the auto 'Re: ...' subject. | |
| confirmed | No | Required to actually send. Not needed when draft=true. | |
| uidvalidity | No | UIDVALIDITY for that folder; refuses on mismatch. | |
| from_address | No | Must be on the sender allowlist. Left unset, alias mail automatically uses the alias-owner address. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by disclosing that own addresses are removed from Cc and duplicates dropped. It also points to 'reply' for draft/confirmation rules, which is useful. However, it does not detail confirmation rules itself, relying on the sibling tool.
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?
Two concise sentences that front-load the core purpose and key behavioral nuance. No wasted words, and the cross-reference to 'reply' is efficient.
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?
Despite 11 parameters and no output schema, the description is reasonably complete because it references 'reply' for shared rules and the schema covers parameters. It could explain return values or edge cases, but the tool is a variant of 'reply', and the core behavior is clear. A more self-contained description would be better, but the sibling reference helps.
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 91%, so most parameters are already documented. The description mentions Cc behavior but does not add specific parameter semantics. The reference to 'reply' rules implies similar parameter behavior, but that is indirect. With high schema coverage, baseline 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 clearly states the tool replies to everyone on a message, distinguishing it from 'reply' (sender-only) and adding specific behavior about removing own addresses from Cc and dropping duplicates. This is a specific verb+resource with differentiation from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for replying to all recipients and references 'reply' for shared draft/confirmation rules, but does not explicitly state when to use this tool instead of alternatives like 'reply' or 'forward'. It provides context but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
save_attachmentSave an attachmentAIdempotent
Write attachment(s) to disk and return the path(s). Use for images, scanned PDFs, or anything not text-extractable. EPHEMERAL by default — files self-delete after the TTL.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| folder | No | Default INBOX. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| persist | No | Keep the file permanently. Default false = auto-deleted after the TTL so nothing lingers for the user to open by accident. | |
| dest_dir | No | Sub-path under the attachments dir. Writes outside it are refused. | |
| filename | No | Partial match; omit to save all documents. | |
| uidvalidity | No | UIDVALIDITY reported alongside the uid. Pass it back so a mailbox resync cannot make this act on the wrong message. | |
| include_inline | No |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that files are EPHEMERAL by default and self-delete after the TTL, which is important behavioral context beyond the annotations' readOnlyHint and destructiveHint flags. This adds transparency about the tool's lifecycle behavior and potential surprise to users.
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?
The description is three concise sentences, front-loaded with the primary action, followed by the intended use and the critical ephemeral behavior. Every sentence adds value with no redundancy.
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 tool with 8 parameters and no output schema, the description covers the return value (path(s)) and a key behavioral caveat (self-deletion). It doesn't enumerate error scenarios, but the schema covers parameter-level details, making the description sufficient as an overview.
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 75%, so most parameters already have descriptions. The tool description doesn't re-explain parameters, and it also doesn't clarify the undocumented uid and include_inline fields; however, these are reasonably inferable from their names and context.
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 clearly states the tool writes attachment(s) to disk and returns the path(s), using a specific verb and resource. It also gives concrete use cases (images, scanned PDFs, anything not text-extractable) that distinguish it from siblings like read_attachment and view_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use for images, scanned PDFs, or anything not text-extractable, giving a clear when-to-use signal. It does not name alternative tools but implies that text-extractable content is handled elsewhere, which is adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_all_mailSearch all mailARead-only
Search every mailbox at once and collapse duplicates by Message-ID, reporting where each message lives. Use when you do not know which folder something is in.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | ||
| text | No | ||
| limit | No | Most recent N (default 25). | |
| since | No | DD-Mon-YYYY. | |
| before | No | DD-Mon-YYYY. Combine with since for a date range. | |
| subject | No | ||
| unread_only | No | ||
| flagged_only | No |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses the deduplication behavior (collapse duplicates by Message-ID) and that results report message locations. This adds meaningful behavioral context not present in the annotations.
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?
Extremely concise: two sentences that front-load the core function and then the usage context. Every word earns its place, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and usage well, but given 8 parameters and no output schema, it leaves significant gaps. The lack of parameter descriptions for most fields and no detail on the result format beyond 'reporting where each message lives' makes it merely adequate, not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 38%, leaving most parameters (from, text, subject, unread_only, flagged_only) undocumented. The description does not compensate by explaining any parameter semantics, so agents are left without help for these inputs.
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?
Purpose is clearly stated with a specific verb and resource: 'Search every mailbox at once'. It also describes the distinguishing behavior of collapsing duplicates by Message-ID and reporting locations, which sets it apart from sibling search_mail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: 'Use when you do not know which folder something is in.' This gives clear context but does not explicitly name alternatives or exclusion cases, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_mailSearch a folderARead-only
Search a folder. Combine any of: text, from, subject, since (DD-Mon-YYYY), unread_only, flagged_only. Returns uids + envelopes, newest first. Set include_locations to also report which labels and folders each message carries.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | ||
| text | No | ||
| limit | No | Max results (default 15). | |
| since | No | DD-Mon-YYYY, e.g. 01-Jul-2026 | |
| before | No | DD-Mon-YYYY. Combine with since for a date range. | |
| folder | No | Folder to search, e.g. INBOX, 'All Mail', 'Folders/<name>'. Default INBOX. | |
| subject | No | ||
| uidvalidity | No | UIDVALIDITY reported alongside the uid. Pass it back so a mailbox resync cannot make this act on the wrong message. | |
| unread_only | No | ||
| flagged_only | No | ||
| include_locations | No | Report every other mailbox each message appears in, so you can tell what it is already labelled or filed as without a second search. Costs one search per mailbox. |
TDQS
A3.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, and the description adds valuable behavioral details: returns uids + envelopes, newest first, and that include_locations reports other mailboxes each message appears in. No contradictions with annotations.
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?
The description is concise and front-loaded with the primary action 'Search a folder'. It contains no filler and each sentence contributes meaningful information about filtering and return values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior and return format but omits guidance on when to prefer this tool over search_all_mail, the default result limit, and semantics for text/from/subject. Given the 11-parameter complexity and lack of output schema, it is serviceable but not fully complete.
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 only 55%, leaving several parameters like text, from, subject, unread_only, and flagged_only without schema-level explanations. The description merely lists these filters without adding semantics. It does clarify since format and include_locations behavior, but this is marginal. Baseline 3 applies due to moderate coverage.
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?
The description clearly states 'Search a folder' with a specific verb and resource, and lists the filter criteria. It distinguishes from search_all_mail by indicating folder scope, but does not explicitly name the sibling alternative, so it lacks full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like search_all_mail. 'Combine any of' is about combining filters, not tool selection. There is no mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sendSend mailADestructive
Send a new email. GATED: the agent must show the user the exact To/Subject/Body, get an explicit yes, then call with confirmed=true. Never call unattended.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | ||
| to | Yes | ||
| body | Yes | ||
| attach | No | Files to attach, by path. Only from the allowed source directories. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| subject | Yes | ||
| confirmed | Yes | Must be true; set only after the user approves this exact message. | |
| references | No | ||
| in_reply_to | No | ||
| from_address | No | Override the From address. For replies to a SimpleLogin alias, set this to your alias-owner address (PROTON_ALIAS_FROM) and send 'to' the reverse-alias from the message's Reply-To header. |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructive annotation, the description discloses the critical safety protocol: the agent must obtain explicit user approval and set confirmed=true, and never call unattended. This is essential behavioral context not captured in annotations.
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?
Two sentences, front-loaded with the core purpose, and each sentence carries essential information. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter destructive tool with no output schema, the description focuses heavily on confirmation gating but omits other important aspects such as dry_run's safe preview use case, from_address alias handling, and attachment behavior. It is sufficient for avoiding misuse but incomplete for full operational understanding.
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?
The schema covers only 40% of parameters. The description adds meaning to 'confirmed' by tying it to the gating workflow, and references 'exact To/Subject/Body', but it does not compensate for other undocumented parameters like cc, references, in_reply_to, or attachment details. It provides some value but leaves gaps.
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?
Clearly states 'Send a new email' with a specific verb and resource, distinguishing it from sibling tools like reply, forward, and send_draft. The gated confirmation requirement further clarifies its unique behavior.
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 instructs when to use: after showing the user the exact To/Subject/Body and receiving explicit yes, then calling with confirmed=true. Also states 'Never call unattended,' providing a clear exclusion. This is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_draftSend a draftADestructive
Send a saved draft as written, then move it to Trash. GATED. Sender and recipient checks run again at send time.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| folder | No | Defaults to your Drafts folder. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| confirmed | No | ||
| uidvalidity | No | UIDVALIDITY of the folder; refuses on mismatch. |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveness and mutability, but the description adds specific behavioral context: the draft is moved to Trash after sending, and sender/recipient checks re-run at send time. The term 'GATED' hints at restricted access, though it's vague. It doesn't explain the confirmation requirement, but that's partially covered by the schema.
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?
The description is two sentences, front-loaded with purpose and side effect, followed by a terse warning. Every word earns its place, with no fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action and a key side effect, but omits important operational details: the need for 'confirmed' to actually send, the 'dry_run' option for previewing without side effects, and the UIDVALIDITY safety check. Without an output schema, these gaps could lead to incorrect usage if the agent relies solely on the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 60% of parameters with descriptions, leaving 'uid' and 'confirmed' undocumented. The description adds no parameter-specific meaning; it merely states the action. It fails to clarify the critical 'confirmed' flag or the 'dry_run' preview option, which are essential for correct invocation.
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 uses a specific verb ('Send'), names the resource ('saved draft'), and states the outcome ('move it to Trash'). This clearly distinguishes it from siblings like 'send' or 'delete_draft' and leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'as written' implies use when no changes are needed, and 'then move it to Trash' signals when this tool is appropriate. It doesn't explicitly exclude alternatives, but the context is clear enough that an agent can infer when to use it versus other draft-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
unsubscribeUnsubscribeADestructive
Report how to unsubscribe from a message using its List-Unsubscribe header, and optionally send the email form. Reports only unless send=true. Web links are never fetched for you.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| send | No | Actually send the mailto: unsubscribe. Requires confirmed. | |
| folder | No | Default INBOX. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| confirmed | No | ||
| uidvalidity | No |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behaviors: that it only reports by default, that sending requires send=true, and that web links are never fetched. This adds safety context beyond the annotations, which already flag destructiveHint. It aligns with annotations and clarifies side effects.
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 adding value: purpose, default behavior, and a safety caveat. No waste, front-loaded.
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?
Covers purpose, side-effect gating, and a safety guarantee, but does not describe the report format or the confirmation requirement for send, which is only in the schema. Given no output schema, this is a minor gap but overall adequate for a moderately complex tool.
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 covers send, folder, and dry_run with descriptions, but uid, confirmed, and uidvalidity lack explanations. The description clarifies the send flag's role but does not compensate for the undocumented parameters, leaving some ambiguity for confirmed and uidvalidity.
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 uses specific verbs 'Report' and 'send' with a clear resource (List-Unsubscribe header). It distinguishes from sibling tools like 'send' or 'reply' by focusing on unsubscribe semantics and explicitly notes that web links are never fetched.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when the tool reports only versus sends (unless send=true), and notes web links are never fetched, which guides usage. However, it does not explicitly mention alternatives or when not to use it, though the unique purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_draftUpdate a draftADestructiveIdempotent
Replace a draft's contents. Threading headers are carried over, the new version is saved before the old one is binned. Omit a field to keep what the draft already had.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | ||
| to | No | ||
| uid | Yes | ||
| body | No | ||
| attach | No | Files to attach, by path. Only from the allowed source directories. | |
| folder | No | Defaults to your Drafts folder. | |
| dry_run | No | Preview exactly what would happen and change nothing. Needs no confirmation. | |
| subject | No | ||
| uidvalidity | No | UIDVALIDITY of the folder; refuses on mismatch. | |
| from_address | No | Must be on the sender allowlist. |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond the annotations: that threading headers are preserved, the new version is saved before the old one is binned, and that omitting fields retains existing values. This adds meaningful context about what is destroyed (old version) and the order of operations, complementing the destructiveHint and idempotentHint annotations. It does not contradict any annotations, and it provides useful operational details without being overly verbose.
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?
The description is three sentences, each contributing distinct information: the core action, a key behavioral guarantee (carryover of threading headers, save-before-bin), and the update semantics (omission behavior). It is front-loaded with the main verb and resource, has no redundant words, and is efficiently structured for an AI agent to parse quickly.
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 mutation tool with 10 parameters and no output schema, the description covers the critical behavioral aspects: replacement, partial update, and destruction of the old version. It also integrates well with the annotations and existing schema descriptions for parameters like attach, folder, dry_run, uidvalidity, and from_address. Minor gaps exist (e.g., what happens if the draft does not exist, or how attachments are handled in the replacement), but the description is sufficiently complete for an agent to understand the tool's core function and side effects.
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 50%, with some parameters (uid, to, cc, body, subject) lacking descriptions. The description helps by explaining the partial-update semantics for all fields ('Omit a field to keep what the draft already had'), which clarifies how parameters behave. However, it does not elaborate on individual parameter meanings or constraints (e.g., format of uid, what 'to' expects). The description adds moderate value but does not fully compensate for the missing parameter descriptions.
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 clearly states the tool's action with a specific verb ('Replace') and resource ('a draft's contents'). It distinguishes itself from sibling tools like create_draft (creates a new draft) and delete_draft (removes a draft) by focusing on updating an existing draft's content. The mention of 'Threading headers are carried over' further specifies a unique aspect of this tool, making its 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need to update an existing draft rather than create or send one) but does not explicitly state when to use it versus alternatives. It provides one usage guideline—'Omit a field to keep what the draft already had'—but lacks explicit exclusions or alternative tool references. Sibling tool names provide context, but the description itself gives no direct comparison guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
view_attachmentView an image attachmentARead-only
Look at an image attachment. Returns it as a viewable image, which is the only way to see a photo or a scan when the client cannot read local files. Images only, use read_attachment for text and PDFs.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| folder | No | Default INBOX. | |
| filename | No | Which image; partial match is fine. | |
| uidvalidity | No |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world behavior, but the description adds key behavioral context: the tool returns a viewable image and is the only way to see photos/scans under certain conditions. This goes beyond the annotations without contradiction.
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?
Two sentences, front-loaded with purpose, then return format, then constraint and alternative. Every sentence adds value with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations and schema, the description covers purpose and return type but omits parameter roles and any error/output behavior. The absence of an output schema and partial parameter descriptions leaves gaps, but the tool is simple and the core usage is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, but the description provides no additional parameter guidance. It does not explain the role of uid, folder, or uidvalidity, nor how 'filename' partial matching works. The description says 'image attachment' but not how to identify it, leaving the agent to rely on sparse schema hints.
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 clearly states the tool's purpose: 'Look at an image attachment' and 'Returns it as a viewable image'. It explicitly distinguishes from read_attachment for text and PDFs, and the title adds image-specific context. This is a specific verb+resource with clear scope.
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?
Directly says 'Images only, use read_attachment for text and PDFs,' naming the alternative tool and the condition for selection. Also mentions the scenario 'when the client cannot read local files,' providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
34 tool updates
v1.2.1- First observed
ack_folder - First observed
apply_label - First observed
bulk_apply_label - First observed
bulk_delete_labels - First observed
bulk_mark - First observed
bulk_move - First observed
bulk_remove_label - First observed
create_draft - First observed
create_folder_or_label - First observed
delete_draft - First observed
delete_label - First observed
find_thread - First observed
folder_status - First observed
forward - First observed
get_headers - First observed
list_attachments - First observed
list_folders - First observed
mark - First observed
move_to_folder - First observed
poll_folder - First observed
purge_attachments - First observed
read_attachment - First observed
read_message - First observed
remove_label - First observed
reply - First observed
reply_all - First observed
save_attachment - First observed
search_all_mail - First observed
search_mail - First observed
send - First observed
send_draft - First observed
unsubscribe - First observed
update_draft - First observed
view_attachment
TDQS
A3.9/5.0
Disambiguation5/5
Every tool targets a specific action and resource: read vs. view vs. save attachments are clearly separated by content type, single vs. bulk variants are explicitly described for one or many messages, and reply/draft/send/forward each serve distinct lifecycle stages. No two tools are functionally interchangeable without a clear scope difference.
Naming Consistency4/5
The vast majority of tools follow a consistent verb_noun pattern (e.g., list_folders, read_message, create_draft), and all names are lowercase with underscores. Minor deviations like folder_status (noun_noun) and bulk_* prefixes (adverb_verb) introduce slight inconsistency, but the pattern remains predictable and readable.
Tool Count2/5
At 34 tools, the server exceeds the 25-tool threshold and feels heavy for a mail client. The bulk/single pairs for mark, label, and remove_label add redundancy that could be consolidated with array parameters, and the attachment-specific tools (read, view, save, purge) could potentially be merged.
Completeness4/5
The tool surface covers core email workflows comprehensively: reading, searching, sending, replying, drafting, labels, folders, attachments, and even security headers. Minor gaps include no permanent message deletion, no rename operation for folders/labels, and no dedicated 'list all messages' that doesn't rely on search filters, but these are workaroundable.
Maintenance
ActivityActive
ResponsivenessResponsive
Related MCP Connectors
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
- PO6 MailboxOAuthcom.po6
Give AI agents secure access to your email via private aliases with dedicated mailbox storage.
Governed email for AI agents (Mailbuttons / mbag.ai): sandbox inboxes, policy gate, audit log.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI agents to send, read, search, and organize emails via ProtonMail using Proton Bridge. Supports MCP-compatible clients like Claude and Cursor.17323MIT
- AlicenseAqualityCmaintenanceUnofficial MCP server for Proton Mail (not affiliated with Proton AG) — send, read, search & organize email over SMTP/IMAP311225MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to send, read, search, and organize email from Proton Mail accounts via SMTP and IMAP.122MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Considus/proton-bridge-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server