mailbox-mcp

get_agent_inbox_sources

Read-onlyIdempotent

Deprecated: use get_inbound_item. Still served unchanged during the alias window. Primary OCR read after list_agent_inbox: GET /v1/agent-inbox/:id/sources.

Instructions

Deprecated: use get_inbound_item. Still served unchanged during the alias window. Primary OCR read after list_agent_inbox: GET /v1/agent-inbox/:id/sources. Requires assigned-inbox and indexed-source reads enabled for the account, plus agent.inbox.read + agent.read. After indexed-source rollout, read selected item_id pages: exterior, requested contents and original sample_letter. Group by item, then request_id/bundle_id; cite page_id, preserve source_sha256 and review flags. Derive sender/address only from returned evidence. Both read scopes required; no acknowledgment version or extraction is created. Field meanings and sort order are in outputSchema. Use narrow queries/date windows and fetch selected items, not every mailbox on every poll. Pages: limit 1–50 (default 25), offset 0–10000. Item lists use next_offset; sources/scans use has_more and offset + returned length. Stop before exceeding 10000; narrow item searches, or report incomplete source/scan history. Pagination is a current view, not a snapshot or durable queue. Bound concurrency and retries; honor Retry-After when present, back off with jitter on 429/transient failures, and stop on access errors or disabled rollout. Do not share private results across agents/environments. No ETag, change cursor or unbounded export is promised. No receipt, provider call, signed image URL, email or charge. Managed-PMB custody and forwarded email remain separate and excluded. Required scopes: agent.inbox.read, agent.read. Agent-scoped bearer key required; member/facility keys cannot impersonate an agent. Rollout switches, current member approval, assignment, credential environment and SQL authorization are shared with REST. Never substitute another key or mail API after denial.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Page size, 1–50 (default 25).
`offset`	No	Items to skip, 0–10000 (default 0). Advance by the number returned while more remain; results are a current view, not a snapshot.
`item_id`	Yes	Inbound item id (UUID) from a list or search result.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.0.3Oct 12, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Goes well beyond the annotations: required scopes (agent.inbox.read, agent.read), agent-scoped key requirement, no side effects ('no acknowledgment version or extraction is created'), pagination model (next_offset vs has_more), 429/Retry-After backoff guidance, no ETag/change cursor promise, and denial handling. This is exactly the extra behavioral context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical deprecation notice is correctly front-loaded, but the definition then runs to roughly 250 words of auth, custody, retry, security and rollout advice for a 3-parameter read tool. Much of this belongs in server documentation, and the density of operational warnings buries the actual purpose.

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?

Complete: an output schema exists and the description appropriately defers ('Field meanings and sort order are in outputSchema'), while still covering auth requirements, pagination limits, error/backoff behavior, and scope of returned evidence. Nothing needed to call it correctly is missing.

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 100%, so the baseline is 3, but the description adds real meaning: it explains the two pagination regimes (item lists use next_offset; sources/scans use has_more with offset + returned length) and the 10000 stop-and-report rule, which the schema only partially conveys.

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 concrete verb+resource ('Primary OCR read after list_agent_inbox: GET /v1/agent-inbox/:id/sources') and flags itself as deprecated in favor of get_inbound_item. It distinguishes itself from siblings clearly, though the redirect target is slightly ambiguous given that a non-deprecated get_inbound_item_sources also exists.

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?

Explicitly says 'Deprecated: use get_inbound_item. Still served unchanged during the alias window,' naming the alternative and the migration condition. It also advises narrow queries/date windows and fetching selected items rather than every mailbox, though it never states a positive when-to-use case beyond legacy migration.

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

Deploy Server