Wait for job state

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

Annotations only provide readOnlyHint and idempotentHint. The description adds substantial behavioral detail: internal polling at 200ms, no early return on intermediate transitions, wait_ms=0 as an immediate snapshot, how after_cursor applies to the log tail, and that only the judgement packet is returned. This far exceeds what annotations convey.

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 but every sentence carries operational information: blocking behavior, polling interval, wait_ms=0 semantics, return content scope. It is a bit long, but it avoids redundancy and front-loads the most critical behavioral caveat (does not return early on intermediate transitions) early. Slight over-length keeps it from a 5.

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?

Given the tool has no output schema, the description adequately explains the return payload ('judgement packet only, not full logs or the response text'). Combined with annotations covering safety, the description is sufficient for an agent to invoke it correctly. It lacks explicit mention of error handling or edge cases (e.g., job not found), but those are not essential for basic usage.

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?

With 67% schema coverage, the description compensates by explaining the behavioral semantics of wait_ms (blocking budget, 0 returns immediate snapshot) and after_cursor (byte offset applied to in-progress log tail, finished job returns full packet). This adds meaning beyond the schema descriptions, though job_id is not described beyond its presence in the required field.

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?

Description clearly states the tool's purpose: 'Long-poll a job until it FINISHES or wait_ms runs out'. It specifies a precise verb (long-poll), a resource (job), and the termination condition. It also differentiates from siblings by noting it returns only the judgement packet, not logs or response text, helping distinguish from agy_result and agy_logs.

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 explains the blocking behavior and the meaning of wait_ms, which implies when to use it (e.g., to wait for a job to finish). However, it does not explicitly state when to use this tool versus alternatives like agy_result or agy_logs, or when not to use it. The usage context is present but left to inference.

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