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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing this as a safe read/planning call. The description adds real context beyond that: returned steps are tagged with seeded/asynchronous status, whether they write or leave the machine, what grades them, and which already-read data files they re-read. It does not cover latency or whether prior run context is required, keeping it from 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?

The purpose is front-loaded in the opening clause and there is no filler about generic benefits. The middle sentence, however, is an overlong clause packing a list of return attributes and the data-file-overlap concept into one breath, which harms scanability. Useful content, but structure could be tightened.

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 an 8-parameter, nested-schema, closed-world planning tool with an output schema, the description covers both invocation modes and the nature of the returned graph edges. Since an output schema exists, it need not detail return shapes, and its coverage of the input modes is adequate. Error handling and session prerequisites are unaddressed, so not a 5.

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 coverage is 100%, so the baseline is 3. The description still adds mode-level meaning the schema cannot: `after` vs `output_types` as the mutually-exclusive hand-in, and `target_type` triggering shortest-chain search. It lightly implies `max_steps` bounds chain search but adds no detail on `read_only`/`independent_only` beyond the schema text.

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 a specific function: given a just-finished tool (or output types), it returns candidate next tools whose declared inputs those outputs fill, and with `target_type` it returns shortest tool chains. This is clearly a workflow-graph traversal/planning tool, distinguishable from `run_workflow` or `validate_workflow`. It stops short of explicitly naming sibling alternatives such as `rank_next_tests`, so it does not reach 5.

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 gives concrete entry conditions: 'Give it a tool whose run just finished (or the output types in hand)' and 'Ask for a `target_type` and it returns the shortest chains'. That cleanly describes the two invocation modes. It never states when not to use it or which sibling to prefer for adjacent needs, so 4 rather than 5.

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