[Gmail MCP] Add get_attachment tool to download message attachments

[bam2026]

Gap

The Gmail MCP connector exposes `search_threads`, `get_thread`, `create_draft`, `create_label`, `list_drafts`, `list_labels` — but no way to download message attachments. When `get_thread` is called with `messageFormat: FULL_CONTENT`, attachment content is returned base64-encoded inline. For any thread containing a multi-MB PDF, the response exceeds the LLM's 25,000-token read limit and cannot be processed.

Use Case

Institutional document workflows — real estate underwriting, legal review, contract abstraction, deal diligence — require extracting fee schedules, contract terms, and cost data from PDFs attached to emails (architect engagement letters, GC proposals, lender term sheets, OA executions). Today an LLM agent can confirm an attachment exists and read the message body, but cannot retrieve the PDF content for analysis.

This forces the user to manually save attachments to a separate file system the agent has access to — defeating the point of the Gmail integration.

Proposed Tool

`mcp__gmail__get_attachment`

Required parameters:

• `messageId`: string — the message containing the attachment
• `attachmentId`: string — from the `get_thread` response's `attachmentIds` array

Optional parameters:

• `format`: `"base64"` | `"binary"` (default: `base64`)
• `saveToPath`: string — if provided, write binary content to this path on the host filesystem and return the path; otherwise return content inline

Returns:
```
{
filename: string,
mimeType: string,
size: number,
content: string | null, // base64 if format=base64
savedPath: string | null // populated if saveToPath was used
}
```

Why `saveToPath` Matters

Inline base64 of a 388 MB SD package — or even a 700 KB OA PDF — will blow through any reasonable LLM context window. Writing to the agent's accessible filesystem (e.g., the connected Cowork workspace folder) and returning just the path lets the agent then use `Read`/`Grep`/PDF-extraction tools on the file directly. This is the pattern that makes attachment extraction actually usable for agents.

Underlying Gmail API Support

Already supported natively via `users.messages.attachments.get`. Implementation should be a thin pass-through.

Related Quality-of-Life Additions

1. `messageFormat: FULL_CONTENT_NO_ATTACHMENTS` option on `get_thread` — returns full message bodies and attachment metadata (filenames, mimeTypes, sizes, attachmentIds) but excludes the base64 content. Lets agents survey a thread without blowing the token budget, then decide which attachments to pull.

2. Attachment metadata in `search_threads` results — currently doesn't expose attachment names, so agents must call `get_thread` just to discover what's attached. Surface `attachments: [{filename, mimeType, sizeBytes}]` in the thread summary.

3. `filename:` search operator examples in the tool description — Gmail supports it but agents often forget the exact syntax.

Priority

Single biggest blocker to using Gmail-as-data-source for any agent doing document-grounded analysis. Every other major email/document integration (Microsoft Graph, Slack file API, Box, Dropbox) supports attachment retrieval as a first-class operation.

Concrete Repro

• Agent task: "Confirm the A&E fee in the Nelson Worldwide engagement letter and update the underwriting model."
• Agent found: Executed LOA in Gmail thread, sender confirmed, attachment present.
• Blocked at: Cannot read the PDF content. Forced to ask user to manually share the file.