ci_wait_for_run

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

With no annotations, the description carries the full burden. It discloses that the call blocks up to timeout_seconds, can be repeated, and returns status and per-step results. It does not explain what happens on timeout, whether the call is idempotent, or how polling behaves, so the disclosure is helpful but incomplete.

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?

Two sentences with no filler. The core behavior is front-loaded, and the practical timing guidance earns its place without bloating the description.

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 wait operation, the description covers the main behavior and intended usage pattern, but the lack of annotations and output schema leaves gaps around timeout behavior, parameter meaning for non-obvious fields like poll_seconds, and the exact structure of the returned per-step results.

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 needed to compensate. It only interprets timeout_seconds ('up to timeout_seconds'); run_id, poll_seconds, repo, and project_path remain unexplained. This leaves most of the 5-parameter surface undocumented.

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 verb and resource: wait for a run to finish and return status plus per-step results. It does not explicitly compare against sibling tools like ci_list_runs or ci_get_logs, but the wait/results purpose is unambiguous.

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?

It tells agents to call repeatedly for long builds and gives a concrete duration expectation for iOS builds, which is useful guidance. It does not explicitly spell out when not to use it or name alternatives, but the repeated-call instruction conveys the intended usage pattern.

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