Skip to main content
Glama
alexneamtu

Gmail MCP

by alexneamtu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

search_messages

Read-onlyIdempotent

Find Gmail messages using Gmail search syntax; returns message and thread IDs for get_message or get_thread to retrieve content.

Instructions

Find messages with Gmail search syntax. Returns only {messages:[{id,threadId}],nextPageToken,resultSizeEstimate}, newest first, with no content: pass an id to get_message or a threadId to get_thread. messages is absent when nothing matches.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryYesGmail search query, same syntax as the Gmail search box, e.g. "from:alice@example.com is:unread newer_than:7d". Empty string matches all mail except spam and trash.
accountYesAccount alias from list_accounts; selects which mailbox to use.
pageTokenNonextPageToken from a previous call with the same query, to fetch the next page.
maxResultsNoMessages per page, 1-50. Default 20.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / account / description
      Added value: +"Account alias from list_accounts; selects which mailbox to use."
    • addedInput schema / properties / maxResults / description
      Added value: +"Messages per page, 1-50. Default 20."
    • addedInput schema / properties / pageToken / description
      Added value: +"nextPageToken from a previous call with the same query, to fetch the next page."
    • addedInput schema / properties / query / description
      Added value: +"Gmail search query, same syntax as the Gmail search box, e.g. \"from:alice@example.com is:unread newer_than:7d\". Empty string matches all mail except spam and trash."
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already cover safety (readOnly, idempotent, openWorld, non-destructive), so the description spends its words on non-obvious behavior instead: exact return shape, newest-first ordering, no message bodies, and the quirk that `messages` is absent (not an empty array) when nothing matches. That last detail is the kind of thing that causes agent bugs and is not derivable from any structured field.

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?

A single dense sentence, front-loaded with the verb and search mechanism, then return shape, then the routing hint, then the empty-result edge case. No filler and no repetition of schema content.

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?

There is no output schema, so the description carries the return-value burden and does so precisely (shape, ordering, absence semantics). Combined with a fully documented 4-parameter schema and complete annotations, an agent has everything needed to call and interpret this tool.

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 every parameter (query syntax, account alias, pageToken, maxResults bounds) is already documented in the schema. The description only restates the query syntax and the id/threadId relationship, adding no format or constraint detail beyond what the schema provides, so the baseline 3 applies.

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 (Find) plus resource (messages) and the exact matching mechanism (Gmail search syntax), which distinguishes it from get_message/get_thread that fetch content by id. An agent can separate this from every sibling without opening a schema.

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?

It routes the agent forward explicitly: pass an id to get_message or a threadId to get_thread, which effectively says 'do not use this tool to read content.' That covers the main alternative, but it says nothing about the account-scoping choice or when a search is preferable to listing labels/accounts.

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

Deploy Server

Other Tools