Skip to main content
Glama

Wait for hub events

hub_wait
Read-only

Blocks until the subagent hub needs your attention, changes state, or goes idle, returning timeout status and pending lines; call again after a timeout.

Instructions

Block until the hub needs the master's attention (a task entered need-info / failed / rejected, or the hub went idle after a change) or timeoutSec elapses (default 55, max 55). Returns { timedOut, lines }; if timedOut, just call hub_wait again.

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": "hub_wait"
  }
}

Input Schema

NameRequiredDescriptionDefault
untilNoDefault attention.
cursorNoCursor name, for concurrent waiters. Default master.
timeoutSecNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.0

TDQS

A4/5.0
Behavior4/5

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

The annotations only establish that this is a read-only, closed-world call, and the description adds the real behavioral facts: the call blocks (does not poll and return), the timeout is clamped to 55s with a default of 55, and the result shape is { timedOut, lines }. It still does not say what 'lines' actually contains, and 'the master' role and the 'cursor' concept are left implicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with no waste: the trigger condition and timeout rule come first, and the return shape and retry loop follow. Every clause adds information.

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?

There is no output schema, but the description compensates by stating the return shape and the retry contract, which is what an agent needs to call this in a loop. The gaps, the unmentioned cursor parameter and what 'lines' contains, are minor but not negligible for a concurrent-waiter tool.

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 67%: timeoutSec gains a default (55) that the schema omits, and the trigger conditions loosely map to the until enum. However, the third parameter, cursor ('for concurrent waiters, default master'), is never mentioned, and the boundary between 'attention', 'change' and 'idle' is only partially explained.

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 definition gives a specific blocking verb and states exactly what wakes it: a task entering need-info/failed/rejected, or the hub going idle after a change. It is precise about semantics, but it never names the sibling tools it overlaps with (swarm_wait, zcode_wait, hub_show), so an agent cannot tell from the text alone which wait primitive to pick.

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

Usage Guidelines4/5

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

The guidance is clear: call it to block for attention; if the result is timedOut, simply call hub_wait again, which squarely addresses the polling loop an agent will hit. What is missing is when not to use it, for example when to poll with hub_board or hub_show instead of blocking.

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