Catalyst evidence graph

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

Annotations already cover the read-only/idempotent safety profile, and the description layers on genuinely new behavior: name-to-node resolution in one call, what each returned finding contains, the no-about summary mode, and the required no-match fallback ('tell the person Catalyst has no findings'). It also warns that evidence strength is not a recommendation, which guards against agent misinterpretation.

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 trigger scenario, then the parameter guidance, then return shape and the failure rule. Slightly dense as one paragraph, but nearly every sentence carries actionable content; the closing definition of evidence strength is defensible as interpretation guidance.

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, the description correctly carries the return-value burden: it enumerates claim, evidence strength, design, population, dose, quote, paper, permalink and citation, and covers the empty-result path. Nothing needed to call or interpret this tool is missing.

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%, so the baseline is 3. The description adds real meaning beyond the schema by explaining the query/about split as a division of labor ('Pass the substance as query, and the specific effect, if there is one, as about') and what happens when about is omitted, which the schema's per-parameter text does not convey.

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 with concrete example queries ("does magnesium help sleep?"), so the agent knows exactly what class of question this answers. It implicitly separates itself from get_finding/get_findings by noting that one call resolves a name 'in their words' to the node with findings, though it never names those siblings explicitly.

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 an explicit trigger condition ('Use this when someone asks what a supplement, nutrient, drug, food compound or plant does... or whether it affects something specific') plus a behavioral rule for the no-match case. It stops short of naming the alternative tools (search_nodes, get_findings) for when the agent already has a node id.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description goes beyond that by disclosing the response structure, the ordering of evidence_strength_reasons ('each rule that set the level, in order'), and what the assessment does not weigh.

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 resource and then the payload, followed by one usage sentence. The long enumerated clause is dense but every element earns its place; minor compression is possible.

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?

No output schema exists, so the description carries the return-value burden and does so thoroughly, listing every field and the semantics of evidence_strength_reasons. Nothing needed to call it correctly is missing.

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% and the single parameter is already documented with its pattern and source. The description adds the concrete permalink shape ('the last part of a permalink, /e/{id}'), which meaningfully supplements the schema's generic 'from a permalink or get_findings'.

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 (get) and resource (one finding by id) and enumerates exactly what comes back: claim, evidence strength and its meaning, verbatim quote, study design, paper, and evidence_strength_reasons. The singular 'One finding' cleanly separates it from the sibling get_findings.

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 an explicit use case: 'Use it to explain why the evidence behind a finding is as strong as it is, from evidence_strength_reasons rather than by guessing.' It also tells the agent where the id comes from (permalink or get_findings), but it does not explicitly name alternatives or exclusions.

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

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

Adds substantial behavior beyond the read-only/idempotent annotations: summary spans ALL findings, not just the returned rows; an empty list means nothing curated yet rather than no effect; evidence strength is not a recommendation; and it instructs the agent to always carry the strength and permalink with the claim. These are non-obvious semantics the annotations cannot convey.

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?

Long but front-loaded: what the tool returns, then how to narrow, then what each finding carries, then the caveat about empty results. Slight redundancy (the five strength levels are listed and then re-referenced) keeps it from a 5.

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?

No output schema exists, so the description must describe returns, and it enumerates them fully: claim, evidence strength, verbatim sentence, paper, population, dose, permalink, and a ready-to-quote citation, plus the brief/full detail distinction. Nothing needed to call or interpret this tool is missing.

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, but the description adds meaning to `about` by tying it to the summary output and allowing free words like "sleep", clarifying its role in the two-step workflow. The five evidence-strength levels are restated but already enum-documented, so value is only marginally above 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?

States a specific verb+resource (curated study findings for one node) and immediately disambiguates the two directions it works in: compound→what it affects, outcome→which compounds were studied against it. This distinguishes it from the singular sibling get_finding and from find_evidence.

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 an explicit workflow: call with node_id to see coverage via summary, then pass about (id or words) to narrow to one thing. It does not explicitly name or rule out siblings such as get_finding or find_evidence, so the routing is clear but not exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: assertion_class is always 'inferred', coverage is one Rhea plus one Human-GEM release, hub compounds return counts only, unlinked participants and human-enzyme-only listing, plus the empty-result interpretation. This is unusually rich behavioral context.

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?

