Skip to main content
Glama

read_inbox

Retrieve messages received from peers and optionally acknowledge a completed batch so agents can process peer handoffs and replies.

Instructions

Return messages received from peers. Listener command (listener delivery only): (shown once connected: call list_peers, then list tools again). Review a snapshot's supplied content; its file label is not a local path. Reply with review_request_id, based_on set to its sha256, and reply_to when available. Before using a local checkout, check the local file with check_snapshot (or run '/usr/bin/node' '/app/bin/hoptell.js' snapshot --check <received-sha256> <local-file>) and report match, mismatch or unable to check. On mismatch or failure, review the supplied content; local tests do not validate it. A review set (hoptell_review_set) lists files by file_id. Use its content only if hoptell's Review set check after the matching end marker says every file's content matches its sha256. The sender's user reviews and applies proposals; do not claim one was applied.

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": "read_inbox"
  }
}

Input Schema

NameRequiredDescriptionDefault
ackNoOptional. The receipt returned with a message batch you have finished handling.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.1
    • addedInput schema / properties / ack
      Added value: +{
      +  "description": "Optional. The receipt returned with a message batch you have finished handling.",
      +  "type": "string"
      +}
  2. First observedv0.1.1

TDQS

C2.4/5.0
Behavior2/5

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

With no annotations, the description must carry the full behavioral burden. It implies a read operation ('Return messages') but never explicitly states safety, side effects, or auth requirements. The 'listener delivery only' note and the warning about not claiming proposals were applied are useful but buried in unrelated context.

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?

The description is poorly structured and overly long, cramming multiple unrelated instructions (listener command, snapshot review, review sets) into a single block. The core purpose is front-loaded but quickly buried under tangential details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema, the description should clearly explain what it returns, how 'ack' works, and when to use it. Instead it spends most of its text on snapshot-review procedures, leaving the actual inbox-reading behavior under-specified.

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?

The schema fully documents the single optional 'ack' parameter, so the baseline is 3. The description does not mention 'ack' or add any meaning beyond the schema's own description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence 'Return messages received from peers' gives a clear verb and resource, but the rest of the description is a dense mix of unrelated workflow instructions (snapshot review, listener command, review sets) that obscure the core purpose. It does not distinguish read_inbox from sibling tools like wait_for_message or ack_messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage guidance is limited to a specific snapshot-review workflow ('Review a snapshot's supplied content...'), with no general statement of when to call read_inbox versus alternatives such as wait_for_message or ack_messages. The mention of check_snapshot is a step within that workflow, not a routing alternative.

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