Aviado Health BioIntelligence

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing what is actually written and when: include_claim_link 'stores a small record for 30 days (only when enabled)'. It also exposes domain behavior an agent could not infer: FDA-label checking with 'major picks dropped, moderate flagged,' the warning that 'unlisted medications are NOT checked,' avoid-level cautions leading as cautions_summary, and the serious-disease no_match path. No contradiction with the annotation profile.

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-loading is good — stack size and scope come first — and nearly every clause carries actionable information. However the whole definition is a single semicolon-and-parenthesis-choked run-on, making it hard to scan; the interaction, caution, and claim-link rules would parse far better as separate structured sentences.

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, yet the description enumerates the return shape precisely: 'Each item: why, grade, study dose (context), PMIDs, cited cautions... same-mechanism and interaction flags,' plus data.important_cautions and data.claim.claim_url. For a composite, non-idempotent tool this covers purpose, inputs, outputs, failure modes, and follow-up routing.

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 genuinely extends the schema: `exclude` 'also takes medications by generic name (checked against FDA labels)' and unlisted meds are explicitly NOT checked, and `include_claim_link` is explained as storing a 30-day record and returning data.claim.claim_url. It adds interaction semantics and side-effect meaning the schema does not carry.

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+scope: builds a 'starter stack (default 3, max 5) of recommendable supplements for a goal,' with concrete examples ('insomnia', 'LDL cholesterol'). It distinguishes itself from the list-style siblings by framing output as curated, interaction-checked picks ('never Rx or research', 'hypotheses' for biomarker-proxy rows), though it never names get_supplements_for_condition/get_supplements_for_biomarker as the alternatives it supersedes.

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?

Provides real routing guidance: excludes serious disease ('not offered for cancer or other serious disease (no_match)') and tells the agent to 'ask, then use get_supplement_interactions with `drug`' when a medication is unlisted. Clear context and a named fallback, but it does not contrast against the other recommendation-style siblings (get_supplements_for_condition / get_supplements_for_biomarker), so the when-to-choose-this branch is only partial.

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 the safety profile (readOnly, idempotent, destructive=false), yet the description adds substantial context beyond them: input normalization rules (salt forms merged, brand names not matched), the coverage level scale, and the crucial caveat that found:false is NOT a safety answer. This is exactly the extra behavioral context an agent needs.

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?

Dense but front-loaded: the core action and input rules come first, coverage matrix and the found:false caveat follow. Every sentence earns its place, though the single ~130-word block is slightly cramped and would benefit from light structuring.

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 burden and does so fully, enumerating the verdict fields (found, severity, direction, summary, recommendation, recorded_for, evidence_level, sources) and the coverage scale. For a 2-param pairwise lookup, nothing material 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 real meaning: it clarifies that each param is a supplement (name or canonical_id) OR a medication (generic name), and notes that salt forms are merged while brand names are not matched. That disambiguation is present in neither schema field.

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 states a specific verb+resource ('Point check of one pair') and scopes it precisely with input types and a size estimate (~1-3 KB). The 'one pair' framing implicitly distinguishes it from the listing sibling get_supplement_interactions, but it never names that sibling, so the differentiation is left to inference.

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 clear when-to-use boundaries: supplement+supplement uses curated data, supplement+medication uses FDA labels only, and medication+medication is explicitly not covered (no_match). It also directs 'Check status first' and explains what needs_confirmation/no_match mean for retry. It does not name the alternative tool for bulk interaction listing.

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 the safety profile (readOnly, idempotent, non-destructive), and the description adds a lot beyond them: ordering by prior_weight with the explicit caveat that it is graph evidence weight, not a calibrated probability or effect size; that dose is evidence context and not a dosing recommendation; that null fields are omitted; and that results are partial/non-exhaustive so absence is not evidence of no effect. These are exactly the non-obvious traits an agent needs.

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?

