q_await

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

With no annotations to rely on, the description carries the full burden and does so thoroughly. It discloses that the tool blocks until completion or error, that it is one-shot (a job_id can only be awaited once), and enumerates all error scenarios (job not found, TTL cancellation, server shutdown, underlying council errors). It also conveys the operational expectation that the host must not end its turn with an outstanding job. This goes far beyond a minimal disclosure.

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 highly structured: the first sentence delivers the core purpose, the second paragraph provides usage context, and a bulleted list covers errors. Every sentence earns its place; there is no fluff. The information is front-loaded with the most critical fact (blocking behavior) stated immediately.

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 description fully covers what an agent needs to know to call this tool correctly: it explains the blocking nature, the one-shot constraint, the exact error outcomes, and the return value (rounds markdown). An output schema exists, so detailed return formatting is not required. There is no missing information that would prevent correct invocation or interpretation.

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?

The single parameter `job_id` has zero schema description, so the description must compensate. It does by explaining that the job_id identifies the background run, and the error section clarifies what happens if the id is invalid (expired, already retrieved, or invalid). It stops short of specifying a format (e.g., UUID), but since a valid id comes from a sibling start tool, this is sufficient for the agent to understand its role.

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 a specific verb ('Block'), a clear resource ('background council run identified by job_id'), and an outcome ('return its rounds markdown'). It distinguishes itself from the sibling start tools (q_plan_start, q_brainstorm_start, etc.) as the blocking completion counterpart, so an agent can immediately tell what this tool does and how it differs from its siblings.

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 description explicitly states that this is 'the blocking completion notification for every council start' and gives a clear directive: 'The orchestrating host must not end its turn with a live job outstanding; it calls q_await after its independent work.' It also warns that it is one-shot, leaving no ambiguity about when and how to use it. No alternative tools are mentioned, but the context of siblings being all start tools makes the usage obvious.

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