Skip to main content
Glama

channel_wait

Waits for new messages from a specified peer, replays missed messages first, then listens over WebSocket until timeout, returning message bodies or a timeout status without polling the model.

Instructions

等待指定对端的新消息:先补读,随后以 WebSocket 等待,不轮询模型。

纯读、不自动 ACK。返回正文后,等待此工具的当前回合可继续;不能唤醒已经结束 的 Desktop 回合。超时不自动重开等待。取消或连接故障会结束本次订阅。 调用方应让 MCP 请求超时大于 timeout_seconds + 4 * io_timeout_seconds + 5 秒。 客户端若提前超时,须发送 MCP cancel 或关闭连接;仅本地超时服务端无法感知。

返回 status=messages 或 timeout,附正文列表、has_more、next_cursor 与 delivery_source(replay=初始补读,event=WS 事件后补读,timeout_read=到期 后的末次补读,可为空)。游标失效直接报错,不静默跳页。

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": {
      "channel": "<channel>",
      "reader": "<reader>",
      "sender": "<sender>"
    },
    "name": "channel_wait"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNo最多返回的消息数,范围 1-200,默认 50。
sinceNo首次调用的 ISO 8601 时间下界;与 cursor 至少传一个,续读使用 cursor。
cursorNo上次实际处理页的 next_cursor;按数据库插入序续读,不用时间戳替代。
readerYes收件角色标识,如 leader-codex,不是 session_id。
senderYes对端角色标识,如 leader-cc;不能与 reader 相同。
channelYes专线频道名,如 team:aiteam-os-bridge。
project_idNo项目 id;留空按既有 cwd 规则解析,解析不到则拒绝。
timeout_secondsNo等待新消息的秒数,范围 (0, 7200],默认 45;不含连接与补读开销。 空闲长挂前确认客户端工具超时足够(Codex 为 tool_timeout_sec)。
io_timeout_secondsNo连接、订阅确认和单次 HTTP 读取各自的秒数预算,范围 (0, 60],默认 10。

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.17.1
    • changedInput schema / properties / timeout_seconds / description
      Previous value: -"等待新消息的秒数,范围 (0, 300],默认 45;不含连接与补读开销。"New value: +"等待新消息的秒数,范围 (0, 7200],默认 45;不含连接与补读开销。\n空闲长挂前确认客户端工具超时足够(Codex 为 tool_timeout_sec)。"
  2. Addedv1.12.3

TDQS

A4/5.0
Behavior5/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 so: pure read, no automatic ACK, does not wake a finished Desktop turn, timeout does not auto-reopen the wait, and cancel or connection failure terminates the subscription. It also states that an invalid cursor raises an error rather than silently skipping pages, which is exactly the failure mode an agent needs to know before retrying.

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 purpose and the catch-up-then-wait mechanism are front-loaded in the first line, with behavioral caveats and the timeout formula after. It is longer than most definitions but nearly every clause carries operational weight; the delivery_source and return-field enumeration is somewhat redundant given the output schema.

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 9-parameter blocking tool with no annotations, the description covers the hard parts: client-side timeout arithmetic, cancellation semantics, and cursor failure behavior; return values are already covered by the output schema. Minor gaps remain, such as whether concurrent waits on the same channel are safe and whether ordering across replay and events is guaranteed.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning the schema does not: the timeout formula that couples timeout_seconds and io_timeout_seconds, and the rule that the cursor comes from the last actually-processed page's next_cursor and cannot be replaced by a timestamp. It says nothing extra about reader/sender/channel beyond 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?

The description states a specific verb and resource ('等待指定对端的新消息') and discloses the mechanism ('先补读,随后以 WebSocket 等待,不轮询模型'), which implicitly separates it from a plain non-blocking read. It never names a sibling tool (e.g., channel_read or channel_unread), so the agent must infer the boundary itself, which keeps it short of a 5.

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

Usage Guidelines3/5

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

Usage guidance is operational rather than selective: it tells the caller to set the MCP request timeout above 'timeout_seconds + 4 * io_timeout_seconds + 5' and to send an MCP cancel or close the connection on early client timeout. It also warns that an ended Desktop turn cannot be woken. However, it never says when to prefer this over channel_read or channel_unread, so the choice between blocking wait and a plain read is left to inference.

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