Skip to main content
Glama

wait_for_message

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.

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, 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": "wait_for_message"
  }
}

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.1/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It does disclose that the wait may end early for a held-message notice or cancellation, which is useful behavioral context, but it does not state that the operation is read-only/non-destructive or describe the returned message batch structure. Much of the text describes snapshot-review protocol rather than this tool's behavior.

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?

Only the first sentence is front-loaded and relevant. The rest is a long run-on mixing review_request_id replies, sha256 verification, check_snapshot instructions, and review-set rules into a tool that merely waits for messages, which makes the definition harder to scan and apply.

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 simple two-parameter wait tool with no output schema, the description is simultaneously bloated with unrelated protocol and incomplete about the wait itself: it does not clarify what an ack should contain, what message shapes are returned, or how the hold/cancellation outcomes are represented. It says enough to identify the operation but not enough to call it confidently.

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. The description mentions timeout_seconds in passing but adds no new semantics, and it does not explain the ack parameter even though that is the more subtle of the two.

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 a specific verb and resource: wait for inbox messages up to timeout_seconds and return them. It distinguishes the tool from a plain inbox read via the conditional 'only when delivery instructions call for waiting,' though it never names read_inbox as the alternative.

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 gives a restrictive usage condition ('only when ... delivery instructions call for waiting'), which is helpful, but it does not explicitly compare against sibling tools like read_inbox or explain when a shorter/longer timeout is appropriate. The remainder of the description is unrelated workflow guidance, not usage guidance for this tool.

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