mesh_wait_room

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It does this by disclosing the underlying background tap, noting the call reads an existing feed rather than opening anything new, the behavior under an MCP host that backgrounds slow calls (turning into push), and the turn-blocking limitation—the agent's own turn remains occupied for the duration. It also transparently explains that the server cannot hand off a fresh turn to an idle client, which is critical for the agent to avoid misuse.

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?

The description is dense with required behavior, and it is front-loaded with the core behavior before a thoughtful set of caveats and alternatives. It is longer than average, but nearly every sentence adds a necessary distinction or answer a potential mis-call: it justifies why this isn't the same as saying something, explains the background tap, notes the harness workaround, and disallows a common wrong loop. A couple of clauses (like 'for free' at the end) could be trimmed, but overall the length mirrors the tool's real complexity.

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?

For a blocking tool with no annotations and not output schema, this is conspicuously complete. It covers what happens, how long, the first-from-someone semantic, turn ownership, and how it interacts with an MCP host's backgrounding behavior, and it points to mesh://etiquette for fringe scheduling choices. The missing return-value explanation is not necessary for a blocking wait; the envelope's subsequent consumption is covered indirectly by naming reading alternatives. An agent calling this has all the knowledge it needs to avoid hangs and misrouting.

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 100%, so the baseline is 3. The description still adds real semantic value beyond the schema: it clarifies that room_topic accepts 'agents.lobby' as a central room, says the room will be joined if not already present, and makes explicit that this is the 'first envelope from someone else' (excluding self-writes). It does not go deep on host, but the schema covers the host's default, and the added context about the watcher feeding the wait is useful for understanding parameter behavior.

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 states a specific verb, resource, and scope: it blocks for up to wait_seconds waiting for the first envelope from someone else on a room the caller already belongs to, while requiring no outbound message first. It explicitly contrasts itself with mesh_say's wait_reply_seconds and identifies itself as the passive counterpart, making sibling differentiation crisp. Even without opening schemas, an agent can tell exactly when to choose this tool over mesh_say, mesh_read_inbox, or the harness scheduler.

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?

This section gives explicit when-to-use context: use it when you have nothing to say yet and are just waiting for an answer, objective, or reply. It also names the alternative paths the caller should consider instead (harness scheduler, mesh_read_inbox, manual sleep-and-check), and it clearly says never to use a sleep-then-check loop — a one-shot full wait is the correct usage. These are concrete, actionable rules with exclusions.

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