run_inspect

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It thoroughly explains the returned state shapes, the fact that reading is non-destructive ('nothing is consumed by reading it'), and that provider resources are released on first terminal read (RunSupervisor.cleanup()). It also discloses memory growth and references the durable state machine scope. This is exemplary transparency.

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 detailed and covers many important aspects (state shapes, retention, cleanup, edge cases). Every sentence adds value, but it is somewhat verbose for a simple polling operation. It could be condensed without losing critical information. However, given the complexity of the behavior (retention, resource cleanup, cancellation nuances), the length is justified.

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?

With no output schema and no annotations, the description must fully explain the return values and behavioral nuances. It does so comprehensively: describes both running and terminal states, merges with execute_code result shape, handles cancellation caveats, explains retention and cleanup semantics, and notes memory implications. This is complete for the tool's complexity.

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?

The schema has only one parameter, run_id, with 0% description coverage. The description does not explicitly say that run_id is the identifier returned by run_submit, though it is implied by 'Poll a background run started with run_submit.' This is adequate but leaves room for explicit clarification (e.g., 'run_id as returned by run_submit'). The description adds minimal parameter-specific detail beyond the schema.

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 opens with 'Poll a background run started with run_submit', which clearly states the verb (poll) and the resource (a background run), and immediately distinguishes it from the sibling run_submit (which starts runs) and run_cancel (which stops them). This is a specific, action-oriented description.

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 clearly states when to use the tool (to poll a background run) and provides guidance on interpreting terminal results, including checking 'ok' and 'verdict'. It also references run_cancel's docstring for cancellation semantics. However, it does not explicitly state when NOT to use it (e.g., if you need to start a new run or cancel one), though the context makes that clear.

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