mailbox.bot

search_inbound_items

Read-onlyIdempotent

List and search inbound mail through GET /v1/inbound-items, the same list and search the dashboard shows: newest first, with public status, kind (letter | package), the sender line as read from the envelope, the envelope page and any open action. q is a literal AND search (max 12 terms, 200 characters) over the reference, the sender and the OCR text of every readable page, envelope or contents; status, kind, received_after and received_before (intake time) narrow it. Sandbox keys (sk_agent_test_) see the account's sample letter from Mojave Land Partners: start with q: "Mojave"; an empty result carries a notice explaining why. Use item.id with the other tools. Key scope: inbound.item.read (agent.inbox.read also works). Member keys read their own live items; agent keys read items bound or assigned to them, in their key's environment. Proposals are agent-only and always wait for the owner: they never charge credits, buy postage, open, forward or discard anything by themselves. Forward destinations and discard proposals are checked against the agent's structured inbound policy. Image URLs are never issued to agents. Stop on denial; never switch keys or mail APIs to bypass it.

Input 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.
`kind`	No	letter or package.
`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.
`status`	No	Only items in this public status.
`received_after`	No	Inclusive intake time (ISO 8601 with offset): when the facility logged the item, never a printed date.
`received_before`	No	Exclusive intake time (ISO 8601 with offset); must be after received_after.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 29, 2026

addedOutput schema / properties / result / properties / notice

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "message": {
+      "type": "string"
+    },
+    "reason": {
+      "const": "sample_unavailable",
+      "type": "string"
+    }
+  },
+  "required": [
+    "reason",
+    "message"
+  ],
+  "type": "object"
+}

Changed7 schema fields changedSep 28, 2026

addedInput schema / properties / kind / description
```
Added value: +"letter or package."
```
addedInput schema / properties / limit / description
```
Added value: +"Page size, 1–50 (default 25)."
```

addedInput schema / properties / offset / description

Added value: +"Items to skip, 0–10000 (default 0). Advance by the number returned while more remain; results are a current view, not a snapshot."

addedInput schema / properties / q / description

Added value: +"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."

addedInput schema / properties / received_after / description

Added value: +"Inclusive intake time (ISO 8601 with offset): when the facility logged the item, never a printed date."

addedInput schema / properties / received_before / description

Added value: +"Exclusive intake time (ISO 8601 with offset); must be after received_after."

addedInput schema / properties / status / description
```
Added value: +"Only items in this public status."
```

AddedSep 24, 2026

TDQS

A4/5.0

Behavior5/5

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

Annotations already declare a safe, idempotent, non-destructive read, and the description still adds substantial behavior beyond them: key scope semantics (inbound.item.read / agent.inbox.read), member vs agent key visibility, environment scoping, the sandbox sample dataset, the explanatory notice on empty results, the guarantee that image URLs are never issued, and the rule that proposals never charge or act autonomously. This is well past the lower bar set by the annotations.

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

Conciseness3/5

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

It is front-loaded — the purpose and the q/filter behavior come first — but it is a dense multi-clause block that folds in unrelated policy about proposals, forwarding and discard checks against the agent's inbound policy, which belongs to the propose_* tools rather than a read/search tool. Several clauses earn their place; the policy tail does not.

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?

Given an output schema exists, the description need not explain return values, yet it still sketches them, and it covers auth scopes, sandbox behavior, denial handling and cross-tool id usage — ample for correct invocation. The remaining gap is sibling disambiguation against list_inbound_items/list_inbound_mail.

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 the baseline is 3. The description largely restates what the schema already documents (q as a literal AND search with term/character limits, status/kind/date filters narrowing the set), adding only the framing that received_after/received_before refer to intake time. It adds little semantics the schema does not already carry.

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 ('List and search inbound mail through GET /v1/inbound-items') and enumerates the returned fields (public status, kind, sender line, envelope page, open action), which is specific enough to act on. It does not, however, differentiate itself from near-identical siblings such as list_inbound_items or list_inbound_mail, so an agent cannot tell from the description alone which of these to pick.

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?

Gives clear operational context: use item.id with the other tools, sandbox keys should start with q: "Mojave", and 'Stop on denial; never switch keys or mail APIs to bypass it.' It explains how filters narrow results and when an empty result is expected. What it lacks is an explicit when-to-use-this-vs-alternatives statement naming the sibling list/search tools.

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

All mailbox.bot tools Inspect

Try in Browser

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.