Skip to main content
Glama
Sign In
gmail-mcp

gmail-mcp

by DimitrisPasakaleris
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

read_emails

Fetch full content from multiple Gmail messages in one request, bundling API calls into batches and saving large results to a file with a compact summary.

Instructions

CHOICE HINT: When the user asks to "read", "show", or "fetch" content from
multiple emails (e.g. "read these 5 emails", "show me the latest 3 emails"),
ALWAYS prefer this tool over making N calls to read_email(). It bundles all
Gmail API calls into bounded HTTP batches.

Fetch full content of multiple emails in a single MCP request.

Uses googleapiclient.http.BatchHttpRequest — calls are bundled
into batches of up to 100 per HTTP round-trip.
Handles up to 100 messages per call automatically.

Optional:
  save_to_file (bool, default=False) — force save all results to a
    .md file regardless of size. Useful for large fetches.
  max_chars (int, default=30000) — if estimated output exceeds this,
    auto-saves to .md and returns a compact summary with the file path.

Returns on success (small):
  {"ok": true, "data": {
    "requested": N, "succeeded": N, "failed": 0,
    "results": [{"id": "...", "ok": true, "data": {...}}, ...]
  }}

Returns on success (large / save_to_file):
  {"ok": true, "data": {
    "saved": true,
    "path": "C:\Users\...\gmail-mcp\emails\2026-05-11-piraeus-49.md",
    "count": 49,
    "size_bytes": 184523,
    "summary_table": "## Summary

| # | Date | From | Subject | ...|", "requested": 49, "succeeded": 49, "failed": 0, "results": [{"id": "...", "ok": true, "data": {"date": "...", "from": "...", "subject": "...", "snippet": "...", "labels": [...]}} ...] }}

Workflow note: Use this instead of N calls to read_email() to bundle
  all fetches into a single MCP request. Each result has the same
  shape as a read_email() response.

Input Schema

NameRequiredDescriptionDefault
max_charsNo
message_idsYes
save_to_fileNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4/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 discloses the BatchHttpRequest batching model, the 100-message cap, the auto-save threshold behavior triggered by max_chars, and the two distinct return shapes including partial-failure counts. What it omits is auth/permission requirements and whether a partial failure still returns ok=true or raises per-message errors.

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 choice hint, then the one-line purpose, then params and returns — a sensible ordering. The two verbose return-shape JSON blocks are defensible since there is no output schema, but they are somewhat redundant with each other and the summary_table example is padded.

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?

No output schema and no annotations, so the description has to supply both the behavioral model and the result shape — and it does, including file-save behavior and per-message success/failure. It is close to complete for a 3-parameter batch fetch, with only the message_ids contract and the read_emails_full distinction outstanding.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate — and it does for two of three parameters, giving defaults and precise semantics for save_to_file and max_chars (auto-save above threshold). The required message_ids parameter is only implicit ('multiple emails', 'up to 100 messages'), with no guidance on where IDs come from or how invalid IDs are reported.

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: 'Fetch full content of multiple emails in a single MCP request', and immediately frames it as the batched alternative to read_email(). The only weakness is that the sibling read_emails_full is never mentioned, so an agent cannot tell from this text which of those two to prefer.

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?

The CHOICE HINT gives concrete trigger phrases ('read these 5 emails', 'show me the latest 3 emails') and an explicit rule to prefer this over N calls to read_email(). It lacks any when-not-to-use condition, and does not address the read_emails_full alternative.

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