AnyMail MCP is a local MCP server that gives AI agents full read, send, organize, and delete access across multiple Gmail (and experimental IMAP) accounts simultaneously, with credentials stored securely in the macOS Keychain.
Account Management
List configured accounts (including default and read-only status)
Add new accounts: Gmail, iCloud, Fastmail, or custom IMAP (with App Password, optional read-only or default flag)
Reading & Searching
Search messages using native Gmail query syntax, optionally filtered by label
Fetch full message content (headers, plain-text/HTML bodies, attachment metadata)
Fetch entire email threads (oldest first)
List all labels/mailboxes for an account
Download attachments by index; returns base64 or saves to disk for large files
Sending & Drafting
Send emails with to/cc/bcc, plain text, HTML, attachments, and reply threading
Create and save drafts without sending
Organizing & Labeling
Create new labels (supports nested labels)
Add/remove labels on messages
Mark messages as read or unread
Star or unstar messages
Archive messages (remove from Inbox)
Move messages to a target label/folder
Deleting
Trash messages (reversible ~30 days)
Permanently delete messages (requires confirm: true)
Bulk Operations (all support dryRun: true and confirm: true for large batches)
Mark all matching messages as read
Bulk add/remove labels on matching messages
Bulk move matching messages to a folder
Bulk trash matching messages
Bulk permanently delete matching messages
Empty Spam or Trash (optionally narrowed by query)
Security & Integration
Credentials stored in macOS Keychain; runs entirely locally, binding only to 127.0.0.1
Bearer token API access with sensitive info redacted from logs
Integrates with AI agents via HTTP (Cursor, Claude Code, VS Code, Windsurf) or stdio (Claude Desktop)
Allows reading, sending, organizing, and deleting emails across multiple Gmail accounts via IMAP/SMTP.
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., "@AnyMail MCP search all accounts for 'invoice'"
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.
Give your AI agent every one of your mailboxes, without giving anything to a cloud service. A local MCP server that lets Claude Code, Claude Desktop, Cursor, VS Code or Windsurf search, read, send, organize and clean up mail across all your accounts at once, over plain IMAP/SMTP. Gmail, iCloud, Fastmail, Microsoft 365, or any IMAP host.
Your mail is read by a program running on your own machine. Nothing is uploaded, proxied, or seen by anyone, including this project.
Pre-1.0. It works and it is in daily use, but tool names and options may still change between versions.
claude mcp add email-local -- npx -y email-local-mcp
npx -y email-local-mcp add you@example.com --defaultThat is the whole setup. Restart your agent and ask it to list_accounts.
Note on the examples below.
npxruns the tool without installing a binary, so there is no bareemail-local-mcpcommand on your PATH. Every example in this README is written asemail-local-mcp …; if you installed withnpx, prefix it withnpx -y. A Homebrew or from-source install gives you the bare command.
Prefer a menu bar app, a Homebrew install, or no terminal at all? See Other ways to install.
Related MCP server: io.github.p-w-4-z/inbox-mcp
Once it is connected, these are ordinary requests:
"What did I miss this week across all my accounts?"
"Find the invoice from Acme, any mailbox, and save the PDF to my desktop."
"Reply to Sarah's last email agreeing to Tuesday, but keep it short."
"Unsubscribe sweep: trash every promotional email older than a year."
"Move everything from my accountant into a Tax folder."
The last two touch thousands of messages. They are still one request, because the bulk tools work on a whole search result rather than one message at a time.
That is the right question to ask, so here is the honest answer in four parts.
There is no server run by this project, no account to create, and no telemetry. The engine is a Node process on your computer that opens a direct IMAP/SMTP connection to your mail provider. The only parties involved are you, your computer, and your provider, exactly as with any desktop mail client.
Your agent does see the messages it is asked to read, because that is the point. That happens on whatever terms you already have with your agent.
You never give it your real password. You create an App Password or sign in with OAuth: either way a per-app credential you can revoke at any time without touching your account. It is stored only in your operating system's credential store:
Platform | Where credentials live |
macOS | Keychain |
Windows | Credential Manager |
Linux | Secret Service (gnome-keyring / KWallet) |
Never in a config file, never in the repo, never in a log line, and never in a response your agent can read back.
The always-on HTTP mode is locked down three ways at once, because a local port that speaks to your mailbox is worth attacking:
Bound to 127.0.0.1 only. Not reachable from your network, let alone the
internet.
A bearer token on every request. Generated on first run and stored with permissions only you can read.
Origin validation. This is what stops a malicious website in your
browser from quietly talking to the port behind your back, an attack called
DNS rebinding.
Deleting mail is irreversible, so it is not treated like reading it:
Trash is the default. trash_message is reversible. Permanent deletion is
a separate tool that refuses to run without confirm:true.
Bulk operations preview first. dryRun:true reports what would be
affected and changes nothing. Anything destructive, or any batch over 100
messages, requires confirm:true.
Accounts can be read-only. Add one with --read-only and every write is
refused for that account, whatever the agent decides to try.
Full detail, including an App Password's blast radius and how to revoke one, is in SECURITY.md. The code is MIT licensed, so none of the above has to be taken on trust.
Two ways. Most people want the first.
Create a per-app credential with your provider, then:
email-local-mcp add you@gmail.com --default
email-local-mcp add you@icloud.com --provider icloud
email-local-mcp add you@work.com --provider imap --imap-host mail.work.com --smtp-host smtp.work.comProvider | Where to create it | Notes |
Gmail | Turn on 2-Step Verification first. IMAP is always on. | |
iCloud | https://account.apple.com → Sign-In and Security → App-Specific Passwords | Needs two-factor auth on the Apple Account. |
Fastmail | Settings → Password & Security → App Passwords | Scope it to IMAP + SMTP. |
Other IMAP | Your host's control panel | Some hosts require enabling IMAP access explicitly. |
Useful flags: --default (used when a tool omits account), --read-only
(refuse every write), --name "Full Name" (the display name recipients see).
login connects through the provider's own sign-in page, with no App Password.
For Microsoft it is the only option, since Exchange Online no longer accepts
basic auth for IMAP.
email-local-mcp login you@gmail.com --provider gmail --client-id … --client-secret …
email-local-mcp login you@contoso.com --provider microsoft --client-id … --tenant contoso.onmicrosoft.comOne piece of setup is yours: you register the OAuth client and pass its id. That is not busywork. Mail scopes are "restricted", so a client id shipped inside a public binary would force this project through Google verification and an annual security assessment, and until it passed, your refresh tokens would expire every week. A client you create yourself has none of those limits and takes about five minutes. docs/oauth.md walks through both providers.
Tokens refresh automatically and live in the same credential store as App
Passwords. email-local-mcp logout <email> disconnects and revokes at the
provider where the provider supports it.
Full CRUD across every connected account:
Kind | Operations |
Read | list accounts · search · read message · read thread (Gmail) · list labels (Gmail) · fetch attachments |
Create | send · save draft · create label · add an account |
Update | add/remove labels · read/unread · star/unstar · archive · move |
Delete | trash (reversible) · permanent delete (explicit |
Bulk | one call acts on every message matching a query: |
Every tool takes an optional account (the email address). Omit it to use your
default.
The bulk tools are query-first. They take
{ query?, mailbox?, dryRun?, confirm?, max? } and act on the whole matching set
in one pass, rather than one tool call per message. "Trash every promo older
than a year" is a single call, not four hundred.
dryRun:true previews the matched count and a sample, changing nothing.
Destructive or large (>100 message) batches require confirm:true.
Per-message failures are reported, never hidden.
Spam and Trash are reachable with the mailbox param, e.g. '[Gmail]/Spam'.
For very large sweeps, the removing operations act on up to max messages per
call (default 2000) and return { matched, affected, remaining, done }. If
done is false, re-run the identical call until it is true. Messages that
were acted on leave the search scope, so it resumes cleanly and a 10,000 message
cleanup never trips your agent's tool timeout.
Every provider speaks IMAP/SMTP, so the core (search, read, send, draft, move, archive, trash, delete, attachments, bulk) works everywhere. What differs is what the protocol itself exposes:
Gmail | iCloud · Fastmail · Microsoft 365 · any IMAP host | |
Status | Fully supported | Works, smaller feature set |
Organizing | Labels, many per message | Folders, one per message |
Search | Native Gmail syntax ( | Server-side text match only |
Threads |
| Not available |
Add it with | (default) |
|
list_accounts reports each account's provider, so an agent can tell which
rules apply before it acts. Mixing is the point: a Gmail work account and an
iCloud personal account can be connected at once, and every tool takes an
optional account to choose between them.
The app supervises the engine and gives you an Add Account window, an Install into Agents button, and Start at Login.
Download Email-Local-MCP-<version>-universal.dmg from the
latest release.
One universal build runs on Apple Silicon and Intel, with Node bundled
inside, so there are no prerequisites.
Open the DMG and drag Email Local MCP to Applications.
The first launch is blocked. The app is ad-hoc signed and not yet notarized, so macOS refuses it once. Open System Settings > Privacy & Security, find the "Email Local MCP was blocked" notice, click Open Anyway, and confirm. macOS remembers.
xattr -dr com.apple.quarantine "/Applications/Email Local MCP.app"A mail icon appears in the menu bar. Open Add Account and connect a mailbox. The first time a password is read, macOS shows a Keychain Always Allow prompt. Click it once. (It re-prompts after each update while builds are ad-hoc signed; a notarized release will end that.)
That is the last DMG you download. The app updates itself, checking on launch, every 6 hours, and when you open the menu. Updates are cryptographically verified against a key pinned inside the app, so only releases signed by the maintainer are ever installed.
The Add Account window covers Gmail, iCloud, Fastmail, or a custom IMAP host.
The App Password never touches the app itself: it is posted once to 127.0.0.1
and the engine puts it straight in the Keychain.
brew tap marcinwalendowski/tap
brew install email-local-mcp # the CLI and MCP server
brew install --cask email-local-mcp # the menu bar appThey are independent, and most people want the first. brew install with no
flag resolves to the formula, so the app genuinely needs --cask.
Then:
claude mcp add email-local -- email-local-mcp
email-local-mcp add you@example.com --defaultThe cask does not remove the Gatekeeper step described above. Homebrew installs the app; it does not vouch for it.
On a macOS beta or seed build, brew install of the formula can fail with a
complaint that your Xcode is outdated, naming a version Apple has only released
as a Beta. That is Homebrew deriving the requirement from the OS version, not a
problem with this formula. Use the cask or npx until a stable Xcode ships.
git clone https://github.com/MarcinWalendowski/email-local-mcp.git
cd email-local-mcp && ./scripts/setup-cli.sh --install-agents
node dist/index.js add you@gmail.com --defaultOn Windows, run npm ci && npm run build in place of the setup script. The
engine runs on macOS, Windows and Linux.
Paste this into Claude Code, Cursor, or any coding agent:
Install the Email Local MCP email server for me: run
claude mcp add email-local -- npx -y email-local-mcp
Then restart yourself, confirm it worked by calling list_accounts, and walk me
through adding my first mail account with npx -y email-local-mcp add.email-local-mcp install (or the app's Install into Agents button) writes
the right config for every agent it detects:
Agent | Transport | What gets written |
Cursor · Claude Code · VS Code · Windsurf | HTTP | local URL + |
Claude Desktop | stdio | spawn command (its own engine, same credential store) |
Restart the agent afterwards, then ask it to list_accounts.
This project has shipped as gmail-mcp and as anymail-mcp. If you used
either, your accounts come across on their own the first time you start
Email Local MCP: the registry with its flags, App Passwords, and OAuth refresh
tokens. There is nothing to run.
To watch it happen, or to find out why an account did not make it:
email-local-mcp import-legacy # explicit run, with a report
email-local-mcp import-legacy --force # look again after it has already runYour old data is copied, not moved. ~/.anymail-mcp/ and the old
credential-store items stay where they are. Delete them once you are
satisfied.
It runs once. A marker at ~/.email-local-mcp/legacy-import.json records
the run, so an account you delete afterwards stays deleted. If a credential
could not be read, from a locked Keychain say, the marker is deliberately not
written and the next start tries again.
Re-registering the MCP server is the one step that is not automatic, since the old spawn command names the old binary.
Agent (Claude Code / Desktop / Cursor ...)
│ MCP over stdio or HTTP (127.0.0.1, bearer token)
▼
Email Local MCP engine (local Node process, yours)
│ one provider per account
│
├─ GmailProvider ── ImapFlow → imap.gmail.com:993 (+ X-GM-*: labels, threads, raw search)
│ Nodemailer→ smtp.gmail.com:465
│
└─ ImapProvider ── ImapFlow → imap.mail.me.com:993 (iCloud / Fastmail / Microsoft / any host)
Nodemailer→ smtp.mail.me.com:587 folders, IMAP SEARCH
▼
Each account authenticated with its own credential, read from the OS storeGmailProvider extends ImapProvider, so Gmail is the generic IMAP behaviour
plus the X-GM-* extensions. Adding a provider means extending ImapProvider
and adding a preset. See src/node/providers/.
Why IMAP/SMTP rather than the Gmail HTTP API. Full-CRUD Gmail API access
needs restricted OAuth scopes, which for personal @gmail.com accounts forces
Google app verification plus an annual CASA security assessment, or a 7-day
token expiry in Testing mode. App Passwords over IMAP sidestep all of it and run
fine in a local process. IMAP also needs a long-lived TCP socket, so this could
not be a serverless function in any case.
The macOS app internals are in app/BUILD.md; the distribution
pipeline is in docs/DISTRIBUTION.md.
Generic IMAP providers: iCloud, Fastmail, and any IMAP host.
Universal DMG: one macOS app for Apple Silicon and Intel, Node bundled.
Windows and Linux CLI, using each OS's native credential store.
OAuth sign-in, which also brings in Microsoft 365 / Outlook.
Homebrew tap: a formula for the CLI and a cask for the app.
npm / npx distribution, which is now the one-line install.
Automatic import of accounts from a previous install.
Richer search for IMAP providers: map the common Gmail-style operators
(from:, subject:, has:attachment, date ranges) onto IMAP SEARCH, so
a query behaves the same across accounts.
More providers: Yahoo.
A sign-in button in the app, so OAuth does not need the CLI.
A notarized DMG, so the first launch opens without the Gatekeeper step.
See CONTRIBUTING.md. Security reports: SECURITY.md.
MIT. See LICENSE.
Add and verify a mail account, storing its App Password in the macOS Keychain (never in the registry or logs). provider: gmail (default) | icloud | fastmail | imap. For 'imap' pass imapHost + smtpHost (ports default to 993 / 465, or 587 with smtpStartTls). SECURITY: the App Password is an argument to this call, so it passes through the agent's context and the MCP client's logs. For the most private path, add accounts in the app's GUI instead — there the password goes straight to the local engine and the model never sees it.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | The account's email address. | ||
| imapHost | No | IMAP host (required for provider 'imap', e.g. imap.host.tld). | |
| imapPort | No | IMAP port (default 993). | |
| provider | No | Mail provider (default gmail). Presets cover gmail/icloud/fastmail; 'imap' needs custom hosts. | |
| readOnly | No | Refuse all writes for this account. | |
| smtpHost | No | SMTP host (required for provider 'imap', e.g. smtp.host.tld). | |
| smtpPort | No | SMTP port (default 465, or 587 with smtpStartTls). | |
| appPassword | Yes | App Password / IMAP password. Stored only in the Keychain. | |
| displayName | No | ||
| makeDefault | No | Make this the default account. | |
| smtpStartTls | No | Use STARTTLS on 587 instead of implicit TLS on 465. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes security behavior: password stored in Keychain, not registry/logs, and warns that password passes through context/logs. This adds value beyond the openWorldHint annotation. Some details on verification behavior are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences plus a security note. Efficiently front-loaded with main action. Could be slightly more structured, but no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description does not explain return value or error behavior. It lacks details on what 'verify' entails or failure handling. Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (91%), but description adds context: provider defaults, port defaults, STARTTLS. It explains the purpose of parameters beyond the schema, like security context for appPassword.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add and verify a mail account' with a specific verb and resource. It distinguishes from sibling tools by focusing on account creation, unlike message management or label tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on providers, default ports, and when to use GUI for privacy. It also explains required parameters for 'imap' provider, giving clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a message (remove it from the Inbox).
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Gmail address to act on. Omit to use the default account. | |
| gmMsgId | Yes | Gmail message id (X-GM-MSGID), as returned by search_messages or get_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects. It states 'remove it from the Inbox' but does not clarify whether the message is still accessible via 'All Mail' or other labels, whether it can be undone, or its impact on unread status.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single clear sentence with no wasted words, front-loading the key information. However, it is somewhat brief given the complexity of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of output schema and annotations, the description should provide more behavioral context (e.g., message lifecycle after archiving). It is insufficient for an AI agent to fully understand the consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add any additional meaning to the parameters beyond what is already in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'archive' and the resource 'message', and the parenthetical 'remove it from the Inbox' distinguishes it from deletion or trashing. However, it does not explicitly compare with sibling tools like 'trash_message' or 'delete_message'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'move_message' or 'trash_message'. The description lacks context about prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PERMANENTLY delete every message matching a query in an explicit mailbox. On Gmail this only works inside Trash or Spam (use empty_trash / empty_spam, or bulk_trash then empty_trash). Irreversible; requires confirm:true (dryRun:true to preview).
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | Cap on messages acted on this call for trash/move/delete/empty (default 2000, keeps calls under the timeout). If the result is done:false, re-run the same call (with confirm:true) to continue until done:true. | |
| query | No | What to match. On Gmail this is native search syntax (e.g. 'older_than:1y is:unread'); on other providers a text match. Omit to match the whole mailbox. | |
| dryRun | No | Preview only: return the matched count + a small sample, changing nothing. | |
| account | No | Gmail address to act on. Omit to use the default account. | |
| confirm | No | Required to actually run a destructive or large (>100) batch. | |
| mailbox | No | Mailbox/label to run in (e.g. '[Gmail]/Spam'). Omit for the account's whole-mail scope (Gmail: All Mail). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint:true. The description adds that the action is irreversible, requires confirm:true, and notes Gmail-specific restrictions, which provides useful behavioral context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key action and warning, every word earns its place, no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 params, destructive, no output schema), the description covers Gmail specifics, preview, confirmation, and alternatives. It lacks return value details, but the absence of output schema reduces the need. Overall fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description emphasizes the roles of confirm and dryRun, but adds little other semantic value beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'PERMANENTLY delete every message matching a query in an explicit mailbox' with a specific verb and resource, and differentiates from sibling tools by noting Gmail-specific restrictions and alternatives like empty_trash/empty_spam.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance (for permanent deletion) and when-not (only in Trash/Spam on Gmail), mentions dryRun:true for preview and confirm:true for execution, and references alternative tools for emptying trash/spam.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add and/or remove labels on every message matching a query (Gmail only). Provide add and/or remove. dryRun:true previews; confirm:true runs batches over 100.
| Name | Required | Description | Default |
|---|---|---|---|
| add | No | Labels to add. | |
| max | No | Cap on messages acted on this call for trash/move/delete/empty (default 2000, keeps calls under the timeout). If the result is done:false, re-run the same call (with confirm:true) to continue until done:true. | |
| query | No | What to match. On Gmail this is native search syntax (e.g. 'older_than:1y is:unread'); on other providers a text match. Omit to match the whole mailbox. | |
| dryRun | No | Preview only: return the matched count + a small sample, changing nothing. | |
| remove | No | Labels to remove. | |
| account | No | Gmail address to act on. Omit to use the default account. | |
| confirm | No | Required to actually run a destructive or large (>100) batch. | |
| mailbox | No | Mailbox/label to run in (e.g. '[Gmail]/Spam'). Omit for the account's whole-mail scope (Gmail: All Mail). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. It discloses dryRun preview and confirm requirement for large batches, but does not mention potential issues like rate limits, timeouts, or that it modifies many messages. Modest transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise two-sentence description. Front-loads the purpose and action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 8 parameters and no output schema, the description is very short. It omits details about the 'max' parameter's re-run behavior, result handling, and asynchronous nature. Leaves gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3. The description adds minimal value beyond schema: it restates 'provide add and/or remove' and clarifies dryRun/confirm behavior, but most parameter details are already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds/removes labels on every message matching a query, specifying it is Gmail only. It distinguishes from sibling 'modify_labels' by indicating bulk operation, but does not explicitly contrast with other bulk tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on using dryRun for preview and confirm for large batches, but lacks explicit when-not-to-use or alternatives. Implied usage from 'every message matching a query' is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
File every message matching a query under a target label (Gmail: adds the label and removes it from the Inbox; other providers: moves to the folder).
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | Cap on messages acted on this call for trash/move/delete/empty (default 2000, keeps calls under the timeout). If the result is done:false, re-run the same call (with confirm:true) to continue until done:true. | |
| query | No | What to match. On Gmail this is native search syntax (e.g. 'older_than:1y is:unread'); on other providers a text match. Omit to match the whole mailbox. | |
| dryRun | No | Preview only: return the matched count + a small sample, changing nothing. | |
| account | No | Gmail address to act on. Omit to use the default account. | |
| confirm | No | Required to actually run a destructive or large (>100) batch. | |
| mailbox | No | Mailbox/label to run in (e.g. '[Gmail]/Spam'). Omit for the account's whole-mail scope (Gmail: All Mail). | |
| targetLabel | Yes | Label/folder to file matches under. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses provider-specific behavior (Gmail adds label and removes from Inbox, others move to folder), mentions destructive nature via the confirm parameter, and notes capping with max. However, it does not detail potential impacts on thread structure or mention whether moved messages are archived.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, one sentence with a parenthetical clarification for provider differences. It efficiently conveys the core purpose, though it could be slightly more structured with separate notes for behavior and safety.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, full schema coverage, and no output schema or annotations, the description fairly covers the operation's scope and provider behavior. It could be improved by explicitly stating it operates on individual messages (not threads) and what the return value indicates, but it is largely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully described in the schema itself. The tool's description adds no extra parameter-specific meaning beyond the schema, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (file/move) and resource (messages matching a query) and distinguishes the tool from siblings like move_message (single message) or bulk_delete (deletion) by specifying it moves to a label/folder and describes provider-specific behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for bulk moving messages based on a query, but does not explicitly state when to avoid it or compare with alternatives like bulk_modify_labels or bulk_trash. Lacks explicit exclusions or recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move every message matching a query to Trash (reversible ~30 days). Requires a query or mailbox. dryRun:true previews; confirm:true runs batches over 100.
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | Cap on messages acted on this call for trash/move/delete/empty (default 2000, keeps calls under the timeout). If the result is done:false, re-run the same call (with confirm:true) to continue until done:true. | |
| query | No | What to match. On Gmail this is native search syntax (e.g. 'older_than:1y is:unread'); on other providers a text match. Omit to match the whole mailbox. | |
| dryRun | No | Preview only: return the matched count + a small sample, changing nothing. | |
| account | No | Gmail address to act on. Omit to use the default account. | |
| confirm | No | Required to actually run a destructive or large (>100) batch. | |
| mailbox | No | Mailbox/label to run in (e.g. '[Gmail]/Spam'). Omit for the account's whole-mail scope (Gmail: All Mail). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Disclosed reversible (30 days), batch behavior, need for re-run if done:false, and timeout via max parameter. Adds value beyond destructiveHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key info, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers operation, reversibility, and batch mechanics. No output schema, but description implies results. Could mention per-message processing time, but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning for dryRun and confirm beyond schema descriptions. Schema already covers all parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool moves messages to Trash based on a query. Distinct from siblings like bulk_delete and trash_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions requirements: query/mailbox, dryRun for preview, confirm for large batches. Does not directly compare to siblings but provides sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compose a draft and save it to the Drafts mailbox (does not send).
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | ||
| to | Yes | Recipient address(es). | |
| bcc | No | ||
| html | No | HTML body (optional). | |
| text | No | Plain-text body. | |
| account | No | Gmail address to act on. Omit to use the default account. | |
| subject | Yes | ||
| inReplyTo | No | RFC822 Message-ID being replied to; sets In-Reply-To/References so Gmail threads it. | |
| attachments | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clarifies that the tool creates a draft without sending, which is critical behavioral context. However, it does not mention prerequisites (e.g., valid account), error handling, or 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core action ('Compose a draft'). No wasted words; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 9 parameters and no output schema or annotations, the description is minimal. It explains the core purpose but leaves out return values (e.g., draft ID), error conditions, and required permissions. The description is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 56%, meaning 5 of 9 parameters have descriptions in the schema. The description adds no additional information about parameters. It does not clarify ambiguous parameters like 'cc', 'bcc', or 'subject' (which is required but has no schema description). The description fails to compensate for coverage gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'compose and save' and resource 'draft', and explicitly distinguishes from sending ('does not send'), differentiating it from sibling tool send_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells the agent when to use—when a draft is needed but not sent. However, it does not explicitly state alternatives (e.g., 'use send_message to actually send') or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Gmail label (nested labels use '/', e.g. 'Clients/Acme').
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Label name/path. | |
| account | No | Gmail address to act on. Omit to use the default account. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden, but it only states the basic creation action. It fails to disclose what happens if the label already exists, required permissions, or any 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the primary action. It is efficient but could include more details without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema, the description is incomplete. It lacks behavior on duplicate labels, error conditions, and usage context, which an agent would need for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the nested label syntax with an example, which is not present in the schema parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new Gmail label and gives a nested label example, making the purpose specific. However, it does not explicitly distinguish it from sibling tools like list_labels or modify_labels, though the context implies it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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. It lacks conditions, prerequisites, or exclusions, leaving the agent to infer usage from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PERMANENTLY delete a message (moves to Trash then expunges). Irreversible. Requires confirm:true. Prefer trash_message for a reversible delete.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Gmail address to act on. Omit to use the default account. | |
| confirm | Yes | Must be true to permanently delete. | |
| gmMsgId | Yes | Gmail message id (X-GM-MSGID), as returned by search_messages or get_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint and idempotentHint. Description adds context about irreversible nature and the two-step process, enhancing transparency 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences that are front-loaded and each sentence adds meaningful information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with full schema coverage and annotations, the description is complete, covering the irreversible nature, required confirmation, and alternative tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds limited value for parameters beyond mentioning confirm:true, which is already in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool permanently deletes a message, provides the mechanism (moves to Trash then expunges), and distinguishes from trash_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the requirement for confirm:true and recommends trash_message for reversible deletion, providing clear when-to-use and 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.
PERMANENTLY delete everything in the Spam/Junk mailbox (optionally narrowed by query). Irreversible; requires confirm:true. Use dryRun:true to see the count first.
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | Cap on messages acted on this call for trash/move/delete/empty (default 2000, keeps calls under the timeout). If the result is done:false, re-run the same call (with confirm:true) to continue until done:true. | |
| query | No | What to match. On Gmail this is native search syntax (e.g. 'older_than:1y is:unread'); on other providers a text match. Omit to match the whole mailbox. | |
| dryRun | No | Preview only: return the matched count + a small sample, changing nothing. | |
| account | No | Gmail address to act on. Omit to use the default account. | |
| confirm | No | Required to actually run a destructive or large (>100) batch. | |
| mailbox | No | Mailbox/label to run in (e.g. '[Gmail]/Spam'). Omit for the account's whole-mail scope (Gmail: All Mail). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds beyond the destructiveHint annotation by stating irreversibility, necessity of confirm:true, and the availability of dryRun:true, providing critical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences; first sentence clearly states purpose, second adds essential safety info. No wasted words, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with good schema and annotations, the description adequately covers purpose, safety, and preview option. Could mention max parameter but schema covers it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so baseline is 3. The description only implicitly references the query parameter and adds no new parameter-level details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('PERMANENTLY delete everything in the Spam/Junk mailbox') and the ability to narrow by query, which is specific and distinct from sibling tools like empty_trash.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions irreversible nature, confirm requirement, and dryRun suggestion, but does not explicitly contrast with siblings (e.g., empty_trash) or provide 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.
PERMANENTLY delete everything in the Trash mailbox (optionally narrowed by query). Irreversible; requires confirm:true. Use dryRun:true to see the count first.
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | Cap on messages acted on this call for trash/move/delete/empty (default 2000, keeps calls under the timeout). If the result is done:false, re-run the same call (with confirm:true) to continue until done:true. | |
| query | No | What to match. On Gmail this is native search syntax (e.g. 'older_than:1y is:unread'); on other providers a text match. Omit to match the whole mailbox. | |
| dryRun | No | Preview only: return the matched count + a small sample, changing nothing. | |
| account | No | Gmail address to act on. Omit to use the default account. | |
| confirm | No | Required to actually run a destructive or large (>100) batch. | |
| mailbox | No | Mailbox/label to run in (e.g. '[Gmail]/Spam'). Omit for the account's whole-mail scope (Gmail: All Mail). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses permanent deletion and irreversibility beyond the destructiveHint annotation. Also mentions the dryRun safety mechanism and the need for confirmation, adding full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences front-load the main action and then cover safety caveats. Every word earns its place; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the core behavior, preview, and confirmation. While no output schema exists, the description could explicitly mention what the tool returns on success (e.g., count or status). However, the parameter descriptions hint at return values via 'done:false'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant value beyond the 100% schema coverage. Explains the purpose of confirm (required for destructive/large batches), dryRun (preview count/sample), and max (cap, timeout handling with done:false).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('delete') and names the resource ('Trash mailbox'), with optional narrowing by query. It clearly distinguishes from siblings like 'empty_spam' and 'trash_message'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states that the action is irreversible and requires confirm:true, and recommends using dryRun:true for preview. Provides clear when-to-use and 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.
Download one attachment from a message by index. Provide savePath to write it to disk (required for files >5MB); otherwise returns base64.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Attachment index from get_message.attachments. | |
| account | No | Gmail address to act on. Omit to use the default account. | |
| gmMsgId | Yes | Gmail message id (X-GM-MSGID), as returned by search_messages or get_message. | |
| savePath | No | Absolute path to write the attachment to. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the two output modes and the size threshold, adding behavioral context beyond the readOnlyHint annotation. No contradiction with annotations; the tool is read-only and the description aligns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The main action and key conditions are front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior (download modes, size threshold) and uses the schema well. However, it is slightly ambiguous whether savePath is always required for writing or only for large files. Overall, it is adequate given the tool's simplicity and rich schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters with descriptions (100% coverage). The tool description adds useful context: savePath is required for files >5MB, which is not in the schema. This enhances parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Download one attachment from a message by index.' It specifies the verb (download), resource (attachment), and the two modes (base64 or file write) with a size threshold, distinguishing it from siblings like get_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 savePath (required for files >5MB) and otherwise returns base64. It does not explicitly compare with alternatives among siblings, but provides enough guidance for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a full message: headers, plain-text and HTML bodies, and attachment metadata (use get_attachment for bytes).
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Gmail address to act on. Omit to use the default account. | |
| gmMsgId | Yes | Gmail message id (X-GM-MSGID), as returned by search_messages or get_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already set readOnlyHint=true, so the description's addition of what the tool returns (headers, bodies, attachment metadata) adds value but doesn't disclose deeper behavioral traits like pagination, size limits, or performance. The description is adequate 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose ('Fetch a full message') and adds essential distinctions. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with 2 parameters and no output schema, the description is fairly complete. It clarifies the tool's scope and relation to a sibling. Missing info on response format or restrictions, but still sufficient for basic selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; it merely restates that gmMsgId comes from search_messages or get_message, which is already in the parameter descriptions. No extra semantics for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies 'Fetch a full message: headers, plain-text and HTML bodies, and attachment metadata' and explicitly distinguishes from the sibling tool 'get_attachment' by directing users there for byte content. This makes the tool's purpose very clear and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on what the tool returns and points to an alternative for attachment bytes. However, it does not explicitly state when to use this tool over other siblings like search_messages, which could be implied. Still, it offers good differentiation from a key sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch all messages in a Gmail thread (by gmThrId), oldest first.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Gmail address to act on. Omit to use the default account. | |
| gmThrId | Yes | Gmail thread id (X-GM-THRID) from search_messages. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which the description aligns with ('Fetch all messages'). No additional behavioral traits (e.g., return format limits, authentication needs) are disclosed beyond 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the core action and ordering. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a fetch operation without output schema, the description covers the key aspects: what is returned (all messages), ordering (oldest first), and input (by gmThrId). Could mention pagination or limits, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal value beyond the schema. It mentions gmThrId but does not elaborate on account parameter or provide additional semantic guidance. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches all messages in a Gmail thread by gmThrId, ordered oldest first. This is specific and distinguishes it from siblings like get_message or search_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a thread's messages but does not explicitly state when to use it versus alternatives (e.g., get_message for single messages). No exclusion criteria or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the configured Gmail accounts (no secrets), showing which is default and which are read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds valuable context by stating 'no secrets' and specifying that it shows default and read-only status, enhancing transparency beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the verb 'List' and efficiently conveys all necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no output schema, and a simple listing task, the description is fully complete. It explains what the tool returns (list of accounts with default/read-only status) without needing further detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the description does not need to add parameter info. Baseline for 0 params is 4, and the description is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'configured Gmail accounts', specifying what information is shown (default and read-only status). It distinguishes from sibling tools which perform actions on messages or labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. However, as a simple read-only list operation, usage is implied by the tool's name and description. The lack of exclusions is acceptable but could be improved with context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all labels/mailboxes for the account, including special-use flags.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Gmail address to act on. Omit to use the default account. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, so the read-only nature is clear. The description adds value by stating the tool includes 'special-use flags', which is a specific behavioral detail beyond the annotation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core purpose. Every word 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.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with good annotations and schema, the description is complete. It specifies the resource, the inclusion of special-use flags, and the account parameter is covered by schema. No output schema needed for such a straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter 'account' with a clear description. The tool description does not add additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and the resource (labels/mailboxes for the account). It distinguishes from sibling tools like 'create_label' and 'modify_labels' by focusing on reading all labels, not creating or modifying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to use this tool versus alternatives like 'create_label' or 'modify_labels'. It implies usage for viewing all labels, but lacks guidance on when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark every message matching a query as read in one pass — e.g. {query:'is:unread', mailbox:'[Gmail]/Spam'}. Reaches Spam/Trash via the mailbox param. Use dryRun:true to preview the count; confirm:true for batches over 100.
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | Cap on messages acted on this call for trash/move/delete/empty (default 2000, keeps calls under the timeout). If the result is done:false, re-run the same call (with confirm:true) to continue until done:true. | |
| query | No | What to match. On Gmail this is native search syntax (e.g. 'older_than:1y is:unread'); on other providers a text match. Omit to match the whole mailbox. | |
| dryRun | No | Preview only: return the matched count + a small sample, changing nothing. | |
| account | No | Gmail address to act on. Omit to use the default account. | |
| confirm | No | Required to actually run a destructive or large (>100) batch. | |
| mailbox | No | Mailbox/label to run in (e.g. '[Gmail]/Spam'). Omit for the account's whole-mail scope (Gmail: All Mail). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: reaches Spam/Trash via mailbox param, requires confirm for destructive/large batches, dryRun previews count, and max parameter limits. Since no annotations exist, description carries full burden and handles it well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff, front-loaded with the primary action. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no output schema, no annotations, the description covers all essentials: purpose, usage pattern, important parameters, and safety mechanisms. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema: explains query example, mailbox scope, dryRun/confirm semantics, and max parameter context. With 100% schema coverage baseline at 3, this description excels.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool marks every message matching a query as read in one pass, with a concrete example. It distinguishes from siblings like mark_unread by specifying 'mark as read' and batch operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on using dryRun for preview and confirm for large batches. Could be improved by directly contrasting with single-message mark_read, but the intent is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a message as read (\Seen).
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Gmail address to act on. Omit to use the default account. | |
| gmMsgId | Yes | Gmail message id (X-GM-MSGID), as returned by search_messages or get_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are empty, so description should disclose behavioral traits. Only states it marks as read; no mention of side effects, permissions, or return value. Minimal disclosure for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words. Appropriate length for a simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with no output schema; description covers core action. Lacks context about email state changes, filtering implications, or relation to sibling tools. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description does not add any extra meaning beyond the schema for the two parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Mark a message as read' with the specific IMAP flag '\Seen'. Distinguishes from sibling tool 'mark_unread' by focusing on the read state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'mark_unread' or 'archive'. Does not mention prerequisites or context (e.g., single message only).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a message as unread.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Gmail address to act on. Omit to use the default account. | |
| gmMsgId | Yes | Gmail message id (X-GM-MSGID), as returned by search_messages or get_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description only says 'mark a message as unread'. It does not disclose any side effects, permissions, or state changes beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero waste. It is appropriately sized for a simple action but could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema and full param coverage, the description is minimally complete but lacks context about when this action is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no additional meaning beyond what the schema already provides for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Mark') and resource ('a message'), and the title reinforces it. It implicitly distinguishes from siblings like 'mark_read' and 'unstar'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives like 'mark_read' or 'modify_labels'. The description does not indicate prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add and/or remove Gmail labels on a message. System labels use a backslash prefix (\Inbox, \Starred, \Important); custom labels use their plain name. Removing \Inbox archives.
| Name | Required | Description | Default |
|---|---|---|---|
| add | No | Labels to add. | |
| remove | No | Labels to remove. | |
| account | No | Gmail address to act on. Omit to use the default account. | |
| gmMsgId | Yes | Gmail message id (X-GM-MSGID), as returned by search_messages or get_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that removing \Inbox archives and explains the backslash prefix for system labels. However, it does not mention side effects on invalid labels, permission requirements, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It is front-loaded with the primary action, then provides critical detail about label naming and the effect of removing \Inbox.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description covers the core behavior but lacks completeness on return values, error conditions, and prerequisites. It adequately explains the label format and a key side effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the naming convention (backslash for system labels) and the archival effect of removing \Inbox, which are not fully captured in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: adding and/or removing Gmail labels on a message. It distinguishes itself from sibling tools like 'archive' (which is a specific label action) and 'create_label' (which creates labels) by specifying the action on existing labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly mentions that removing \Inbox archives, which relates to the 'archive' sibling tool, but it does not explicitly state when to use this tool versus others or provide prerequisites. No when-not or alternative guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a message to a label: applies the target label and removes it from the Inbox.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Gmail address to act on. Omit to use the default account. | |
| gmMsgId | Yes | Gmail message id (X-GM-MSGID), as returned by search_messages or get_message. | |
| targetLabel | Yes | Label to file the message under. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the core action (apply label, remove from Inbox) but lacks details on permissions, error behavior, or side effects like removal of other labels.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one sentence (12 words) and front-loads the purpose, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, but the description does not mention return values or error conditions. For a mutation tool, this is a gap—it should indicate success/failure or other outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description only adds context that the target label causes removal from Inbox. This adds marginal value beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'move' and resource 'message', and distinguishes by specifying that it applies the target label and removes from Inbox, differentiating it from sibling tools like modify_labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for moving to a label and removing from Inbox, but does not provide explicit guidance on when to use this tool vs alternatives like modify_labels or archive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search a Gmail account with native Gmail query syntax (e.g. 'from:alice newer_than:7d has:attachment', 'in:anywhere subject:invoice'). Returns summaries with gmMsgId/gmThrId. Note: All Mail excludes Trash/Spam unless you add 'in:anywhere'.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Restrict to a specific label/mailbox path instead of All Mail. | |
| limit | No | Max results (default 25, newest first). | |
| query | Yes | Gmail search query (X-GM-RAW syntax). | |
| account | No | Gmail address to act on. Omit to use the default account. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint: true), the description adds key behavioral details: use of native Gmail syntax, return of summaries with specific IDs, default ordering (newest first), and the fact that Trash/Spam are excluded unless 'in:anywhere' is added. This provides valuable context for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3 sentences), front-loading the purpose, followed by examples and a critical note. Every sentence serves a clear purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description adequately explains the return format (summaries with gmMsgId/gmThrId) and critical behaviors like scope and ordering. It does not detail pagination or error cases, but those are secondary for this straightforward search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The tool description adds value with explicit query examples and contextual notes, enhancing understanding of the 'query' and 'limit' parameters beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: searching a Gmail account using native Gmail query syntax. It provides concrete examples and distinguishes from sibling tools like get_message or get_thread by emphasizing the search functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the query syntax and includes a useful note about the scope of 'All Mail' versus 'in:anywhere'. It implies when to use this tool (for searching) but does not explicitly contrast with alternatives like get_message or list_accounts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an email from the account via Gmail SMTP. A copy is filed in Sent automatically. This delivers real mail — confirm before running.
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | ||
| to | Yes | Recipient address(es). | |
| bcc | No | ||
| html | No | HTML body (optional). | |
| text | No | Plain-text body. | |
| account | No | Gmail address to act on. Omit to use the default account. | |
| subject | Yes | ||
| inReplyTo | No | RFC822 Message-ID being replied to; sets In-Reply-To/References so Gmail threads it. | |
| attachments | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint: true, but the description adds behavioral context: 'A copy is filed in Sent automatically' and 'This delivers real mail — confirm before running.' This provides meaningful detail beyond the annotations about automatic filing and finality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the action, and contains no unnecessary words. Every sentence adds value: purpose, automatic filing, and destructive warning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no output schema, sibling tools), the description is partially complete. It covers the main purpose and destructive nature, but lacks guidance on parameters and when to use alternatives like 'create_draft'. It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention any parameters or add meaning beyond the input schema. With 9 parameters and only 56% schema description coverage, the description should compensate by explaining key parameters like 'to', 'subject', or 'account', but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send an email from the account via Gmail SMTP', specifying the verb (send), resource (email), and context (Gmail SMTP). It distinguishes from the sibling tool 'create_draft' by noting that this sends real mail, not a draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description warns 'confirm before running' but does not provide explicit guidance on when to use this tool versus alternatives like 'create_draft' for drafts. It lacks context for appropriate versus inappropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Star a message.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Gmail address to act on. Omit to use the default account. | |
| gmMsgId | Yes | Gmail message id (X-GM-MSGID), as returned by search_messages or get_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It does not reveal whether starring is idempotent, what happens if the message is already starred, or any required permissions. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence), which is concise but lacks important behavioral and usage context. It could be expanded slightly without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple operation like starring with no output schema and two parameters, the description is minimally complete. However, it omits return value (void) and side effects. Acceptable but could be better.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters well. The description adds no extra meaning beyond 'star a message'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Star a message.' clearly states the action (star) and the resource (a message). It distinguishes from the sibling 'unstar' by implying the opposite operation. However, it lacks specificity about what 'star' means in the Gmail context (e.g., applying a star label).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'unstar' or 'modify_labels'. There is no context about prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a message to Trash (reversible for ~30 days).
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Gmail address to act on. Omit to use the default account. | |
| gmMsgId | Yes | Gmail message id (X-GM-MSGID), as returned by search_messages or get_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true. Description adds 'reversible for ~30 days', which is valuable behavioral context. No contradictory information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action, then temporal clarity. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple move-to-trash operation with clear schema and no output, the description is sufficient. Could mention handling of already-trashed messages, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions for both parameters. Description adds no further parameter meaning beyond 'Gmail message id' which is already in schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Move a message to Trash' – a specific verb and resource. Clearly distinguishes from siblings like delete_message (permanent deletion) and archive (different action). The reversible duration adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use for trashing messages but no explicit guidance on when not to use or alternatives. With siblings like delete_message and archive, a brief note on when to choose trash would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove the star from a message.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Gmail address to act on. Omit to use the default account. | |
| gmMsgId | Yes | Gmail message id (X-GM-MSGID), as returned by search_messages or get_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the action ('remove the star') but does not disclose any side effects, permissions, error conditions, or rate limits. With no annotations, the description carries full burden but is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded with the essential action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no annotations), the description sufficiently conveys the primary behavior. However, it lacks details on preconditions or results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already described. The description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove the star from a message' uses a specific verb ('Remove') and resource ('star from a message'), clearly distinguishing it from the sibling 'star' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 (e.g., 'star' for adding a star). The purpose is obvious but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0add_accountbulk_deletebulk_modify_labelsbulk_movebulk_trashempty_spamempty_trashmark_all_readv0.1.0archivecreate_draftcreate_labeldelete_messageget_attachmentget_messageget_threadlist_accountslist_labelsmark_readmark_unreadmodify_labelsmove_messagesearch_messagessend_messagestartrash_messageunstarScored across 26 tools
Each tool targets a distinct action, with clear separation between single and bulk operations, permanent and reversible deletes, and label vs folder moves. Descriptions clarify any potential overlap (e.g., archive vs modify_labels vs move_message).
Tool names follow multiple conventions: some use verb_noun (add_account, create_draft), some are plain verbs (archive, star), others have inconsistent patterns (bulk_delete vs delete_message, list_accounts vs get_message). No consistent verb or noun style across the set.
26 tools cover account management, message retrieval, sending, label manipulation, bulk actions, and trash/spam management. While the count is slightly high, each tool addresses a distinct function, and the scope justifies the number.
The set covers full lifecycle: account setup, message creation (draft/send), retrieval (by ID, search, thread), updates (labels, read state, stars, archive, move), and deletion (trash, permanent, bulk, empty trash/spam). No obvious gaps for standard email operations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Hosted email for AI agents: create inboxes, send, receive, and reply over MCP with scoped API keys
