Skip to main content
Glama

Search Emails

search-emails
Read-onlyIdempotent

Find Outlook emails by sender, recipient, subject, date, folder, or query; list results, group conversations, sync changes, and search shared mailboxes read-only.

Instructions

Search, list, delta-sync or thread-group emails (read-only); parameters set the mode. No params: recent emails in folder (default inbox). query/from/to/subject/date filters: search, combined as an OData filter. searchExpression (deprecated alias kqlQuery): a raw Graph $search expression. deltaMode: true: current state plus a deltaToken to pass back next time for changes only. groupByConversation: true: conversation threads. conversationId: every message in one thread. internetMessageId: the message with that RFC Message-ID. sharedMailbox (alias email) searches a shared/delegated mailbox, custom folders and nested paths included. Graph $search takes no other filter: a query that needs one is answered by OData filters or local matching, and a searchExpression reports the filters it could not apply. _meta.searchMetadata names the strategy that answered. Returns up to count messages (id/subject/from/receivedDateTime/preview); outputVerbosity expands them.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search-emails"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoFilter by recipient email/name. Personal Outlook.com accounts reject the server-side recipient filter, in which case this is matched locally over the 500 most recent messages only (raise with `OUTLOOK_SEARCH_SCAN_LIMIT`). On a large archive, pair `to` with `receivedAfter`/`receivedBefore` to reach older mail; the response says so when the scan was truncated.
fromNoFilter by sender email/name
countNoNumber of results (list default: 25, search default: 10, max: 50). There is no page cursor: when the result says more emails are available, raise `count` or narrow `receivedAfter`/`receivedBefore`.
emailNoAlias for `sharedMailbox`.
queryNoFree-text search. Omit for list mode. Alone or with only date and boolean filters, it is sent to Graph `$search`, which matches subject, body and sender. `$search` takes no other filters, so those are applied to its results, newest first, reading at most 250. With `from`, `to` or `subject`, those go to Graph as a filter and `query` is matched against each result's subject, preview and sender. If nothing passes, this falls back to a subject substring match (all words must appear in the subject) with the filters applied server-side. The response names the strategy used and says when coverage was partial.
folderNoEmail folder (default: 'inbox'). Accepts a well-known name, a custom/localized display name, or a nested path like `Inbox/Subfolder`.
subjectNoFilter by subject
kqlQueryNoDEPRECATED alias for `searchExpression` (this was never full KQL — it is a Graph `$search` expression).
deltaModeNoEnable delta sync mode. Returns only changes since last sync. Use deltaToken for subsequent calls; an initial sync larger than `maxResults` arrives over several pages, each returning a continuation token to pass back until a delta token is returned. Honors `sharedMailbox`/`email` (and custom `folder` paths) to sync within a shared/delegated mailbox.
deltaTokenNoToken from previous delta call for incremental sync (deltaMode only). The token is authoritative — it encodes its own mailbox and folder, so `folder`/`sharedMailbox` are ignored and a token from a different mailbox is rejected.
maxResultsNoDelta sync page size (deltaMode only): 1-200, default 100, sent to Graph as the `Prefer: odata.maxpagesize` header. It sizes each page, not the whole sync: while a page returns a continuation token, keep calling with that token until a delta token is returned, and pass the same `maxResults` on every page (an omitted value means 100).
unreadOnlyNoFilter to unread emails only
receivedAfterNoFilter emails received after date (ISO 8601)
sharedMailboxNoEmail address of a shared/delegated mailbox to search (default: the signed-in account). Combine with `folder` (incl. custom subfolders/paths) or `searchAllFolders`. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).
conversationIdNoGet the messages in a conversation thread by conversationId, oldest first (up to 100; a longer thread is marked truncated — use `export target=conversation` for up to 1000). Honors `sharedMailbox`/`email` to thread within a shared/delegated mailbox.
hasAttachmentsNoFilter to emails with attachments
includeHeadersNoInclude email headers for each message (conversationId only)
receivedBeforeNoFilter emails received before date (ISO 8601)
outputVerbosityNoOutput detail level (default: standard)
searchAllFoldersNoSearch across all mail folders
searchExpressionNoRaw Microsoft Graph `$search` expression (KQL), e.g. `subject:"quarterly report" AND received>=2026-01-01`, `invoice OR receipt`. It takes the place of the other search params. It is sent to Graph as one double-quoted string, the form Graph reads as KQL (as written when it already is one, otherwise wrapped with its `"` and `\` escaped); `receivedAfter`/`receivedBefore`/`hasAttachments`/`unreadOnly` are then not applied (they come back in `droppedFilters`), so dates go in the expression. Operators are upper-case (`AND`, `OR`, `NOT`). Terms match whole words or their beginnings; results are newest first; with `searchAllFolders: true` Graph leaves out Deleted Items and Junk Email. Exception: an expression made only of `from:`/`to:`/`subject:` terms is sent as written, and when Graph rejects it (personal accounts do) or finds nothing it is run as OData filters: substring match, date and boolean params applied, strategy `raw-kql-translated`. Any other expression that finds nothing ends with no results.
internetMessageIdNoLook up email by Message-ID header (e.g. <abc123@example.com>). For threading/deduplication. Honors `sharedMailbox`/`email` to look up within a shared/delegated mailbox.
groupByConversationNoList conversations (threads) grouped by conversationId, not individual emails. Honors `sharedMailbox`/`email` (and custom `folder` paths) to group within a shared/delegated mailbox.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv3.14.2
    • changedInput schema / properties / query / description
      Previous value: -"Search query text. Omit for list mode. On personal Outlook.com accounts Graph `$search` is unavailable, so this falls back to a subject substring match (all words must appear in the subject) — precise, but it does NOT search message bodies. Use `searchExpression` when you need body content."New value: +"Free-text search. Omit for list mode. Alone or with only date and boolean filters, it is sent to Graph `$search`, which matches subject, body and sender. `$search` takes no other filters, so those are applied to its results, newest first, reading at most 250. With `from`, `to` or `subject`, those go to Graph as a filter and `query` is matched against each result's subject, preview and sender. If nothing passes, this falls back to a subject substring match (all words must appear in the subject) with the filters applied server-side. The response names the strategy used and says when coverage was partial."
    • changedInput schema / properties / searchExpression / description
      Previous value: -"Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:\"invoice\"`, `from:github.com`, or `foo OR bar`. Quote your own phrases, escaping any `\"` or `\\` inside them with a backslash; a single bare token is auto-quoted and escaped for you. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there. RELEVANCE, NOT RECENCY: an untranslated expression is answered by Graph `$search` over the whole message including the body, ranked by relevance and not sorted by date, so top hits can look unrelated to a caller expecting a subject match. `query` is the more predictable choice for a term you expect in a subject line; `searchExpression` is the one that reaches body text."New value: +"Raw Microsoft Graph `$search` expression (KQL), e.g. `subject:\"quarterly report\" AND received>=2026-01-01`, `invoice OR receipt`. It takes the place of the other search params. It is sent to Graph as one double-quoted string, the form Graph reads as KQL (as written when it already is one, otherwise wrapped with its `\"` and `\\` escaped); `receivedAfter`/`receivedBefore`/`hasAttachments`/`unreadOnly` are then not applied (they come back in `droppedFilters`), so dates go in the expression. Operators are upper-case (`AND`, `OR`, `NOT`). Terms match whole words or their beginnings; results are newest first; with `searchAllFolders: true` Graph leaves out Deleted Items and Junk Email. Exception: an expression made only of `from:`/`to:`/`subject:` terms is sent as written, and when Graph rejects it (personal accounts do) or finds nothing it is run as OData filters: substring match, date and boolean params applied, strategy `raw-kql-translated`. Any other expression that finds nothing ends with no results."
  2. Changed12 schema fields changedv3.14.1
    • changedInput schema / properties / conversationId / description
      Previous value: -"Get all messages in a conversation thread by conversationId."New value: +"Get the messages in a conversation thread by conversationId, oldest first (up to 100; a longer thread is marked truncated — use `export target=conversation` for up to 1000). Honors `sharedMailbox`/`email` to thread within a shared/delegated mailbox."
    • changedInput schema / properties / count / description
      Previous value: -"Number of results (list default: 25, search default: 10, max: 50)"New value: +"Number of results (list default: 25, search default: 10, max: 50). There is no page cursor: when the result says more emails are available, raise `count` or narrow `receivedAfter`/`receivedBefore`."
    • changedInput schema / properties / deltaMode / description
      Previous value: -"Enable delta sync mode. Returns only changes since last sync. Use deltaToken for subsequent calls."New value: +"Enable delta sync mode. Returns only changes since last sync. Use deltaToken for subsequent calls; an initial sync larger than `maxResults` arrives over several pages, each returning a continuation token to pass back until a delta token is returned. Honors `sharedMailbox`/`email` (and custom `folder` paths) to sync within a shared/delegated mailbox."
    • changedInput schema / properties / deltaToken / description
      Previous value: -"Token from previous delta call for incremental sync (deltaMode only)"New value: +"Token from previous delta call for incremental sync (deltaMode only). The token is authoritative — it encodes its own mailbox and folder, so `folder`/`sharedMailbox` are ignored and a token from a different mailbox is rejected."
    • addedInput schema / properties / email
      Added value: +{
      +  "description": "Alias for `sharedMailbox`.",
      +  "type": "string"
      +}
    • changedInput schema / properties / folder / description
      Previous value: -"Email folder (default: 'inbox')"New value: +"Email folder (default: 'inbox'). Accepts a well-known name, a custom/localized display name, or a nested path like `Inbox/Subfolder`."
    • changedInput schema / properties / groupByConversation / description
      Previous value: -"List conversations (threads) grouped by conversationId instead of individual emails."New value: +"List conversations (threads) grouped by conversationId, not individual emails. Honors `sharedMailbox`/`email` (and custom `folder` paths) to group within a shared/delegated mailbox."
    • changedInput schema / properties / internetMessageId / description
      Previous value: -"Look up email by Message-ID header (e.g. <abc123@example.com>). For threading/deduplication."New value: +"Look up email by Message-ID header (e.g. <abc123@example.com>). For threading/deduplication. Honors `sharedMailbox`/`email` to look up within a shared/delegated mailbox."
    • changedInput schema / properties / kqlQuery / description
      Previous value: -"DEPRECATED alias for `searchExpression` (this was never full KQL — it is a Graph `$search` expression). Prefer `searchExpression`."New value: +"DEPRECATED alias for `searchExpression` (this was never full KQL — it is a Graph `$search` expression)."
    • changedInput schema / properties / maxResults / description
      Previous value: -"Max results per page for delta sync (default: 100, max: 200)"New value: +"Delta sync page size (deltaMode only): 1-200, default 100, sent to Graph as the `Prefer: odata.maxpagesize` header. It sizes each page, not the whole sync: while a page returns a continuation token, keep calling with that token until a delta token is returned, and pass the same `maxResults` on every page (an omitted value means 100)."
    • changedInput schema / properties / searchExpression / description
      Previous value: -"Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:\"invoice\"`, `from:github.com`, or `foo OR bar`. Quote your own phrases; a single bare token is auto-quoted. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there. RELEVANCE, NOT RECENCY: an untranslated expression is answered by Graph `$search` over the whole message including the body, ranked by relevance and not sorted by date, so top hits can look unrelated to a caller expecting a subject match. `query` is the more predictable choice for a term you expect in a subject line; `searchExpression` is the one that reaches body text."New value: +"Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:\"invoice\"`, `from:github.com`, or `foo OR bar`. Quote your own phrases, escaping any `\"` or `\\` inside them with a backslash; a single bare token is auto-quoted and escaped for you. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there. RELEVANCE, NOT RECENCY: an untranslated expression is answered by Graph `$search` over the whole message including the body, ranked by relevance and not sorted by date, so top hits can look unrelated to a caller expecting a subject match. `query` is the more predictable choice for a term you expect in a subject line; `searchExpression` is the one that reaches body text."
    • addedInput schema / properties / sharedMailbox
      Added value: +{
      +  "description": "Email address of a shared/delegated mailbox to search (default: the signed-in account). Combine with `folder` (incl. custom subfolders/paths) or `searchAllFolders`. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).",
      +  "type": "string"
      +}
  3. Changed3 schema fields changedv3.11.1
    • changedInput schema / properties / query / description
      Previous value: -"Search query text. Omit for list mode."New value: +"Search query text. Omit for list mode. On personal Outlook.com accounts Graph `$search` is unavailable, so this falls back to a subject substring match (all words must appear in the subject) — precise, but it does NOT search message bodies. Use `searchExpression` when you need body content."
    • changedInput schema / properties / searchExpression / description
      Previous value: -"Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:\"invoice\"`, `from:github.com`, or `foo OR bar`. Quote your own phrases; a single bare token is auto-quoted. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: on personal Outlook.com accounts field-scoped `$search` is best-effort and may return nothing — prefer `query` there (it has progressive fallback)."New value: +"Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:\"invoice\"`, `from:github.com`, or `foo OR bar`. Quote your own phrases; a single bare token is auto-quoted. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there. RELEVANCE, NOT RECENCY: an untranslated expression is answered by Graph `$search` over the whole message including the body, ranked by relevance and not sorted by date, so top hits can look unrelated to a caller expecting a subject match. `query` is the more predictable choice for a term you expect in a subject line; `searchExpression` is the one that reaches body text."
    • changedInput schema / properties / to / description
      Previous value: -"Filter by recipient email/name"New value: +"Filter by recipient email/name. Personal Outlook.com accounts reject the server-side recipient filter, in which case this is matched locally over the 500 most recent messages only (raise with `OUTLOOK_SEARCH_SCAN_LIMIT`). On a large archive, pair `to` with `receivedAfter`/`receivedBefore` to reach older mail; the response says so when the scan was truncated."
  4. Addedv3.9.1
  5. Removedv3.9.0
  6. Changed1 schema field changedv3.7.4
    • addedInput schema / additionalProperties
      Added value: +false
  7. First observedv3.4.1

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing account-type quirks (personal Outlook.com rejects the server-side recipient filter, falling back to a 500-message local scan tunable via OUTLOOK_SEARCH_SCAN_LIMIT), an environment opt-in gate for shared mailboxes that can refuse the call, delta-token authority (token encodes mailbox/folder, mismatched mailbox rejected), truncation signaling, and the `_meta.searchMetadata` strategy field. These are exactly the operational caveats an agent needs and none are derivable from readOnlyHint/openWorldHint/idempotentHint.

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

Conciseness3/5

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

The mode summary is correctly front-loaded and nearly every clause carries information, but the prose is a semicolon-chained block with no bullets or mode headings, and it duplicates a good deal of the schema text verbatim. For a 23-parameter tool some length is warranted, but the density and lack of scannable structure cost it.

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 23-parameter, multi-mode tool with no output schema, the description covers return contents (id/subject/from/receivedDateTime/preview, expandable via outputVerbosity), pagination behavior (no cursor; raise count or narrow dates; delta continuation tokens), fallback strategies, and failure/partial-coverage reporting. An agent could invoke nearly every mode correctly using this text alone.

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

Parameters3/5

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

Schema description coverage is 100% and the individual parameter descriptions are unusually thorough, so the baseline is 3. The description adds value mainly by synthesizing which parameter combination triggers which mode, plus a brief return-shape note, but it largely mirrors content already present in the schema rather than adding new per-parameter meaning.

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

Purpose4/5

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

The opening sentence names specific verbs and the resource ('Search, list, delta-sync or thread-group emails') and explains that the parameters select the mode, so an agent immediately knows this is the multi-mode mailbox retrieval tool rather than a single-message reader. It never names a sibling tool (e.g. read-email or export) to draw the boundary, and the internetMessageId lookup overlaps conceptually with a single-message read, so differentiation is implied rather than explicit.

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

Usage Guidelines4/5

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

Provides near-explicit mode-routing rules: no params means recent mail in `folder`; query/from/to/subject/date means search; deltaMode means sync; groupByConversation/conversationId/internetMessageId each select a distinct retrieval shape. It also states exclusions ('searchExpression takes the place of the other search params', date/boolean filters are then not applied and appear in `droppedFilters'). It stops short of naming alternative tools for overlapping tasks, so it stays at 4 rather than 5.

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