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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior the annotations cannot express: wait_s blocks the call until the run ends or the timeout elapses, and the reported fields change depending on completion state (DRC-by-type, fab release, diagnosed causes appear only once finished, with a 'fix first' ordering). Return-format disclosure like this is the real value here.

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, no filler, and the returned-field inventory is front-loaded before the wait_s semantics. The first sentence is a dense comma list, which is slightly heavy, but every item is informative rather than padded.

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 no output schema, so the description carries the return-value burden, and it does so thoroughly: run state, metrics, DRC detail, release status, and failure causes with priority ordering. Combined with the explicit wait_s blocking rule, an agent has enough to call and interpret it. The only shortfall is the missing contrast with sibling status tools.

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 100% and both parameters are documented in the schema, so baseline is 3. The description only restates wait_s semantics ('holds the call until the run ends (or that many seconds pass)'), which is roughly what the schema already says ('Seconds to wait for a running board to finish (max 55)'), adding little new syntax or edge-case detail.

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 names the specific resource — the board run — and enumerates exactly what is reported (stage, size, layers, placement, routing completion, open nets, DRC counts, fab release, diagnosed causes). That is well beyond a restatement of the name. It does not, however, distinguish itself from close siblings such as get_fab_status, get_board_job, or board_census, so the agent cannot tell from the text alone which status endpoint to pick.

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?

Usage is only implied: the wait_s sentence signals this is polled until a run completes, which is useful. There is no explicit when-to-use guidance, no statement of when to prefer this over get_fab_status/get_board_job, and no prerequisites or exclusions. Adequate but with a clear routing gap.

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