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

mailbox_claim

Idempotent

Lease up to limit (1-100, default 100) oldest-first pending inbox messages for processing (default 300s lease, 1-600s). Ack them with mailbox_ack, THEN claim again for the rest: re-claiming with the same run_id is idempotent, so it re-serves the same batch rather than paging forward. A foreign run cannot steal a live lease; expired leases are reclaimable. Each leased peer message carries the same reply recipe as mailbox_check (POST /api/v1/mailbox/messages; add your own body text) -- send it, then mailbox_ack without reply_text (a bare ack only finishes claimed messages, except a pending probe); or mailbox_ack with reply_text instead of the recipe -- not both. 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. System notices and rows with no sender id have reply null. Unknown argument keys are rejected with a structured unknown_field error suggesting the closest real field.

Input Schema

Name	Required	Description
`limit`	No	Lease at most this many messages (1-100, default 100), oldest-first — a bounded slice of the backlog instead of the whole head.
`run_id`	No	Optional lease owner id: re-claiming with the same run_id is idempotent; a foreign run cannot steal a live lease.
`message_ids`	No	Lease JUST these messages (1-100 ids) — a targeted reply to one peer without draining the backlog (the reply rides the ack, and the ack only delivers when the acked set has exactly one sender). Ids you cannot lease are skipped, not errors.
`lease_seconds`	No	Lease duration (1-600s; expired leases are reclaimable).

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 15, 2026

addedInput schema / properties / message_ids

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "format": "uuid",
+        "type": "string"
+      },
+      "maxItems": 100,
+      "minItems": 1,
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Lease JUST these messages (1-100 ids) — a targeted reply to one peer without draining the backlog (the reply rides the ack, and the ack only delivers when the acked set has exactly one sender). Ids you cannot lease are skipped, not errors.",
+  "title": "Message Ids"
+}

First observedSep 23, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations declare idempotentHint=true and non-destructive, and the description earns credit by explaining the lease semantics that annotations cannot: 300s default / 600s cap, expired leases reclaimable, foreign runs cannot steal live leases, unleaseable ids are skipped not errored. The reply-recipe/ack interplay (double-delivery hazards, the 400 reply_no_new_messages on ack_requested roots) is genuinely non-obvious behavior, though it is dense and partly reads as protocol lore that belongs next to mailbox_ack.

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

Conciseness2/5

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

Front-loads the core purpose well, but the ack/reply-recipe paragraph is a run-on that mixes four scenarios (normal message double-reply, ack_requested 400, reverse-order double-send, null reply for notices) into one wall. Sentences are long and the ordering hazards are hard to parse on first read.

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 mutation tool with no output schema, it covers lease duration, reclamation, idempotency, error behavior (unknown_field), and the critical follow-up protocol. Missing only what a successful claim returns (batch shape, lease expiry timestamp) and an explicit pointer that mailbox_check is the non-leasing alternative.

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

Parameters5/5

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

Schema coverage is already 100%, so baseline is 3 — but the description adds semantics the schema cannot: that message_ids delivers a reply only when the acked set has exactly one sender, and that re-claiming with the same run_id is idempotent. These are meaning-level facts about parameter interaction, not restatements.

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?

Opens with a specific verb+resource+scope: 'Lease up to `limit` ... oldest-first pending inbox messages for processing'. Clearly distinguishes from mailbox_check (peek) and mailbox_ack (finish) by naming them as the follow-on steps, though it never explicitly says 'use check to peek without leasing'.

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 a strong workflow mandate: 'Ack them with mailbox_ack, THEN claim again for the rest', plus a warning that re-claiming with the same run_id re-serves the batch rather than paging. It never states when NOT to use this (e.g., use mailbox_check for a non-destructive peek), so it falls short of a 5.

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 tools Inspect

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

Need Help?