Wait for a T3 run change

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

Annotations say readOnlyHint=true, and the description clarifies that the tool is a non-mutating poll. It adds important context: a timeout is not an error and does not cancel the run. This aligns with annotations. Only minor gap is that it doesn't specify what happens on run completion vs. no change, but the timeout clarification is valuable.

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 two sentences, concise and front-loaded with the primary action. It adds the key behavioral nuance about timeout without redundancy. Could include parameter hints but the brevity is a strength.

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?

There is an output schema (though not shown in detail) which might document return values, so description doesn't need to. The tool is relatively simple with two parameters. The description covers the main purpose and timeout behavior, but misses parameter meanings (since schema coverage is 0%) and doesn't explain 'relevant run change' or how to interpret polling results. Adequate but with gaps.

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 explain the parameters, but it does not. The runId is only type string with minLength, and timeoutSeconds has defaults and bounds, but the description doesn't define semantics like 'timeoutSeconds' meaning maximum wait time or what 'runId' refers to. The schema provides structural constraints but not meaning.

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 a clear purpose: 'Poll for a relevant run change for a bounded interval.' It identifies the resource (run) and action (wait/poll), which is specific enough. However, it does not clarify what constitutes a 'relevant' run change or how it differs from related tools like t3_run_get, which might be used to check status instead of waiting.

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 implies usage: when you need to wait for a run change with a timeout. It does not explicitly state when NOT to use it, nor does it mention alternatives like t3_run_get for immediate status checks. The timeout semantics are partially explained (does not cancel run), but there is no guidance on choosing between this and polling manually.

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