Google Workspace MCP Server - Control Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms & Drive

Search Gmail Messages

search_gmail_messages

Read-onlyIdempotent

Search Gmail messages by query and return message and thread IDs plus web links for verification. Supports pagination to retrieve results page by page.

Instructions

Searches messages in a user's Gmail account based on a query. Returns both Message IDs and Thread IDs for each found message, along with Gmail web interface links for manual verification. Supports pagination via page_token parameter.

Input Schema

Name	Required	Description
`query`	Yes	The search query. Supports standard Gmail search operators. Results include drafts unless the query excludes them (e.g. in:sent or -in:drafts).
`page_size`	No	The maximum number of messages to return. Defaults to 10.
`page_token`	No	Token for retrieving the next page of results. Use the next_page_token from a previous response.
`include_headers`	No	If True, also fetch each message's metadata and include Subject, From, Date and label IDs (e.g. DRAFT, SENT) per result. Costs one metadata get per result, grouped into HTTP batches of up to 10, plus retries for transient failures. Defaults to False (output unchanged from prior versions).
`user_google_email`	Yes	The user's Google email address. Required.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.2.0Oct 24, 2026

changedInput schema / properties / include_headers / description

Previous value: -"If True, also fetch each message's metadata and include\nSubject, From, and Date per result. Costs one metadata get per result,\ngrouped into HTTP batches of up to 10, plus retries for transient failures.\nDefaults to False (output unchanged from prior versions)."New value: +"If True, also fetch each message's metadata and include\nSubject, From, Date and label IDs (e.g. DRAFT, SENT) per result. Costs one\nmetadata get per result, grouped into HTTP batches of up to 10, plus retries\nfor transient failures.\nDefaults to False (output unchanged from prior versions)."

changedInput schema / properties / query / description

Previous value: -"The search query. Supports standard Gmail search operators."New value: +"The search query. Supports standard Gmail search operators.\nResults include drafts unless the query excludes them (e.g. in:sent or -in:drafts)."

Changed2 schema fields changedv1.28.0Sep 24, 2026
- removedInput schema / properties / page_token / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedInput schema / properties / page_token / type
```
Added value: +"string"
```

Changed1 schema field changedv1.24.0Aug 13, 2026

addedInput schema / properties / include_headers

Added value: +{
+  "default": false,
+  "description": "If True, also fetch each message's metadata and include\nSubject, From, and Date per result. Costs one metadata get per result,\ngrouped into HTTP batches of up to 10, plus retries for transient failures.\nDefaults to False (output unchanged from prior versions).",
+  "type": "boolean"
+}

Changed12 schema fields changedv1.0.1Jul 31, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / page_size / description

Added value: +"The maximum number of messages to return. Defaults to 10."

removedInput schema / properties / page_size / title
```
Removed value: -"Page Size"
```

addedInput schema / properties / page_token

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Token for retrieving the next page of results. Use the next_page_token from a previous response."
+}

addedInput schema / properties / query / description

Added value: +"The search query. Supports standard Gmail search operators."

removedInput schema / properties / query / title
```
Removed value: -"Query"
```

removedInput schema / properties / service

Removed value: -{
-  "title": "service",
-  "type": "string"
-}

addedInput schema / properties / user_google_email / description
```
Added value: +"The user's Google email address. Required."
```
removedInput schema / properties / user_google_email / title
```
Removed value: -"User Google Email"
```

changedInput schema / required

Previous value: -[
-  "service",
-  "query",
-  "user_google_email"
-]New value: +[
+  "query",
+  "user_google_email"
+]

removedInput schema / title

Removed value: -"search_gmail_messagesArguments"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "result": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "type": "object",
+  "x-fastmcp-wrap-result": true
+}

First observedv1.0.0Jun 10, 2025

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is fully covered. The description adds that results include Message IDs, Thread IDs and web interface links, plus pagination support, but these largely restate what the output schema and the page_token schema entry already say. No disclosure of rate limits, quota costs, or result ordering.

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?

Three short sentences with the core action front-loaded and no filler. The opening sentence earns its place; the pagination sentence is somewhat redundant with the schema but is cheap and oriented toward a practical workflow concern.

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

Completeness4/5

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

With an output schema present, rich annotations, and 100% schema description coverage, the description is complete enough to invoke correctly: it names the account parameter implicitly, the query, and the return shape. Missing only explicit routing guidance to the content-fetch siblings, which is a minor gap given the tool set.

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%, so all five parameters including the include_headers cost note and Gmail operator support are fully documented in the schema. The description's only parameter reference (page_token pagination) adds nothing beyond the schema's own explanation. Baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource ('Searches messages in a user's Gmail account based on a query') and clarifies the output is IDs plus web links, which implicitly separates it from content-fetching siblings like get_gmail_message_content and get_gmail_thread_content. It stops short of explicitly naming a sibling it is not, so it stays at 4 rather than 5.

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

Usage Guidelines3/5

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

Usage is only implied: returning IDs and verification links signals this is a discovery step before reading content with the get_*_gmail_* tools, and the mention of page_token implies multi-page retrieval. There is no explicit 'use this instead of X when Y' or any exclusion beyond what the schema carries.

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

Deploy Server