Skip to main content
Glama

Get inbox

get_inbox

Retrieve new team messages addressed to your agent or role, tracking a read cursor so later calls return only newer mail; use an explicit event ID for read-only history checks.

Instructions

Return messages addressed to the caller (by agent_id or matching role) within the caller team. Default behaviour (since_event_id omitted): the daemon reads the caller's server-side cursor (agents.last_processed_event_id), returns mail past it, and ADVANCES the cursor to the highest returned event_id in the same transaction. Subsequent default calls return only newer mail. Pagination via limit advances the cursor only to the last RETURNED event_id; the next default call resumes from there. Explicit since_event_id (any number, including 0) is read-only inspection: the daemon uses the supplied value as the lower bound and does NOT advance the stored cursor — useful for re-reading history or debugging without disturbing live read position. REPLY GUIDANCE: every returned message carries from_agent_id, from_name, and from_device for the sender. When replying via send_message, construct to_agent_name as from_name + ":" + from_device whenever from_device !== <your own device> — otherwise the daemon resolves the bare name on YOUR device, misses the cross-device sender, and returns unknown_recipient. Bare from_name is correct only when from_device === <your own device>. send_message_by_id({to_agent_id: from_agent_id, ...}) always works regardless of device and is the safe fallback when device is unknown. Retention: messages older than 30 days are deleted by the cleanup routine regardless of read state. Agents that go offline for more than 30 days forfeit any unread mail in that window.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_inbox"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNo
since_event_idNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior4/5

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

With no annotations supplied, the description carries the full burden and does most of it well: it discloses the non-obvious side effect that a default call advances the server-side cursor in the same transaction, that pagination advances only to the last returned event, and that explicit since_event_id is non-mutating. It even documents the concrete failure mode (`unknown_recipient`) caused by bare-name resolution on the wrong device, plus 30-day retention deleting mail regardless of read state. Only minor gaps remain, such as what happens on an empty inbox or the exact response envelope beyond the sender fields it names.

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?

It is front-loaded correctly: recipient scope, then default-vs-explicit cursor semantics, then the reply guidance, then retention. Almost every sentence carries operational information an agent would otherwise get wrong. It is dense and long, and the multi-clause cursor explanation could be tightened, but nothing is filler.

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?

For a two-parameter tool with no annotations and no output schema, an agent needs to know the recipient scope, the cursor side effect, pagination resume behavior, how to reply to a cross-device sender, and message lifetime. All five are covered explicitly, including the failure string it would otherwise encounter blindly.

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 description coverage is 0%, so the description must compensate, and it does: `since_event_id` is defined semantically (lower bound, read-only, 'any number, including 0' — clarifying an edge case the bare integer type would not) and its interaction with the stored cursor is spelled out. `limit` is given meaning beyond its type by explaining that pagination advances the cursor only to the last RETURNED event_id and that the next default call resumes from there.

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 opening sentence gives a specific verb and resource ('Return messages') plus the exact recipient scope: addressed to the caller by agent_id or matching role, within the caller team. That is enough to separate it from every write-side sibling such as send_message, broadcast, or broadcast_to_role without opening any 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?

The description explicitly splits two modes and says when each applies: omit `since_event_id` for normal consuming reads that advance the cursor, or pass it explicitly for 'read-only inspection ... useful for re-reading history or debugging without disturbing live read position.' It also routes reply handling to the correct sibling, preferring send_message with a composed device-qualified name and naming send_message_by_id as the safe fallback.

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