Healthy Aging Atlas

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds important context: it is not a product ranking, contains no affiliate links, and must not be used for personal health information. No contradictions.

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?

Concise and well-structured: the purpose is front-loaded, followed by usage boundaries and safety instructions. Every sentence adds value.

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?

Given the annotation coverage, output schema, and simple parameter set (2 required params), the description is complete. It covers all necessary context for an AI agent to use the tool appropriately.

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 has 0% description coverage. Description mentions 'goal' and 'supplements' but does not elaborate on format or constraints. It provides enough context for understanding what the parameters are, but could be more specific.

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 clearly states it compares human-evidence strength and limitations for 2-5 supplements for a goal, distinguishing it from product rankings. It uses specific verb 'compare' and resource '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?

Explicitly states when to use (evidence comparison) and when not (personal health info), directs to a qualified healthcare professional for personal queries, and clarifies no affiliate links.

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 indicate read-only, non-destructive, idempotent, and closed-world behavior. The description adds valuable context beyond this: it discloses that the tool returns 'affiliate purchase links' (commercial aspect), 'safety notes' (risk information), and 'evidence quality' (methodological transparency), which aren't covered by 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 the core purpose in the first clause, followed by a concise list of return components. Every sentence earns its place by specifying output details without redundancy. It's appropriately sized for a tool with clear functionality.

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?

Given the tool's moderate complexity (comparison with multiple output aspects), no output schema, and rich annotations, the description is mostly complete. It details the return components (differences, evidence, use cases, safety, verdict, links), but could benefit from mentioning format or limitations (e.g., supplement database scope).

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%, fully documenting both required parameters with examples. The description doesn't add any parameter-specific information beyond what the schema provides (e.g., no additional constraints or usage tips for the slugs). Baseline 3 is appropriate when schema does the heavy lifting.

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 clearly states the specific action ('head-to-head comparison') and resource ('two supplements'), distinguishing it from siblings like get_product (single product info) or search_supplements (multi-product search). It specifies the comparative nature with 'key differences' and 'verdict' outputs.

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 implies usage context by stating it's for 'head-to-head comparison' of two supplements, suggesting when to use it (for direct comparison). However, it doesn't explicitly state when not to use it or name alternatives like get_product for single supplement details or recommend_for_goal for goal-based recommendations.

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 indicate readOnly, idempotent, and non-destructive behavior. The description adds important behavioral details: citations are verified, mismatched ones are counted and withheld, claim prose is never emitted without verification, and no affiliate links. This goes beyond 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 a single paragraph that delivers all necessary information without excessive verbosity. However, the first sentence is somewhat long and could be split for readability. Still, it's appropriately sized for the tool's complexity.

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?

The description covers usage constraints and behavioral details well, but lacks parameter guidance. Given that there are 6 parameters (2 required, 4 optional) with 0% schema description coverage, the description should explain the purpose and constraints of parameters like limit, year range, and study_type. The presence of an output schema somewhat compensates for missing return value explanations, but parameter semantics are incomplete.

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 0%, so the description must explain parameters. However, it does not describe any of the six parameters (supplement, goal, limit, year_from, year_to, study_type) beyond their names. The enum for study_type is self-documenting, but the absence of parameter descriptions is a significant gap.

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 clearly states the tool returns only PubMed-cache-verified citations for a supplement-goal record, with additional context about filtering and withholding. It distinguishes itself from sibling tools by specifying it's for public non-personal evidence questions only, which differentiates it from tools that might handle personal data.

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 states when to use (public, non-personal evidence questions) and when not to use (personal/sensitive health information), and provides an alternative action for the user (direct to healthcare professional). This is excellent guidance for tool selection.

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?

Description confirms annotations (readOnlyHint, idempotentHint, destructiveHint) by stating it returns a summary without creating or modifying data. Adds value beyond annotations by noting no affiliate links, inclusion of safety flags, and that it returns exactly one summary per pair.

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?

