Skip to main content
Glama
Sign In
gmail-mcp

gmail-mcp

by DimitrisPasakaleris
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

list_emails

Search Gmail inbox by query and retrieve email IDs, subjects, and snippets for reading or replying. Supports Gmail search syntax to filter by sender, subject, date, or attachments.

Instructions

Search inbox for emails matching a query string.

Returns a list of emails with their IDs, subjects, from addresses, dates,
snippets, and labels. IDs can be passed to read_email or reply_email.

Required: none — both params have defaults.
Optional:
  query (str, default="") — Gmail search syntax.
    Examples: "from:alice@example.com", "subject:invoice is:unread",
    "after:2026/01/01 before:2026/01/31", "has:attachment".
    Leave empty to get most recent inbox emails.
  max_results (int, default=5) — how many emails to return. Max 500.

Returns on success:
  {"total": N, "emails": [{"id": "...", "subject": "...", "from": "...",
     "date": "...", "snippet": "...", "labels": [...]}]}

Workflow note: The "id" field in each email is a Gmail message ID —
  pass it to read_email, reply_email, or get_thread_messages.
  Leave query empty to get recent inbox. Use Gmail search syntax
  to filter: from:, subject:, after:, before:, is:unread, has:attachment.

Input Schema

NameRequiredDescriptionDefault
queryNo
max_resultsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it declares defaults for both params, a hard cap of 500 results, the exact success payload shape, and the downstream workflow. It omits read-only/auth framing and any pagination or error behavior, so not a 5.

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?

Front-loaded with the action, then structured sections for params and returns. Slightly redundant: the Gmail search operators are listed once in the query examples and again verbatim in the workflow note, which could be trimmed.

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?

No output schema exists, yet the description supplies the return JSON shape with every field named, plus defaults and limits. An agent has everything needed to call this correctly and to know what it gets back.

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

Parameters5/5

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

Schema coverage is 0%, so the description must compensate and it does: query is explained with four concrete Gmail syntax examples and the empty-string behavior, and max_results gets both a default and an upper bound of 500.

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 ("Search inbox for emails") plus the matching criterion (query string), and notes the returned IDs feed read_email/reply_email. It does not explicitly distinguish itself from near-siblings like read_emails or read_emails_full, which keeps it just short of a 5.

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?

Gives concrete when-to-use context: leave query empty for most recent inbox, use Gmail operators to filter, and pass returned IDs onward. It stops short of naming an alternative tool and when to prefer it over read_emails_full or search_and_save.

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