Aviado AI

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 declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description does add real value beyond that: it enumerates the returned verdict fields, the coverage scale (none/sparse/moderate/broad), and the found:false and needs_confirmation semantics. However, it doesn't cover pagination, rate limits, or response latency, so the extra context is useful but not exhaustive.

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 essential scoping rule is front-loaded, but the middle is a dense run-on that crams coverage rules, return fields, and caveats into one sentence. Every clause earns its place content-wise, yet the lack of structure makes it harder to scan than it should 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?

With no output schema, the description carries the burden of explaining return values and does so by naming the verdict fields and coverage levels. It also covers the failure statuses and the retry path. The main remaining gap is that it doesn't say what the sources array contains or whether evidence_level values are enumerated.

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 already 100%, so baseline is 3. The description adds genuine semantics the schema lacks: salt forms are merged, brand names are not matched, canonical_id is accepted, and supplements vs medications resolve differently. This is meaningful input guidance beyond the two terse property descriptions.

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 action and scope: a point check of ONE pair, with explicit resolution rules for each argument (supplement name/canonical id vs generic medication name). The phrase 'Point check of one pair' implicitly separates it from the bulk-oriented sibling get_supplement_interactions, and the per-combination coverage rules make the tool's boundary unmistakable.

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 conditions (single pair, 1-3 KB) and when-not (two medications are not covered and return no_match). It also prescribes agent behavior: check status first, and treat found:false as not a safety answer by reading coverage.note. This is unusually actionable routing guidance for both the agent and its downstream phrasing.

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?

Annotations already establish read-only, idempotent, and non-destructive behavior, but the description adds substantive traits: empty results are not proof of safety, coverage.drug must be read, data-source failures return errors rather than empty lists, label_artifact_suspected flags salt-form artifacts, and status codes indicate unresolved input. No contradiction with annotations.

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 front-loaded with caveats and appropriately sized for a complex tool, but it is a single dense paragraph that repeats the empty-result-is-not-safety warning and could be tighter. Most other sentences carry operational detail.

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 supplies return-value semantics such as interaction_sources, recorded_for, drug_page.total/next_offset, label_artifact_suspected, status, and next_step. Given annotations cover safety and the schema covers parameters, an agent has enough to call and interpret the 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 baseline is 3; the description additionally clarifies that supplement can be a name or an Aviado canonical_id and explains paging via drug_limit/drug_offset and drug_page fields. It still omits include_drug_interactions and mostly repeats drug matching rules already in the schema, so it is above baseline but not exhaustive.

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 resource and the two interaction classes, including provenance: FDA drug labels for drug interactions and Aviado verified pairs for supplement-supplement interactions. It does not explicitly contrast itself with the sibling check_interaction or state when that sibling should be used instead, so it falls short of a 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 usage conditions: pass drug to check one medication, use include_supplement_interactions to retain supplement-supplement pairs, and check status first for unresolved input. It does not state when not to use this tool or name check_interaction as an alternative.

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.