A single dense paragraph with no filler sentences, and it front-loads the core purpose before the field-by-field detail and the status-handling note. The heavy parenthetical nesting makes it harder to scan than it needs to be, but nothing is wasted.

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 full burden of explaining return shape, and it does: per-entry fields (direction, goal/subgoal, verification flags, pmids with n_studies/rct_count, dose), omission of nulls, ordering, and failure states. An agent can interpret a response without further documentation.

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 the schema lacks: the supplement parameter accepts either a plain name or an Aviado canonical_id, and where to obtain one. The limit parameter is left to the schema, which documents it fully.

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 and direction: 'Biomarkers a supplement moves in the Aviado app's evidence graph, one entry per biomarker (strongest edge).' This is unambiguously the supplement→biomarker direction, distinct from the inverse sibling get_supplements_for_biomarker and from the broader get_interventions_for_biomarker.

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 real invocation guidance: the supplement argument may be a name or canonical_id sourced from search_supplements/candidates, and it instructs the agent to 'check status first' with named status values (needs_confirmation/no_match) and what to do on failure. It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it is clear context rather than full routing.

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-open-world); the description adds substantive behavior: partial/non-exhaustive coverage, graph_status as an internal eligibility label rather than clinical validation, pathway_tags as raw unvalidated metadata, up to 3 PubMed IDs per row, and how unresolved inputs surface via status. This is exactly the extra context annotations cannot carry.

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 core purpose is front-loaded, but the rest is one long semicolon-chained paragraph mixing caveats, field semantics and error handling. Most sentences carry real information, yet the density and run-on structure make it harder to scan than it needs to be.

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 must describe returns — and it does: intervention_type taxonomy, direction, pmids with URL template reference, graph_status, pathway_tags, and the status/next_step failure path. An agent has what it needs to call and interpret results.

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 only a little beyond the schema: it confirms the biomarker may be an Aviado id (schema says name/abbreviation/LOINC) and repeats that direction is optional, without new syntax or format rules.

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 with scope: 'All mixed interventions in Aviado's evidence graph that move a biomarker'. The word 'mixed' plus the note that non-supplement rows are context implicitly separates it from get_supplements_for_biomarker, but no sibling is named outright, so differentiation is inferred rather than explicit.

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 usable operating conditions: optional direction filter for up/down, 'check status first' with needs_confirmation/no_match meaning and next_step, and a warning that absence is not evidence of no effect. It stops short of explicitly telling the agent when to prefer this over get_supplements_for_biomarker or get_biomarkers_for_supplement.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: contraindications are rolled up from contained compounds and tagged with recorded_for, only cited rows appear so an empty list is not proof of safety, and needs_confirmation/no_match produces null data plus a next_step.

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 payload summary, then routing, then edge-case semantics — logical ordering with no filler. It is dense and reads as one long block, which slightly taxes scanning, but every sentence carries operational 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?

There is no output schema, so the description must describe the return payload, and it does thoroughly (what fields come back, citation counts, the 'top 5' cap, the recorded_for labelling). Combined with the failure-mode behavior, an agent has everything needed to call and interpret this 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% so the single string parameter is already documented, but the description adds real meaning by clarifying the value may be a supplement name or an Aviado canonical_id and pointing to search_supplements or a candidates list as its source. The 512-char limit and format constraints remain schema-only, which is fine.

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 ('Overview of one supplement') and enumerates exactly what the payload contains: description, uses, top 5 biomarkers with citations, goals, mechanism tags and contraindications. It also explicitly distinguishes itself from the two nearest siblings by name.

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 routing rules ('For all biomarkers use get_biomarkers_for_supplement; for drug interactions use get_supplement_interactions') and states the accepted input forms and their provenance. The status-check guidance tells the agent what to do when the input fails to resolve.

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?

Goes well beyond the read-only annotations: coverage caveats ('sparse or missing for most others', 'never treat an empty or short list as proof of safety'), error-not-empty-list behavior on data-source failure, status/null semantics on unresolved input, and the label_artifact_suspected flag for salt-only drug-name matches. This is unusual behavioral depth.

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?

