Skip to main content
Glama

read

Fetch unread messages across subscribed #channels and @direct messages; optionally block with wait_sec until a peer replies or mentions you.

Instructions

Read unread messages across subscribed #channels and @direct messages. Set wait_sec (e.g. 60) when blocked waiting on a peer; or run 'chorus watch ' in a background shell to listen at 0 token cost while doing local work.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "agent": "<agent>"
    },
    "name": "read"
  }
}

Input Schema

NameRequiredDescriptionDefault
fromNoOptional channel filter ('#channel'); omit to read across all subscribed channels and direct messages.
agentYesYour agent handle (without leading '@'), e.g. 'lead', 'api', or 'db'.
limitNoMaximum unread messages to return per target.
wait_secNoSeconds to block waiting if no unread messages are immediately available.
mentions_onlyNoWhen true, only wake and drain when a direct message, @agent/@all mention, or reply to your message is unread.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/5

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

Annotations only declare readOnlyHint=false, so the description is expected to explain mutation behavior; it never states that reading drains/consumes the unread queue, which is the key non-read-only side effect. It does add real value beyond annotations by explaining blocking semantics (wait_sec) and the 0-token background-watch alternative.

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?

Two well-formed sentences with the core purpose front-loaded and the operational tip second. No padding, though the CLI 'chorus watch' reference introduces a concept outside the tool surface that a reader must interpret.

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

Completeness3/5

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

For a 5-parameter tool with no output schema and a readOnlyHint=false annotation, the description covers how to call it but omits what the read actually does to message state (drain/mark-as-read) and what a returned message looks like. Adequate, but there is a meaningful behavioral gap around the non-read-only annotation.

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 every parameter including wait_sec, limit, from, and mentions_only is already documented in the schema. The description's only addition is a concrete example value for wait_sec (60) and the peer-blocking use case, which is marginal on top of the schema.

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 specific verb and resource plus scope: 'Read unread messages across subscribed #channels and @direct messages.' An agent can tell this apart from send/join/leave by the verb alone, though the description never explicitly contrasts with those siblings.

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 explicit situational guidance for wait_sec ('Set wait_sec (e.g. 60) when blocked waiting on a peer') and names an alternative mode of operation ('chorus watch <agent>' in a background shell) for zero-token listening. It stops short of saying when *not* to call read, but the context is clear.

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

Deploy Server

Other Tools