fmsg-mcp

List inbox

list_messages

Read-onlyIdempotent

Retrieves messages received by an address, newest first, with sender, topic, read state, flags, size, attachments, and previews; supports paging and unread or reaction filtering.

Instructions

List messages received by this address, newest first. Each item carries the id, sender, recipients, topic, time, read state, flags, size, attachment names and types, and a short preview. Reaction messages are hidden unless include_reactions is true, and hidden reactions never count as unread; listed reactions have their own read state (mark_read accepts them) and carry the emoji in reaction. Topics are set only on a thread's first message; get_thread reports a reply's thread_topic. Use get_message for a full body and get_thread for the conversation around a message.

Input Schema

Name	Required	Description
`limit`	No	page size (host maximum 100)
`offset`	No	number of newest messages to skip
`unread_only`	No	keep only unread messages from the fetched page (reactions only with include_reactions)
`include_reactions`	No	also list reaction messages (normally hidden)

Output Schema

Name	Required	Description
`count`	Yes
`offset`	Yes
`messages`	Yes
`next_offset`	Yes	offset for the next page, or null when this page was short
`untrusted_content_notice`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedv1.1.0Oct 15, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / unread_only / description

Previous value: -"keep only unread messages from the fetched page"New value: +"keep only unread messages from the fetched page (reactions only with include_reactions)"

changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +{}
```
changedOutput schema / properties / messages / items / additionalProperties
```
Previous value: -falseNew value: +{}
```
addedOutput schema / properties / messages / items / properties / attachments / description
```
Added value: +"sorted by filename, the same order in every tool"
```
changedOutput schema / properties / messages / items / properties / attachments / items / additionalProperties
```
Previous value: -falseNew value: +{}
```

addedOutput schema / properties / messages / items / properties / attachments / items / properties / type

Added value: +{
+  "description": "media type; inferred from the filename when the host records none",
+  "type": "string"
+}

addedOutput schema / properties / messages / items / properties / compressed

Added value: +{
+  "description": "true when the body was sent deflate-compressed on the wire (see size)",
+  "type": "boolean"
+}

addedOutput schema / properties / messages / items / properties / preview / description
```
Added value: +"start of the body; may be shorter than the full body"
```

addedOutput schema / properties / messages / items / properties / reaction

Added value: +{
+  "description": "the emoji when this message is itself a reaction (\"\" clears one); null otherwise",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / properties / messages / items / properties / reactions / items / additionalProperties
```
Previous value: -falseNew value: +{}
```

addedOutput schema / properties / messages / items / properties / size / description

Added value: +"body size in bytes as stored by your host: for a message you received with compressed true, the compressed wire length; your own sent messages store the uncompressed length. body_bytes, where given, is the decoded length"

addedOutput schema / properties / untrusted_content_notice
```
Added value: +{
+  "type": "string"
+}
```

First observedv0.1.3Sep 5, 2026

TDQS

A4.8/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 ordering, return fields, reaction hiding by default, how hidden reactions affect unread counts, reaction read-state behavior, and thread-topic nuances. These are substantive behavioral details an agent would not get from the annotations alone.

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?

The description is front-loaded and dense with useful guidance. The enumeration of output fields is somewhat unnecessary because an output schema exists, but the overall structure remains efficient and readable.

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?

Given the presence of an output schema and safety annotations, the description supplies the remaining context an agent needs: scope, ordering, reaction behavior, thread-topic rules, and when to use alternative tools. Nothing critical is missing for correct invocation.

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 parameters are already documented, but the description adds meaningful semantics for include_reactions: reactions are hidden unless true, hidden reactions never count as unread, and listed reactions have their own read state. It also clarifies the unread_only interplay with reactions, though limit and offset are left to the schema.

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: list messages received by this address, ordered newest first. It clearly distinguishes inbox listing from get_message, get_thread, and implicitly list_sent by specifying received messages.

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?

It explicitly directs the agent to get_message for a full body and get_thread for the conversation around a message, while making clear this tool lists received messages. The received-by-this-address scope also distinguishes it from list_sent without ambiguity.

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

Deploy Server