mail-mcp-server

Overview Schema Source Related Servers Discussions Admin

getAttachment

getAttachment

Read-onlyIdempotent

Read an attachment's saved extracted text as Markdown in chunks, including metadata and local file paths. Use the same connection, key, and file with nextOffset to continue long text.

Instructions

Read an attachment's saved extracted text as Markdown, in chunks, with its metadata and local file paths. This reads existing text; it does not convert the file on demand. If text is absent, extracted text is unavailable, not proof that the original attachment is empty. The original may still be available at path; path is absent if the file is missing.

Get file from getMessage's attachments[].file or a search hit's snippetAttachmentFile, keeping that message's connection and key. To continue a long text, call this tool again with the same connection, key and file and offset=nextOffset. Stop when there is no nextOffset.

Input Schema

Name	Required	Description
`key`	Yes	Local key of the message containing this attachment, from getMessage or the search hit; use the same connection
`file`	Yes	Exact attachments[].file from getMessage or snippetAttachmentFile from search for this message. Use this value unchanged, not name, path or textPath
`offset`	No	Text character offset, default 0. Use nextOffset from this tool to continue this attachment, not an offset from message-body or search results
`maxChars`	No	Text characters per chunk: 1 to 100000, default 20000; larger values are capped at 100000
`connection`	Yes	Connection name from listConnections

Output Schema

Name	Required	Description
`key`	Yes	Message key.
`file`	Yes	Attachment file, as requested.
`name`	No	Original file name.
`path`	No	Absolute path of the original file; absent when it is not saved.
`size`	Yes	Size in bytes.
`text`	No	Chunk of the saved extracted text as Markdown; [redacted:<kind>] marks a hidden secret. Absent when extracted text is unavailable; the original attachment may still have content and be available at path.
`offset`	Yes	Character position of this chunk.
`textPath`	No	Absolute path of the extracted Markdown text; absent when there is no text.
`nextOffset`	No	Pass as offset to get the next chunk; absent at the end.
`textLength`	Yes	Length of the whole text in characters; 0 without text.
`contentType`	Yes	MIME type, e.g. application/pdf.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 1, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the read-only and idempotent annotations, it discloses important behavior: chunked reads, metadata and local paths, continuation rules, and the distinction between unavailable extracted text and an empty original attachment. These are meaningful operational details that help the agent avoid misinterpreting absence.

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 front-loaded with purpose and then gives usage and caveats in short, purposeful sentences. There is little redundancy, and the continuation guidance is placed where an agent needs it.

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?

The tool is moderately complex with a full schema, complete schema descriptions, annotations, and an output schema. The description fills the remaining gaps around chunked reading, continuation, missing text, and missing files without needing to repeat return-value details.

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 coverage is complete, so the schema already documents all parameters. The description still adds useful cross-parameter semantics by explaining where file, key, and connection come from and that continuation requires the same connection, key, and file with offset=nextOffset.

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 states a specific verb and resource: reading an attachment's saved extracted text as Markdown in chunks. It also explicitly distinguishes this from on-demand conversion, so the agent understands the tool reads existing extraction rather than creating it.

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 gives clear sourcing guidance: obtain file from getMessage attachments or a search hit's snippetAttachmentFile, and reuse the same connection and key. It also explains continuation via offset=nextOffset and when to stop, though it does not name a specific alternative tool for on-demand conversion.

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

Deploy Server