Skip to main content
Glama
EminUZUN

hoptell

by EminUZUN
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

wait_for_message

Waits for inbox messages up to a timeout and returns them, enabling agents to pause until peer messages arrive or a held-message notice/cancellation ends the wait.

Instructions

Wait for inbox messages up to timeout_seconds and return them. Use this only when this session's delivery instructions call for waiting. The wait can also end for a held-message notice or cancellation. 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, 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.

Input Schema

NameRequiredDescriptionDefault
ackNoOptional. The receipt returned with a message batch you have finished handling.
timeout_secondsNoMaximum server wait in seconds (default 300, maximum 1500); the client may time out sooner.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.3.1
    • addedInput schema / properties / ack
      Added value: +{
+  "description": "Optional. The receipt returned with a message batch you have finished handling.",
+  "type": "string"
+}
    • changedInput schema / properties / timeout_seconds / description
      Previous value: -"Max wait in seconds, default 300, max 1500"New value: +"Maximum server wait in seconds (default 300, maximum 1500); the client may time out sooner."
  2. First observedv0.1.1

TDQS

B3.2/5.0
Behavior3/5

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

With no annotations, the description carries the burden. It usefully discloses that the wait may end early for a held-message notice or cancellation, and that the client may time out sooner than the server. But it never explains what the `ack` parameter does behaviorally (does it consume messages?), nor whether this is read-only; instead it spends most words on post-receipt review protocol.

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 first two sentences are well front-loaded, but the remaining text is a dense, run-on block of review-protocol instructions (handling snapshots, sha256 checks, hoptell commands) that buries the tool's actual behavior. Most of it does not serve an agent deciding whether to call wait_for_message.

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?

Lacking an output schema and annotations, the description tries to fill the gap by explaining what to do with received content, which is relevant. But it does so with references to fields not in the schema and omits key behavior (ack semantics, consumption of messages), so the agent still lacks a coherent picture.

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 coverage is 100%, so both parameters are already documented and the baseline is 3. The description adds nothing beyond the schema for `ack` or `timeout_seconds`, and instead introduces field names (review_request_id, based_on, reply_to) that do not exist in the input 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 opening sentence states the specific verb and resource ('Wait for inbox messages ... and return them'), and the 'wait' framing distinguishes it from read_inbox. However, the following ~90% of text is about review protocol rather than the tool's purpose, diluting clarity.

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?

It offers a conditional ('Use this only when this session's delivery instructions call for waiting'), which is a when-to-use hint. But it never names the sibling alternative (e.g., read_inbox for immediate retrieval) or explains what 'delivery instructions' means, leaving the choice 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