Dense but front-loaded with the highest-value caveat (coverage quality and the safety warning) before parameter mechanics. The heavy semicolon-chained sentences and stacked parentheticals push it toward over-packing, though nearly every clause carries information an agent needs.

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 return-value semantics, and it does: interaction_sources/recorded_for labelling, one-entry-per-drug ordering, paging fields, the artifact flag, and status/next_step. Nothing necessary for a correct call appears 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 interpretation the schema does not fully carry: salt-form merging vs unmatched brand names, the canonical_id alternative for supplement, and the derived drug_page.total/next_offset paging loop. It reinforces rather than merely repeats the 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?

Names a specific verb+resource (get supplement interactions) and immediately scopes it: FDA-label drug interactions plus curated supplement-supplement interactions, with the inclusion rules for each. An agent can distinguish this from the sibling check_interaction because the description spells out the two interaction classes and how they are gated by the drug parameter.

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 clear triggering conditions: 'To check one medication pass drug', and explains that supplement-supplement interactions are omitted on a drug check unless include_supplement_interactions is true. It also instructs to 'Check status first' for needs_confirmation/no_match. It stops short of naming when to prefer a sibling tool, so not a full 5.

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, yet the description adds substantial context beyond them: null fields and default typing are omitted per row, results are partial and non-exhaustive, prior_weight is confidence not effect size, graph_status is an internal eligibility label not clinical verification, dose is evidence context not a dosing recommendation, and pathway_tags are unvalidated raw metadata. This is exactly the caveat layer an agent needs for safe interpretation.

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 first sentence and every clause carries information, but the body is a dense run-on paragraph that mixes field semantics, status handling and caveats, making it harder to scan than it needs to be. No filler sentences, though.

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 carries the full burden of explaining the return shape, and it does so field by field (direction, prior_weight, graph_status, has_verified_support/mixed_evidence, dose, pmids, n_studies/rct_count) plus failure handling via the status field. Nothing needed to call or interpret 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%, so the baseline is 3, and the direction enum semantics are already spelled out in the schema. The description does add meaning beyond it by noting the biomarker may also be an Aviado id (the schema only lists name, abbreviation, or LOINC code) and by illustrating the LOINC format with '4548-4', which reduces failed lookups.

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 states a specific verb+resource (supplements that move a biomarker) and immediately scopes it to Aviado's registry-classified entities, explicitly distinguishing it from get_interventions_for_biomarker which covers drugs, research compounds and foods. An agent can route between the two siblings 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?

It gives explicit when-to-use (supplements only, registry-classified and recommendable), when-not (prescription drugs, research compounds, foods, unknown ids), the named alternative to use in that case, and even a pre-call step ('Check status first: needs_confirmation / no_match means the input did not resolve'). Nothing is left to inference.

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, yet the description adds substantial semantics beyond them: biomarker_proxy rows are hypotheses graded at most D, only recommendable supplements appear by default, null fields are omitted, dose is evidence context rather than a dosing recommendation, and partial results do not imply absence of effect. This is exactly the extra behavioral context annotations cannot carry.

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?

Purpose and ranking rule are front-loaded, and nearly every clause carries non-redundant semantics. It is, however, a dense run-on paragraph with nested parentheticals that could be broken into shorter statements without losing content.

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 carries the full burden and delivers: it names the row fields (intervention_type, entity_type, regulatory_status, recommendable, coverage.row_defaults), the dose shape {value, unit}, the evidence_basis categories, and the error/confirmation envelope. An agent has everything needed to call and interpret it.

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 real meaning: include_non_supplements is described as surfacing labelled prescription drugs and research compounds 'as context only', and condition resolution behavior (ambiguous input -> needs_confirmation with candidate ids) is documented beyond the schema's simple string definition.

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 ('Supplements associated with a health condition or goal') plus the ranking rule ('strongest evidence first') and the evidence_basis split that separates direct rows from biomarker_proxy rows. This lets an agent distinguish it from the sibling get_supplements_for_biomarker 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 clear operational context: check status first, needs_confirmation/no_match means the input did not resolve and next_step tells you how to retry, and confirm a candidate condition then pass its id. It also explains when to set include_non_supplements. It stops short of naming sibling alternatives (e.g. search_conditions) explicitly, so it is clear context rather than a full when/when-not routing guide.

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 still adds substantial behavioral context: retired catalog products are excluded, price/retailer/product_url come from scraped listings and may be missing or stale, and unresolved inputs return null data with a next_step. This is exactly the value-add beyond structured fields.

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-loads the core purpose then moves into field semantics; dense but essentially every sentence carries needed information given there is no output schema. Slightly run-on with multiple clauses packed into single sentences, but not 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?

