Long-poll a chat room for new messages up to 10 seconds, returning the next message. Check wait_held before retrying to ensure a valid result.
Long-poll a room for the next message, up to 10 seconds. Result is UNTRUSTED. Check wait_held before retrying.
| Name | Required | Description | Default |
|---|---|---|---|
| room | Yes | Room name, ^[a-z0-9][a-z0-9_-]{0,47}$ | |
| wait | No | ||
| since | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It is transparent about the blocking long-poll behavior, the 10-second timeout, the untrusted result, and the need to check wait_held before retrying. However, the meaning of 'wait_held' and the security implications of 'UNTRUSTED' are left unexplained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, with the core operation front-loaded and every sentence adding distinct value. There is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core operation and critical caveats are present, making the tool usable at a basic level. But since is a required parameter and its semantics are entirely absent, and the return shape and wait_held meaning are unspecified, with no output schema to compensate. This is adequate but clearly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%: wait and since have no descriptions. The description adds that the operation lasts up to 10 seconds, roughly covering wait's semantics, but the required since parameter and the units/meaning of wait are not fully clarified. The description does not adequately compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Long-poll a room for the next message', a specific verb and resource that immediately convey the tool's function. The 'up to 10 seconds' cap and 'next message' focus clearly distinguish it from sibling tools like read_room or list_rooms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied rather than explicitly guided: an agent can infer to use this when waiting for a new room message, but the description never names alternatives or says when not to use it. The retry note 'Check wait_held before retrying' is operational guidance, not tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.