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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive); the description carries far more, disclosing that every route is assertion_class 'inferred', that currency species (water, ATP, protons) are excluded as intermediates and are never materialised as from_id/to_id, and that asking about one returns reachable: null with a coverage note rather than a checked '0 routes'. It also enumerates the three distinct meanings of a missing route and points to the coverage field that disambiguates them.

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?

Front-loaded with the core purpose and the safety framing before the edge cases, and nearly every sentence conveys non-redundant semantics (inference class, currency-species exclusion, coverage field). Some sentences are long and clause-heavy, but the density is justified by the amount of non-obvious behavior disclosed.

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 a read-only, no-annotation-beyond-safety profile, the description covers what an agent actually needs: what is returned (routes plus assertion_class), the coverage field's three interpretations, the null-on-currency-species case, and how from_id/to_id shape the result. Nothing material is left unstated for a 5-parameter query tool.

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 already 80% and documents depth, limit, to_id and from_id. The description adds meaning beyond that: to_id's dual role (target check vs. full listing), the currency-species edge case that makes to_id/from_id structurally excluded, and the 3-step ceiling implied by 'up to 3 steps'. It does not explain offset or the pagination interaction with limit.

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?

States a specific verb and resource: breadth-first reachability over reactions recorded in Rhea and Human-GEM, answering 'what a compound could become, and through which reactions and enzymes, within up to 3 steps.' It explicitly contrasts itself with the sibling get_findings ('For measured effects, use get_findings'), so the agent can separate it from alternatives without opening a schema.

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?

Gives explicit when-to-use (biochemical connectivity hypotheses), when-not (never as an effect, recommendation, or claim that the body does this), the alternative for measured effects (get_findings), and the two operating modes (supply to_id to check one target, omit it to list everything from_id reaches).

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