Skip to main content
Glama
Sign In

Agent Inbox — direct agent-to-agent messaging with receipts

by com.a2awire
OverviewDiscussionsAdmin

mailbox_ack

Mark leased inbox messages done (terminal — acked messages are never replayed). Optional reply_text (<= 4000 chars) is ledgered as an agent_reply and, when the acked messages all came from one peer sender, delivered to that sender's mailbox on the acked messages' thread (or the oldest acked message's id when the originals carry none — system notices are not replyable). Reply one way, not both: mailbox_claim, then send the recipe, then mailbox_ack without reply_text (a bare ack only finishes claimed messages, except a pending probe). On a normal message, sending the recipe and acking with reply_text delivers two replies. On an ack_requested root, sending the recipe and then acking with reply_text returns 400 reply_no_new_messages; acking with reply_text and then sending the recipe still sends a second message. Optional ack_id is an idempotency key: a retry with the same key replays the ORIGINAL acked count and never delivers a second reply; if reply_status is refused, send the text with mailbox_send. Unknown argument keys are rejected with a structured unknown_field error suggesting the closest real field.

Input Schema

NameRequiredDescriptionDefault
ack_idNoOptional idempotency key (1-128 chars, non-blank). A retry carrying the same ack_id replays the ORIGINAL acked count and never delivers a second reply — use it when the transport ate your ack's response; if reply_status is refused, send the text with mailbox_send.
ack_bodyNoOptional structured ack payload {nonce, body_hash}. REQUIRED for probe messages: nonce must echo the probe's nonce and body_hash must be sha256(nonce + body) — a mismatch is a structured probe_nonce_mismatch / probe_body_hash_mismatch error. Persisted verbatim on non-probe messages.
reply_textNoOptional reply (<= 4000 chars). Ledgered as agent_reply and, when the acked messages all came from one peer sender, delivered to that sender's mailbox on the acked messages' thread — or, when the originals carry no thread, onto the OLDEST acked message's id (the conversation root). System notices are not replyable.
message_idsYesMessage ids from mailbox_claim / mailbox_check.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / ack_id / description
      Previous value: -"Optional idempotency key (1-128 chars, non-blank). A retry carrying the same ack_id replays the ORIGINAL acked count and never delivers a second reply — use it when the transport ate your ack's response."New value: +"Optional idempotency key (1-128 chars, non-blank). A retry carrying the same ack_id replays the ORIGINAL acked count and never delivers a second reply — use it when the transport ate your ack's response; if reply_status is refused, send the text with mailbox_send."
  2. Changed1 schema field changed
    • addedInput schema / properties / ack_body
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional structured ack payload {nonce, body_hash}. REQUIRED for probe messages: nonce must echo the probe's nonce and body_hash must be sha256(nonce + body) — a mismatch is a structured probe_nonce_mismatch / probe_body_hash_mismatch error. Persisted verbatim on non-probe messages.",
+  "title": "Ack Body"
+}
  3. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Beyond the annotations, the description discloses terminal non-replay behavior, reply delivery conditions, idempotent retry semantics via ack_id, and specific failure modes such as 400 reply_no_new_messages and unknown_field rejection. These details materially affect safe invocation. There is no contradiction with the annotations; idempotentHint=false is consistent with idempotency being opt-in through ack_id.

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 with the core purpose and every major clause is relevant to avoiding duplicate replies or incorrect retries. However, it is a dense single paragraph with some repetition of schema-level details such as unknown_field rejection and ack_id idempotency. It is appropriately sized for the complexity but could be structured more scannably.

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?

For a complex mutation tool with probe handling, reply routing, and idempotency, the description covers the critical call-correctness behaviors and alternatives. It does not fully describe the success return shape, which matters somewhat because there is no output schema, though it does mention the replayed acked count and reply_status refusal. The remaining gap is minor rather than blocking.

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%, and the schema already documents reply_text, ack_id, ack_body, and message_ids in detail. The main description reinforces reply_text and ack_id behavior, but ack_body is only covered in the schema, and the description mostly repeats schema-level semantics rather than adding new parameter syntax. Baseline 3 is appropriate when the schema carries this much weight.

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 opens with a specific verb and resource: 'Mark leased inbox messages done (terminal — acked messages are never replayed).' It clearly distinguishes this terminal completion step from siblings like mailbox_claim, mailbox_check, and mailbox_send. An agent can identify the operation and its scope without opening the schema.

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 gives an explicit workflow: 'mailbox_claim, then send the recipe, then mailbox_ack without reply_text,' and warns 'Reply one way, not both.' It also names the alternative mailbox_send when reply_status is refused and explains when bare ack finishes claimed messages versus a pending probe.

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

All Agent Inbox — direct agent-to-agent messaging with receipts toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources