wait_run

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's role is to add behavior beyond that. It does add the polling loop requirement (caller must continue polling if terminal=false), which is useful. However, it does not explain what 'terminal' refers to or what happens on timeout, leaving some ambiguity. This is a moderate addition given the annotation coverage.

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 a single, dense sentence in Chinese with no wasted words. It front-loads the maximum wait time and then states the polling condition. While brief, it is efficient and to the point, though it could benefit from a bit more structure.

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 and limited annotations, the description needs to explain the interaction flow. It mentions the 'terminal=false' condition but does not define what terminal is, how the caller receives it, or what the return value looks like. It also does not clarify the role of relayRunId in identifying the run. This is incomplete for a polling tool that an agent is expected to use correctly.

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%, so the description must compensate for parameter meaning, but it mentions no parameters at all. The schema only provides basic types and constraints (e.g., waitMs is an integer 0-30000), but the description does not explain the purpose of waitMs or relayRunId or how they affect behavior. This is a significant gap for a 2-parameter tool.

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 the tool waits up to 30 seconds, making the primary action clear. However, it does not differentiate from sibling tools like get_run, which could also be used for polling run status. The 'wait' verb is specific, but the description lacks explicit resource context beyond the run-related name.

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 provides no guidance on when to use this tool versus alternatives. It mentions a polling requirement ('mustCallAgain=true') but does not state when to choose this over get_run or other siblings, nor any exclusions. This leaves the selection decision to the agent without support.

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