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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is low, and the description still adds real behavioral context: step output is 'trimmed', steps may have run on sample data or been switched off, and the check block is absent until check_test_run has scored the run. It omits failure/not-found behavior and whether the trimmed output can be obtained in full, which keeps it short of a 5.

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?

It is a single information-dense sentence with no filler, which is efficient. However, the comma-separated field list is not front-loaded with a verb or purpose, making it read like a partial response schema rather than a callable action.

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?

Because there is no output schema, the description carries the entire return-value burden and does enumerate most of the payload, including the conditional check block. It still leaves ambiguity about how to interpret 'done' and 'status', and what a trimmed step output actually contains.

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?

With a single parameter and 100% schema description coverage, the schema already explains that test_run_id comes from test_run_draft or list_test_runs, so no semantic lift is required from the description. The description adds nothing about the id itself, which is acceptable at baseline.

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 text is a noun-phrase inventory of the returned fields ('A test run: status, done, the output, each step's status and output...') rather than an explicit verb+resource statement; the 'read' framing comes only from the title. An agent can infer this fetches a single test run by id, partly because it names 'check_test_run' as the scorer of the check field, but the description itself never says 'retrieve' or scopes the single-record nature.

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?

There is no when-to-use guidance and no disambiguation from the near-identical sibling 'get_run'. The only actionable hint is the sequencing note that the check appears 'once check_test_run has scored it', which implies an ordering prerequisite but is phrased as a payload description rather than an instruction.

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