pi_wait

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

With no annotations, the description carries the full burden, and it does disclose two real behaviors: a hard 300-second cap and that only a 'result header' is returned rather than the full payload. It does not say what happens on timeout, whether the call blocks or polls, or that a header presumably requires a follow-up call (pi_result) for the body. Useful but materially incomplete for a blocking operation.

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?

A single sentence with zero padding, and the most decision-relevant facts (time bound, return shape) are front-loaded. It is arguably too terse given the undocumented parameters, but as a structural matter there is no wasted wording.

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 three-parameter, no-annotation, no-output-schema tool, the definition is thin: it omits timeout behavior on expiry, the meaning of cwd and job_id, and any indication of how the 'result header' relates to pi_result. The 300-second cap is the only operational constraint an agent can rely on.

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 0% across three parameters. The description adds meaning only for timeout_seconds by implying a 300-second ceiling, and says nothing about job_id (the identifier of the job being waited on) or cwd (working directory semantics). Two of three parameters are left entirely undocumented in both the schema and the description.

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?

States a specific verb ('Wait'), the resource ('a job'), a bound ('up to 300 seconds'), and what comes back ('its result header'). That is far more specific than the name alone. However, it does not distinguish itself from the sibling pi_result, so an agent cannot tell from this text alone which of the two to reach for.

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?

No when-to-use guidance is given: it never says this should follow pi_execute, nor when to prefer pi_wait over pi_result or pi_list. The polling/waiting intent is only implied by the verb. There are no exclusions or prerequisites, and with 0 required parameters it is unclear whether job_id is mandatory in practice.

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