Long but front-loaded and dense: the identity of the data, the 'inferred' caveat, and the routing to get_findings come first, with edge cases after. Only the coverage sentence is somewhat sprawling, but nearly every clause carries distinct information.

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 a read-only lookup with no output schema, the description supplies everything needed: row semantics, hub-count exception, participant linkage rules, and empty-result meaning. An agent can interpret results correctly without an output schema.

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 only 33% (node_id documented, limit/offset not), so the description needs to compensate but does not: it adds no meaning about limit, offset, or pagination behavior. The node_id example lives in the schema, not the description.

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 precise verb+resource: biochemical reactions from Rhea/Human-GEM that a compound or protein participates in, with the direction (substrate/product vs catalyses/transports) spelled out. It clearly distinguishes itself from the sibling get_findings by naming it as the tool for effects.

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?

Explicitly says to use this tool for biochemistry but get_findings for effects, warns never to present rows as an effect or recommendation, and explains the hub-flag special case and what an empty result means. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-derivable context: every row is assertion_class 'inferred' and is a hypothesis, not a measured result. It does not mention pagination or result volume, but the epistemic caveat is the higher-value disclosure.

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?

Three sentences, fully front-loaded: what the tool returns, the critical inferred/hypothesis caveat, then the presentation rule plus the alternative. No sentence is filler; the caveat is placed before the alternative deliberately.

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?

No output schema, so the description carries return-value context — it discloses that rows are inferred assertions. It pairs well with the read-only annotations and the required node_id. Pagination semantics are left to the schema's defaults/ranges, a minor gap for a 4-parameter list 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 coverage is 50%: node_id and predicate are documented inline ('A node id from search_nodes, e.g. CHEBI:16919', 'e.g. transports'), while limit/offset rely on defaults. The description's category list (transporters, enzymes, pathways, expression) loosely hints at predicate values, but it does not add format or syntax beyond the schema, so the baseline of 3 applies.

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+resource — what public reference databases (Reactome, UniProt, Rhea, ChEBI) record about a node — and enumerates the content types (transporters, enzymes, pathways, expression). It explicitly distinguishes itself from the sibling get_findings, so an agent can route without opening either 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-not guidance ('never as effects' / 'present these as possible mechanisms') and names the alternative tool by name: 'For effects, use get_findings.' This is exactly the when-to-use/when-not/alternative triad.

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

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.

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, so the safety profile is settled. The description adds real behavioral detail beyond that: result ordering (hits with findings first), the presence of a finding count per hit, and an explicit negative-scope statement that it does not describe the entities it returns. Pagination or result-size behavior is not covered, so it stops 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?

Front-loaded with the action, then chaining, then ordering guidance, then a boundary statement. Every sentence carries distinct information and none is redundant with the title or schema.

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, the description must carry the return-value burden, and it does: node ids, per-hit finding counts, and result ordering. It does not describe the full shape of a hit (id plus display name, possible synonyms) or whether the list is truncated, which is the only remaining gap for a one-parameter search 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 coverage is 100% for the single parameter, so the baseline is 3, but the description adds concrete example values ("magnesium", "vitamin D", "sleep", "creatine") that clarify the expected granularity of a query beyond the schema's "A name, synonym or phrase."

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 ("Search the Catalyst evidence graph by name or synonym") and immediately scopes what it does versus its siblings with "It finds things; it does not say anything about them." An agent can distinguish it from get_findings, get_relations and reach without opening any 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?

Explicitly routes the agent onward: "Returns node ids to pass to get_findings or get_relations," naming the two downstream alternatives. It also gives selection guidance — "hits with findings come first, so the first hit with findings above 0 is usually the one to use" — which is actionable usage instruction rather than vague context.

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