Description is three sentences, front-loaded with purpose. Each sentence adds value: purpose/contents, affiliate disclaimer, usage restrictions. Slightly verbose but efficient.

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 only 2 string parameters, annotations covering safety, and an output schema present, the description fully covers what the tool does, what it returns, and when to use it. No missing critical information.

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 0%, but the description clarifies parameters by stating 'supplement-goal pair' and implying goal is the health objective. For simple string parameters with no enums, this is sufficient guidance, though examples or format hints would improve clarity.

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 clearly states the tool returns a single, source-accurate HAA summary for a supplement-goal pair, listing specific contents like evidence boundary, limitations, safety flags, and canonical source. It distinguishes itself from siblings by specifying it's only for public, non-personal evidence questions.

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 states when to use (public, non-personal evidence questions) and when not to use (personal/sensitive health information). Provides clear alternative action: tell the user not to submit such info and direct them to a healthcare professional.

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 this as a read-only, non-destructive, idempotent, and closed-world operation. The description adds valuable context beyond annotations by specifying what data is retrieved ('current price, historical observations, and price trend') and the resource type ('supplement product'), which helps the agent understand the scope and output structure. 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 the core purpose in the first sentence and efficiently lists key data points in the second. Every sentence adds value without redundancy, making it appropriately sized and easy to parse for an AI agent.

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?

Given the tool's low complexity (1 parameter), rich annotations covering safety and behavior, and no output schema, the description is reasonably complete. It specifies the data returned and resource type, though it could benefit from mentioning limitations (e.g., date ranges for history) or output format details to achieve a perfect score.

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%, with the single parameter 'product_id' fully documented in the schema. The description doesn't add any parameter-specific details beyond what the schema provides (e.g., no examples of product IDs or clarification on 'partial product name'). Baseline score of 3 is appropriate since the schema carries the full burden.

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 clearly states the tool's purpose with specific verbs ('Retrieve', 'Shows') and resources ('price history and freshness data for a supplement product'). It distinguishes from siblings by focusing on price history rather than comparison, product details, recommendations, or search. However, it doesn't explicitly differentiate from 'get_product' which might also include price data, making it a 4 rather than 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?

The description implies usage when price history is needed for a supplement product, but provides no explicit guidance on when to use this tool versus alternatives like 'get_product' (which might include current price) or 'compare_supplements' (which could involve price comparisons). There's no mention of prerequisites or exclusions, leaving usage context somewhat vague.

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 provide key behavioral hints (read-only, non-destructive, idempotent, closed-world), so the bar is lower. The description adds valuable context by specifying the types of data returned (e.g., trust score, certifications, evidence summary), which helps the agent understand the output structure and richness beyond what annotations cover, though it doesn't detail rate limits or auth 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?

The description is a single, well-structured sentence that efficiently lists all key data fields without redundancy. It is front-loaded with the main action and resource, and every element (ingredient profile, trust score, etc.) adds specific value, making it highly concise and zero-waste.

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?

