Email MCP Server

Search emails

search_emails

Read-only

Find emails by keyword, sender, recipient, date range, attachment, size, or reply status. Omit keyword to filter by sender or other criteria.

Instructions

Search emails by keyword across subject, sender, and body — and, where the local mirror is enabled, attachment filenames (searching "report" finds an email carrying Q3-report.pdf). Omit query (or pass an empty string) to use it as a pure filter — e.g. find all emails from a specific sender without a keyword. Supports additional filters for sender, recipient, date range (since/before — INTERNALDATE; sent_since/sent_before — Date: header), attachments, size, and reply status. At least one of query/from/to/since/before/sent_since/sent_before/has_attachment/larger_than/smaller_than/answered must be set; otherwise the call errors (use list_emails to browse without filters). Results carry the same 📰 newsletter / 🤖 automated markers as list_emails.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`to`	No	Filter by recipient address
`from`	No	Filter by sender address (substring match)
`page`	No	Page number
`query`	No	Search keyword across subject, sender, and body (omit to use filters only)
`since`	No	Only emails received on/after this date (ISO 8601, e.g. 2026-05-11T00:00:00Z)
`before`	No	Only emails received before this date (ISO 8601)
`account`	Yes	Account name from list_accounts
`mailbox`	No	Mailbox path (default: INBOX)	INBOX
`preview`	No	Include a ~200 character body preview per message. Off by default: it fetches extra bytes per message and lengthens the output.
`answered`	No	Filter: true=replied, false=not replied
`pageSize`	No	Results per page
`sent_since`	No	Only emails with Date: header on/after this date (ISO 8601)
`larger_than`	No	Minimum email size in KB
`sent_before`	No	Only emails with Date: header before this date (ISO 8601)
`smaller_than`	No	Maximum email size in KB
`has_attachment`	No	Filter: true=has attachments, false=no attachments

Output Schema

TableJSON Schema

Name	Required	Description	Default
`page`	Yes
`cache`	No
`count`	Yes
`total`	Yes
`emails`	Yes
`account`	Yes
`hasMore`	Yes
`mailbox`	Yes
`pageSize`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.6.0Oct 17, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / properties / before

Added value: +{
+  "description": "Only emails received before this date (ISO 8601)",
+  "type": "string"
+}

addedInput schema / properties / from

Added value: +{
+  "description": "Filter by sender address (substring match)",
+  "type": "string"
+}

addedInput schema / properties / preview

Added value: +{
+  "default": false,
+  "description": "Include a ~200 character body preview per message. Off by default: it fetches extra bytes per message and lengthens the output.",
+  "type": "boolean"
+}

changedInput schema / properties / query / description

Previous value: -"Search keyword (omit or leave empty to use filters only)"New value: +"Search keyword across subject, sender, and body (omit to use filters only)"

addedInput schema / properties / sent_before

Added value: +{
+  "description": "Only emails with Date: header before this date (ISO 8601)",
+  "type": "string"
+}

addedInput schema / properties / sent_since

Added value: +{
+  "description": "Only emails with Date: header on/after this date (ISO 8601)",
+  "type": "string"
+}

addedInput schema / properties / since

Added value: +{
+  "description": "Only emails received on/after this date (ISO 8601, e.g. 2026-05-11T00:00:00Z)",
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "account": {
+      "type": "string"
+    },
+    "cache": {
+      "additionalProperties": false,
+      "properties": {
+        "offline": {
+          "const": true,
+          "type": "boolean"
+        },
+        "source": {
+          "const": "cache",
+          "type": "string"
+        },
+        "stale": {
+          "const": true,
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "source"
+      ],
+      "type": "object"
+    },
+    "count": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "emails": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "answered": {
+            "type": "boolean"
+          },
+          "bulk": {
+            "additionalProperties": false,
+            "properties": {
+              "kind": {
+                "enum": [
+                  "newsletter",
+                  "automated"
+                ],
+                "type": "string"
+              },
+              "listId": {
+                "type": "string"
+              },
+              "oneClick": {
+                "type": "boolean"
+              },
+              "unsubscribe": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "kind",
+              "oneClick"
+            ],
+            "type": "object"
+          },
+          "date": {
+            "type": "string"
+          },
+          "flagged": {
+            "type": "boolean"
+          },
+          "from": {
+            "additionalProperties": false,
+            "properties": {
+              "address": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "address"
+            ],
+            "type": "object"
+          },
+          "hasAttachments": {
+            "type": "boolean"
+          },
+          "id": {
+            "type": "string"
+          },
+          "labels": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "preview": {
+            "type": "string"
+          },
+          "seen": {
+            "type": "boolean"
+          },
+          "subject": {
+            "type": "string"
+          },
+          "to": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "address": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "address"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "id",
+          "subject",
+          "from",
+          "to",
+          "date",
+          "seen",
+          "flagged",
+          "answered",
+          "hasAttachments",
+          "labels"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "hasMore": {
+      "type": "boolean"
+    },
+    "mailbox": {
+      "type": "string"
+    },
+    "page": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "pageSize": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "total": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "account",
+    "mailbox",
+    "total",
+    "page",
+    "pageSize",
+    "hasMore",
+    "count",
+    "emails"
+  ],
+  "type": "object"
+}

First observedv0.2.3Jul 30, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds real context beyond them: the attachment-filename search is conditional on the local mirror being enabled, results carry the same newsletter/automated markers as list_emails, and an unset-filter call is an error rather than a no-op. It does not cover pagination limits or result ordering, but the error semantics and mirror dependency are meaningful disclosures.

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

Conciseness4/5

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

The keyword-search capability is front-loaded, followed by filter guidance, the precondition, and the sibling reference, in a logical order with no filler sentences. It is on the long side, but each sentence conveys a distinct constraint an agent would otherwise have to discover by failing a call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter search tool with an output schema present, the description need not explain return values, and it covers the remaining risk areas: filter precondition, query-optional behavior, searchable fields, date-field semantics, and the list_emails fallback. An agent has everything needed to invoke it correctly.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra credit: it explains that an omitted/empty query turns the tool into a pure filter, gives the 'report' → Q3-report.pdf example for attachment matching, and crucially distinguishes since/before (INTERNALDATE) from sent_since/sent_before (Date: header), a semantic split the schema does not spell out.

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

Purpose5/5

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

States a specific verb and resource ('Search emails by keyword across subject, sender, and body') plus the scope of extra coverage (attachment filenames when the local mirror is on). It explicitly positions itself against list_emails for the unfiltered browse case, so an agent can distinguish the two without opening any schema.

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

Usage Guidelines5/5

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

Gives concrete when-to-use cases (filter-only search by omitting query, example of finding a sender's mail without a keyword), states the hard precondition that at least one of the listed filters must be set or the call errors, and names the alternative for the no-filter case (list_emails). Nothing is left to inference.

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

Deploy Server