gmail

search_email

Read-only

Search for emails in Gmail to find specific messages or filter the inbox. Use this when the user wants to find emails by sender, subject, date, content, or other criteria. Returns email summaries suitable for listing and overview - to read full email content, attachments, or HTML body, use get_email with the returned email ID. This tool searches across all folders unless specified otherwise in the query.

Input Schema

TableJSON Schema

Name	Required	Description
`query`	Yes	Search query using Gmail search syntax. Examples: - from:john@example.com (emails from specific sender) - to:jane@example.com (emails to specific recipient) - subject:meeting (emails with 'meeting' in subject) - has:attachment (emails with attachments) - is:unread (unread emails) - is:important (important emails) - after:2025/1/1 (emails after date) - before:2025/1/31 (emails before date) - newer_than:1d (emails from last day, use 1h for hour, 1w for week) - older_than:1d (emails older than 1 day) - label:inbox (emails in inbox) - in:sent (sent emails) - bare words search all fields Combine with AND/OR operators. Date format: YYYY/M/D or relative (1d, 1w, 1m).
`pageToken`	No	Token for fetching the next page of results
`maxResults`	No	Maximum number of results to return (default 10, max 100)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`emails`	Yes
`message`	No
`resultCount`	Yes
`nextPageToken`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedApr 7, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- addedOutput schema / properties / nextPageToken / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / properties / nextPageToken / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

Changed1 schema field changedFeb 9, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "emails": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "date": {
+            "type": "string"
+          },
+          "from": {
+            "type": "string"
+          },
+          "hasAttachments": {
+            "type": "boolean"
+          },
+          "id": {
+            "type": "string"
+          },
+          "labels": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "snippet": {
+            "type": "string"
+          },
+          "subject": {
+            "type": "string"
+          },
+          "threadId": {
+            "type": "string"
+          },
+          "to": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "threadId",
+          "subject",
+          "snippet",
+          "hasAttachments",
+          "labels"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "message": {
+      "type": "string"
+    },
+    "nextPageToken": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "resultCount": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "emails",
+    "nextPageToken",
+    "resultCount"
+  ],
+  "type": "object"
+}

First observedJan 31, 2026

TDQS

A4.5/5.0

Behavior4/5

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

The annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds valuable behavioral context beyond this: it specifies the search scope ('across all folders unless specified otherwise'), describes the return format ('email summaries suitable for listing and overview'), and implies pagination behavior (by referencing 'get_email with the returned email ID' for full content). However, it doesn't explicitly mention rate limits or authentication requirements, which could be useful additions.

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

Conciseness5/5

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

The description is appropriately sized and front-loaded, with three sentences that each serve a distinct purpose: stating the tool's function, providing usage guidelines, and clarifying scope. There is zero waste—every sentence adds value, and the structure flows logically from general purpose to specific instructions and limitations.

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?

Given the tool's complexity (search functionality with multiple parameters), rich schema (100% coverage with examples), annotations (clear read-only, non-destructive hints), and the presence of an output schema (implied by context signals), the description is complete enough. It covers purpose, usage, scope, and output format without needing to repeat schema details or explain return values, which the output schema will handle.

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 the schema already documents all three parameters thoroughly with examples and defaults. The description adds minimal parameter semantics beyond the schema—it mentions 'query' implicitly through search criteria but doesn't provide additional syntax or format details. This meets the baseline of 3 when the schema does the heavy lifting, but the description doesn't compensate with extra insights like query construction tips or pagination strategies.

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

Purpose5/5

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

The description clearly states the tool's purpose with specific verb ('Search for emails in Gmail') and resource ('emails'), distinguishing it from siblings like 'get_email' (which retrieves full content) and 'list_labels' (which deals with labels). It specifies the search scope ('across all folders unless specified otherwise') and filtering capabilities ('by sender, subject, date, content, or other criteria').

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?

The description provides explicit guidance on when to use this tool ('when the user wants to find emails by sender, subject, date, content, or other criteria') and when to use an alternative ('to read full email content, attachments, or HTML body, use get_email with the returned email ID'). It also clarifies the scope ('searches across all folders unless specified otherwise'), helping differentiate from potential sibling tools that might filter differently.

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

All gmail tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.