mailbox-mcp

list_agent_inbox_scans

Read-onlyIdempotent

Deprecated: use get_inbound_pages. Still served unchanged during the alias window. List/search completed facility-captured scan jobs for this assigned member sample through /v1/agent-inbox/:id/scans.

Instructions

Deprecated: use get_inbound_pages. Still served unchanged during the alias window. List/search completed facility-captured scan jobs for this assigned member sample through /v1/agent-inbox/:id/scans. Sandbox agent key only, with both read scopes even without q. q is literal AND search of saved capture identifiers and authorized captured-page OCR, normalized NFKC/lowercase, max 200 characters and 12 terms, before pagination. Returns request_id, bundle_id, page count and OCR status, not text. Follow pagination.has_more using offset plus scans.length up to offset 10000; report incomplete history at the cap. A completed scan may have null, queued, processing, ready, needs_review or failed OCR; completion is not extraction success. Separate from seeded sample /context; after indexed rollout, item search also includes these captures. No provider, retry, acknowledgment or receipt is triggered. 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
`q`	No	Literal AND search: every term (max 12, 200 characters, NFKC-normalized and lowercased) must appear in the reference, the sender line or the OCR text of a readable page. Not fuzzy; punctuation is literal.
`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.6/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: discloses pagination mechanics and the 10000 offset cap, the 'current view, not a snapshot' caveat, that completion is not extraction success, the OCR status enum meaning, that no provider/retry/acknowledgment is triggered, and the required scopes and key restrictions. This is rich behavioral context an agent cannot infer from annotations.

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-loads the critical deprecation notice first and every clause carries information, but the remaining single dense block packs auth, pagination, OCR and rollout caveats into run-on sentences, raising reading cost.

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?

For a deprecated, auth-heavy, paginated list tool it covers the scopes, key constraints, pagination limits, OCR semantics, and rollout caveats. An output schema exists so return values need no further explanation, and the description is complete without it.

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

Parameters3/5

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

Schema description coverage is 100%, so q, limit, offset and item_id are already fully documented. The description restates q's literal AND/NFKC behavior and the offset cap, adding little beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ('List/search completed facility-captured scan jobs') scoped to 'this assigned member sample' via an explicit endpoint path. It also names its replacement (get_inbound_pages) and distinguishes itself from the seeded sample /context, so an agent can separate it from siblings without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use routing: 'Deprecated: use get_inbound_pages' plus the alias-window caveat, and how it differs from the seeded sample /context endpoint. It also states the precondition (sandbox agent key only, required scopes) that selects or excludes this tool.

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

Deploy Server