Given the tool's low complexity (1 parameter, no output schema), rich annotations, and high schema coverage, the description is largely complete. It provides clear purpose and output details, though it could slightly improve by mentioning when to use versus siblings. The absence of an output schema is mitigated by the detailed description of return data.

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%, with the parameter 'product_id' fully documented in the schema. The description does not add any additional meaning or syntax details beyond what the schema provides (e.g., it doesn't clarify 'brand-name slug' further). Baseline 3 is appropriate as the schema carries the full burden of parameter documentation.

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 clearly states the specific action ('Retrieve detailed data') and resource ('specific supplement product'), listing concrete data fields like ingredient profile, trust score, certifications, pricing, and evidence summary. It distinguishes from siblings like 'search_supplements' (which likely returns multiple products) and 'compare_supplements' (which involves multiple products), making the purpose highly specific and differentiated.

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 implies usage for retrieving detailed data on a single product, but does not explicitly state when to use this tool versus alternatives like 'search_supplements' (for broader searches) or 'get_price_history' (for historical data). It provides context (e.g., 'specific supplement product') but lacks explicit guidance on exclusions or named alternatives, leaving some ambiguity for the agent.

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=true, idempotentHint=true, destructiveHint=false. Description adds 'Contains no affiliate links' which is an extra behavioral trait. No contradictions. Additional context about return fields adds transparency beyond 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?

Description is reasonably concise, front-loading the main purpose. However, the sentence 'Contains no affiliate links' is somewhat extraneous for an AI agent. Overall well-structured and to the point.

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 6 parameters and an output schema, the description covers high-level purpose and usage restrictions but lacks parameter semantics. Return values are mentioned briefly but should be detailed in output schema. Fills some gaps but not all.

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 0%, and the description does not explain any of the 6 parameters (goal, limit, cluster, supplement, evidence_strength, minimum_rct_count). Description focuses on output rather than how to use inputs, failing to compensate for low schema coverage.

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?

Clearly states it queries the DOI-backed HAA Supplement Evidence Density Map 2026 and returns dataset version, denominator, methods, canonical citation, and filtered rows. Distinguishes from siblings like search_evidence by specifying the unique resource.

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 states when to use (public, non-personal evidence questions) and when not to use (personal/sensitive health information), and instructs agent to redirect users to a healthcare professional for inappropriate requests. Provides clear boundaries.

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 indicate this is a read-only, non-destructive, idempotent operation with a closed-world scope, covering safety and reliability. The description adds valuable context by specifying that recommendations are 'evidence-ranked' and include a 'why' explanation, which clarifies the ranking methodology and output format beyond what annotations provide, though it doesn't detail rate limits or authentication 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?

The description is a single, well-structured sentence that front-loads the core purpose ('Get evidence-ranked supplement recommendations for a specific health goal') and efficiently adds key details about filters and output. Every word earns its place with no redundancy or waste, making it highly concise and easy to parse.

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?

Given the tool's moderate complexity (4 parameters, 1 required), rich annotations (covering read-only, non-destructive, etc.), and 100% schema coverage, the description is largely complete. It adds context on evidence-ranking and output explanation, but without an output schema, it could benefit from more detail on the return structure (e.g., product fields). However, it adequately supports agent usage for the core functionality.

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 schema fully documents all parameters (goal, limit, budget_usd, demographic). The description adds minimal semantics by mentioning 'optional budget and demographic filters' and the output format, but it doesn't provide additional meaning beyond the schema's detailed descriptions (e.g., goal slug examples, limit range, demographic enum values). This meets the baseline for high schema coverage.

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 clearly states the specific action ('Get evidence-ranked supplement recommendations') and resource ('for a specific health goal'), distinguishing it from siblings like compare_supplements or search_supplements by focusing on goal-based ranking rather than comparison or general search. It explicitly mentions the output format ('top products with a "why" explanation'), which further clarifies its unique purpose.

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 implies usage by specifying 'for a specific health goal' and mentions optional filters, but it does not explicitly state when to use this tool versus alternatives like compare_supplements or search_supplements. No guidance is provided on prerequisites, exclusions, or comparative contexts, leaving the agent to infer usage from the purpose alone.

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. The description adds 'Contains no affiliate links or purchase recommendations', which provides minor behavioral context. It does not contradict 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 concise with 5 sentences, front-loading the core function and return data. The note about affiliate links could be considered extraneous but does not detract significantly. Efficiently structured.

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?

Given an output schema exists (as per context signals), the description adequately covers return fields (evidence grades, study counts, etc.) and usage restrictions. For a search tool with 7 optional parameters, the description provides sufficient contextual completeness without overburdening.

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 only 43%, with 3 of 7 parameters having descriptions in the schema. The tool description does not add meaning for the undocumented parameters (limit, year_to, year_from, study_type). It merely lists parameter names implicitly through the return data context, which is insufficient.

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 specifies the verb 'search', the resource 'published HAA supplement-goal evidence records', and lists the return data (evidence grades, study counts, etc.). It clearly distinguishes the tool's purpose from siblings like compare_evidence or get_evidence_summary.

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 states when to use ('public, non-personal evidence questions') and when not to use (personal or sensitive health information), and provides guidance to direct users to a healthcare professional. No mention of alternative sibling tools but the restriction is clear.

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 this as read-only, non-destructive, idempotent, and closed-world, which the description doesn't contradict. The description adds valuable behavioral context beyond annotations by specifying that results are 'ranked' with 'trust scores, prices, and affiliate-tagged purchase links,' which helps the agent understand the return format and commercial aspects not covered by 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 a single, well-structured sentence that efficiently communicates purpose, search dimensions, and return format. Every element earns its place with no wasted words, making it easy to parse and front-loaded with key 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 search tool with rich annotations and full schema coverage but no output schema, the description provides good context on purpose, usage, and return format. However, it could be more complete by explicitly mentioning the ranking algorithm or result limitations, though the annotations and schema cover most safety and parameter aspects adequately.

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?

With 100% schema description coverage, the schema fully documents all 4 parameters. The description mentions search criteria ('name, ingredient, or health benefit') which aligns with the 'query' parameter but doesn't add significant meaning beyond what the schema provides. The baseline of 3 is appropriate when the schema does the heavy lifting.

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 clearly states the action ('Search for supplements') and resource ('supplements'), specifies search criteria ('by name, ingredient, or health benefit'), and distinguishes from siblings by focusing on broad search rather than comparison, price history, single product retrieval, or goal-based recommendation.

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 implies usage for general supplement discovery with multiple search dimensions, but doesn't explicitly state when to choose this over alternatives like 'recommend_for_goal' for targeted recommendations or 'get_product' for specific product details. The context is clear but lacks explicit exclusions or named alternatives.

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