MCP Agent Mail

fetch_inbox

Retrieve recent agent messages without altering read or acknowledgment state, with filters for unread, urgent, topic, and timestamp to support safe inbox polling.

Instructions

Retrieve recent messages for an agent without mutating read/ack state.

Filters

urgent_only: only messages with importance in {high, urgent}
since_ts: ISO-8601 timestamp string; messages strictly newer than this are returned
limit: max number of messages (default 20)
include_bodies: include full Markdown bodies in the payloads
topic: filter to messages with this topic tag
unread_only: when True, restrict to messages this recipient has not yet explicitly marked read via mark_message_read or acknowledge_message. Per-recipient: a message read by Agent A is still unread for Agent B. A bare fetch_inbox call does NOT mark messages read; this filter inspects existing read state without mutating it.

Usage patterns

Poll after each editing step in an agent loop to pick up coordination messages.
Use since_ts with the timestamp from your last poll for efficient incremental fetches.
Use unread_only=True from polling agents (Claude Code, Codex, etc.) to skip messages the agent has already acknowledged — cuts token-burn at scale by avoiding re-running prompt context against already-handled mail.
Combine with acknowledge_message if ack_required is true.

Returns

list[dict] Each message includes: { id, subject, from, created_ts, importance, ack_required, kind, read_at, [body_md] } read_at is this recipient's read timestamp (null while unread), so the default view — which includes already-read mail — stays distinguishable.

Example

{"jsonrpc":"2.0","id":"7","method":"tools/call","params":{"name":"fetch_inbox","arguments":{
  "project_key":"/abs/path/backend","agent_name":"BlueLake","since_ts":"2025-10-23T00:00:00+00:00"
}}}

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No
`topic`	No
`format`	No
`since_ts`	No
`agent_name`	Yes
`project_key`	Yes
`unread_only`	No
`urgent_only`	No
`include_bodies`	No
`registration_token`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.4Sep 30, 2026

TDQS

A4.3/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 on the core behavioral trait: it repeatedly states that fetching does NOT mutate read/ack state, and explains per-recipient read semantics. It omits auth/permission requirements and rate-limit behavior, and the registration_token parameter is never mentioned, which is the remaining gap for a no-annotation tool.

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?

Purpose is front-loaded, then clearly sectioned into Filters / Usage patterns / Returns / Example. It is long, but the length is justified by ten parameters and no schema descriptions; the Returns block is somewhat redundant given an output schema exists.

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?

Covers purpose, filtering semantics, non-mutation guarantees, and a working call example, which is strong for a no-annotation tool. The main omissions are the format and registration_token parameters and any authentication context, which an agent may need to invoke correctly.

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 0%, so the description must compensate. It richly documents six of ten parameters (urgent_only's importance enum, since_ts strictness, limit default, include_bodies, topic, unread_only's per-recipient semantics), but leaves format, registration_token, and the meaning of project_key/agent_name (beyond their appearance in the example) undocumented, so the compensation is partial.

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 ('Retrieve recent messages for an agent') plus a distinguishing scope qualifier ('without mutating read/ack state'), which cleanly separates it from siblings like search_messages, fetch_topic, and fetch_summary.

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?

The 'Usage patterns' section gives explicit when-to-use guidance: poll after each editing step, use since_ts for incremental fetches, use unread_only to cut token burn, and combine with acknowledge_message when ack_required. Alternatives and conditions are named rather than left to inference.

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