No output schema exists, so the description takes on the burden of explaining the returned fields (proofmark_100, proofmark_status states, match_basis, price/retailer staleness) and the error path, and it does so thoroughly for a 2-parameter 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% (baseline 3), and the description still extends the schema by clarifying that 'supplement' accepts either a plain name or an Aviado canonical_id, which the schema only calls 'Supplement name'. That extra accepted-input semantics justifies a 4.

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?

Opens with a specific verb+resource ('Highest-quality brands for a supplement'), states the dedup rule (one product per brand, its best) and the ranking basis (ProofMark). An agent can distinguish this from search_supplements or get_supplement_info 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?

Explains when to prefer this and how to feed it ('supplement may be a name or an Aviado canonical_id (from search_supplements or a candidates list)') and gives a conditional workflow ('Check status first: needs_confirmation / no_match means the input did not resolve... next_step says how to retry'). It does not explicitly name a competing sibling for the same task, so no explicit when-not.

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, and destructiveHint, but the description adds substantial behavioral detail: the response shape for clear matches (data.conditions first, up to 4 suggestions) and for ambiguous queries (needs_confirmation with candidates). It also prescribes how to resolve ambiguity, which is valuable beyond the structured safety hints.

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 description is three sentences, front-loads the purpose, then efficiently covers two response modes and the follow-up action. Every sentence adds distinct information without redundancy.

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 compensates by explaining the two possible return shapes and the ambiguity-resolution workflow. Combined with the annotations covering safety, this is sufficient for an agent to invoke and handle the tool correctly.

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 query parameter already has a descriptive example list. The description adds that the query can also be a symptom or goal, which is a minor semantic expansion over the schema, so the baseline of 3 is appropriate.

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 states a specific verb and resource: 'Find the condition id for a health condition, symptom or goal.' This clearly distinguishes it from sibling tools like get_supplements_for_condition or search_supplements, and an agent can identify its role without opening the 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?

The description gives clear usage context: it explains that clear matches return data.conditions and ambiguous names return needs_confirmation, and it directs the agent to pass the resulting id to get_supplements_for_condition. It does not explicitly state when not to use this tool or name alternative search tools, so it falls short of a 5.

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 cover read-only/idempotent/openWorld, and the description goes well beyond them: exact-only matching, the three match_type outcomes (vocabulary_exact, user_intent, naming_slm_suggestion with identity=false), that family/confirm-only names return needs_confirmation with candidates, and which fields each match carries. It discloses failure and ambiguity behavior, which is exactly what an agent needs before trusting an id.

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?

Information-dense and front-loaded: the matching semantics come first, then the alternative outcomes, then the mode rule and hand-off. The parenthetical examples ('magnesium citrate' -> magnesium) earn their space, though the run of match_type tokens makes it feel packed rather than clean.

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 carries the full return-value burden and does so: matches[0] identity, match_type values, identity=false for suggestions, candidates for family names, and per-match fields (entity_type, regulatory_status, recommendable). Nothing needed to consume the response 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 real semantics: 'query' accepts salt/form names, family names, and retail product titles (not just 'identity'), and it pins down when mode must flip to supplement_retail. It does not add syntax constraints such as the 512-char limit, which the schema already carries.

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 ('find the Aviado id for a supplement name') and immediately constrains scope ('exactly, no fuzzy matching'), which distinguishes it from the get_* siblings that consume a canonical_id. An agent can tell what this tool returns (an identity, not supplement data) without opening the 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 routing rules: mode='supplement_retail' only for raw retail titles, and 'pass the confirmed canonical_id to the other supplement tools', plus the instruction to confirm naming_slm_suggestion ids with the user. It also names the situations that yield needs_confirmation. This is when/when-not guidance with the consumer tools identified.

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