Healthy Aging Atlas

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is established. The description adds valuable context: it is not a product ranking, contains no affiliate links, and dictates the agent's behavior when sensitive data is mentioned. 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, followed by scope restrictions and safety instructions. It is somewhat lengthy but every sentence adds necessary context (purpose, exclusions, user-redirect behavior). No filler.

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 output schema exists and annotations cover mutability, the description is complete: it defines the tool's scope, exclusions, and handling of sensitive information. The agent has enough to select and invoke the tool appropriately without missing critical context.

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%, so the description must compensate. It clarifies that 'supplements' should be two to five items and that 'goal' refers to a shared goal for all supplements. However, it does not detail parameter formats, allowed values, or how supplement names should be provided, leaving room for ambiguity.

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?

Description clearly states 'Compare mapped human-evidence strength and limitations for two to five supplements for the same goal' – a specific verb, resource, and scope. It also explicitly distinguishes itself from 'product ranking or purchase recommendation', differentiating it from potential sibling tools like compare_supplements.

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 explicit when-to-use ('public, non-personal evidence questions') and when-not-to-use ('requests involving personal or sensitive health information') guidance. It also instructs the agent to redirect users to a qualified healthcare professional, making exclusions actionable.

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, non-destructive behavior. The description adds valuable context beyond annotations: 'Legacy' indicates potential deprecation or reliability concerns, and 'may include catalog and affiliate data' warns the agent that results may contain commercial/affiliate content, which is critical for interpreting outputs. This is meaningful supplementary behavioral transparency.

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 exceptionally concise, using two short sentences to convey purpose, legacy status, and a usage alternative. Every word adds value, and the key guidance is front-loaded. No redundancy or filler.

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 tool with only two simple string parameters and no output schema, the description gives a basic understanding of purpose and guidance. However, it lacks information about what the comparison returns (format, structure) and does not compensate for missing parameter descriptions. The annotations and sibling context help, but the description alone feels minimally complete rather than fully self-sufficient.

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 0% schema coverage and no parameter descriptions in the input schema, the description needed to explain what 'supplement_a' and 'supplement_b' should contain (e.g., product names, IDs, or URLs). The description only mentions 'comparison tool' and does not clarify parameter formats or constraints, relying solely on the self-explanatory parameter names, which is insufficient for unambiguous invocation.

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 explicitly states this is a 'Legacy comparison tool' that may include catalog and affiliate data, clearly identifying the tool's function (comparing supplements/products). It also distinguishes itself from the sibling tool 'compare_evidence' by noting the commerce component, making its purpose unique and clear.

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 provides explicit usage guidance: it names the alternative 'compare_evidence' for commerce-free evidence comparison, indirectly telling the user when to choose this tool (when catalog/affiliate data is acceptable or desired) and when not to. This is a clear, actionable directive that aids 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds significant behavioral context: 'Mismatched, conflicting, or unverifiable citations are counted and withheld' and 'Stored claim prose is never emitted without claim-level verification.' It also notes 'Contains no affiliate links,' which is useful trust information. This clearly exceeds what annotations alone convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is several sentences long but each sentence adds value: main function, filtering behavior, safety disclaimer, and usage restriction. It is front-loaded with the core purpose and then expands with necessary caveats, though slightly lengthy for what it covers.

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 moderately complex filtering behavior and the presence of an output schema, the description provides strong contextual coverage: scope, verification process, restrictions, and intended use. It lacks explicit parameter explanations, but the output schema compensates for return value details, making it largely complete.

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 0% schema description coverage, the description carries full responsibility for explaining parameters. However, it only hints at 'supplement-goal record' (implying supplement and goal) but does not explain limit, year_from, year_to, or study_type. This leaves the agent without meaningful guidance for these parameters.

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 function: 'Return only PubMed-cache-verified citations that pass the repository source-accuracy audit for a published supplement-goal record.' This is a specific verb+resource+scope combination that distinguishes it from siblings like search_evidence or get_evidence_summary by focusing on claim-level citations.

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 provides explicit usage restrictions: 'Use only for public, non-personal evidence questions' and explicitly forbids use for personal health information, directing users to healthcare professionals. However, it does not name specific alternative tools or explicitly contrast with siblings, 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?

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses important behavioral traits: it returns a source-accurate summary, contains no affiliate links, includes evidence boundaries and limitations, and explicitly warns about personal health data. This adds context not present in the 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 moderately sized and front-loaded with the core purpose. The additional sentences about affiliate links and health information restrictions are necessary and relevant. It is not overly verbose, though it could be slightly tightened without losing meaning.

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 output schema exists and annotations cover safety semantics, the description adequately covers the tool's purpose, the nature of the return value, and usage boundaries. It does not describe error handling or rate limits, but those are not critical for selection. The main gap is not naming sibling alternatives, but that is a usage-guidelines concern.

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%, so the description must compensate for parameter meaning. It only mentions 'supplement-goal pair,' which essentially restates the parameter names without adding examples, accepted formats, or how the values are interpreted. This is insufficient for a tool with two non-enum string parameters.

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, citable HAA summary for a supplement-goal pair, listing specific included elements (evidence boundary, limitations, safety flags, reviewer metadata, canonical source). This specific verb+resource distinguishes it from sibling tools like search_evidence or get_citations.

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 explicitly states when to use the tool (public, non-personal evidence questions) and when not to use it (personal or sensitive health information), including a list of excluded data types. However, it does not explicitly name alternative sibling tools for those excluded cases, 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 already declare read-only, idempotent, and non-destructive behavior. The description adds value by labeling the tool as 'legacy' and clarifying the data scope (retailer price observations and freshness), which is useful context beyond the 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 two sentences long and front-loads the primary purpose. Every word adds value, with no redundancy or filler.

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 (one parameter, no output schema), the description adequately conveys what data is returned (price observations and freshness) and sets expectations about its legacy and non-clinical nature. It could include more detail about response structure, but is sufficient for this simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention the 'product_id' parameter at all. The parameter name is self-explanatory, but the description fails to provide any additional meaning or format details, leaving a gap that should be compensated.

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 is a legacy commerce tool that retrieves retailer price observations and freshness, and explicitly notes it contains no clinical efficacy conclusion. This distinguishes it from sibling evidence-based tools.

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 implies use for commerce price data and explicitly warns against using it for clinical efficacy conclusions, which serves as a usage boundary. However, it does not name alternative tools or state explicit 'when to use' versus 'when not to use' instructions.

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, and destructiveHint=false, so the safety profile is covered. The description adds the 'Legacy' deprecation context and the list of returned data categories, which is useful but stops short of behavioral details like response format, pagination, or error behavior.

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?

Two short sentences front-load the legacy status and core retrieval action, followed by a useful pointer to an alternative. No filler or 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?

For a simple retrieval tool with one parameter and no output schema, the description conveys the returned data scope and points to the main alternative, while annotations cover side effects. It lacks details like response format or edge cases, but is reasonably complete for its simplicity.

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 mention product_id at all, leaving the parameter semantics entirely to the schema. Although product_id is self-explanatory and the only required parameter, the description fails to compensate for the lack of schema 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 uses the verb 'Retrieve' with a specific resource scope: product-quality, certification, price, availability, and affiliate purchase data. It clearly distinguishes itself as a commerce tool from clinical evidence tools like 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?

It provides an explicit when-not alternative: 'Use get_evidence_summary for clinical evidence.' However, it does not offer guidance for choosing between this and other commerce siblings like get_price_history or search_supplements, and 'Legacy' only weakly implies usage context.

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 mark this as read-only, idempotent, and non-destructive. The description adds meaningful context beyond those annotations: what the tool returns, that it contains no affiliate links, and a clear call-to-action for sensitive health information. This transparency is especially valuable for a health-related data tool and does not contradict any annotation.

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 purpose and output, then adds transparency and usage constraints. While it is 6 sentences, each sentence adds necessary information, and the safety warning is appropriately explicit. No filler or redundancy is present.

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 provides a clear scope and output list, and the output schema likely covers return values. However, with 6 parameters and no schema descriptions, the description does not fully compensate for the missing parameter semantics. It also does not explicitly differentiate from sibling tools like search_evidence, leaving some ambiguity about when this specific dataset map is the right choice.

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?

The schema has 6 parameters with 0% description coverage, and the tool description does not explain any of them. The only hint is 'filtered rows,' which implies parameters serve as filters but omits details on how each parameter maps to fields or how to use them. Since the description must compensate for the schema gap and does not, this dimension is under-served.

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 ('Query') and a specific resource ('DOI-backed HAA Supplement Evidence Density Map 2026'), and lists concrete return items (dataset version, denominator, methods, citation, filtered rows). This clearly distinguishes it from sibling tools like search_evidence or get_evidence_summary, which target broader or different evidence functions.

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 explicit constraints on when to use the tool: 'Use only for public, non-personal evidence questions' and explicitly lists what not to do for personal/sensitive health information. It does not name alternative tools, but the exclusions are unambiguous, and it provides user-facing guidance for out-of-scope requests.

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?

The description adds value beyond annotations by disclosing that the tool 'may contain affiliate URLs' and that rankings are not 'personalized advice'. Given readOnlyHint and idempotentHint are true and destructiveHint is false, the safety profile is already clear; the description enriches understanding of the tool's commercial nature and limitations.

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 two concise sentences with no filler. It front-loads the legacy status and core purpose, then adds key caveats. Every sentence earns its place, and the structure is easy to parse quickly.

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 tool has no output schema and 4 parameters, so the description should ideally describe return format and parameter interactions. It partially does by stating it returns 'catalog/product rankings' and mentions affiliate URLs, but it lacks details on response structure or how demographic/budget influence results. For a legacy tool with potential bias, more context would be valuable, but the core purpose is clear enough for basic invocation.

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 0% schema description coverage, the description provides no explanation of the parameters (goal, limit, budget_usd, demographic). It only mentions 'catalog/product rankings', which hints at goal-based ranking but does not elaborate on how limit, budget, or demographic affect results. The schema provides defaults and enum values, so some semantics exist, but the description fails to compensate for the coverage 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's function: 'Returns catalog/product rankings' and explicitly notes 'may contain affiliate URLs'. It distinguishes itself from sibling evidence tools by stating rankings are 'not clinical-evidence grades or personalized advice', which differentiates it from search_evidence, get_evidence_summary, and compare_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?

No explicit guidance on when to use this tool versus alternatives is provided. The word 'Legacy' implies it may be outdated, but it does not specify use cases, exclusions, or recommend another sibling tool for better options. The only hint is the 'not clinical-evidence grades' caveat, which implies not to use it for clinical decisions, but this is not practical usage guidance.

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 the tool read-only, idempotent, and non-destructive. The description adds behavioral context by stating it contains no affiliate links or purchase recommendations and that it returns 'clean canonical HAA sources', which is not captured in 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 purpose and return value, followed by use restrictions. Each sentence adds operational or safety information, though the safety section is somewhat lengthy for a simple search tool.

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 output schema exists, the description adequately covers return values and scope. It adds important usage boundaries, but the lack of parameter guidance for the optional filters makes it incomplete for a 7-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?

Only 3 of 7 parameters have schema descriptions (goal, population, supplement), and the tool description does not explain limit, year_from/year_to, or study_type. The description only hints that goal and supplement are central, but does not clarify filter semantics or how parameters interact.

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 searches published HAA supplement-goal evidence records and lists the returned fields (evidence grades, study counts, limitations, review dates, canonical sources). It distinguishes itself from siblings like search_supplements and compare_evidence by focusing on evidence records and explicitly ruling out purchase recommendations.

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 explicit guidance on when to use the tool (public, non-personal evidence questions) and when not to use it (personal or sensitive health information). It tells the user to direct personal health questions to a healthcare professional, though it does not name alternative sibling tools for non-personal scenarios.

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 the operation as read-only, idempotent, and non-destructive. The description adds valuable context by warning that 'Results may contain affiliate URLs,' which is a behavioral trait not covered by annotations. It also calls itself 'legacy,' adding useful context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no wasted words. The first sentence immediately labels it as legacy, and the second provides purpose plus an alternative. Every sentence earns its place.

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 four parameters, no output schema, and zero schema descriptions, the description is on the thin side. It gives a clear purpose and a key alternative, but the parameter semantics and return format are not addressed. The annotations cover safety, but the tool's full usage context is 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 compensate for the lack of parameter explanations. It only hints at 'query' semantics via 'by name, ingredient, or brand' but leaves 'goal,' 'limit,' and 'demographic' completely unexplained. This 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's function: 'Search catalog products by name, ingredient, or brand.' It identifies itself as a 'Legacy commerce tool' and distinguishes itself from the sibling tool 'search_evidence' by directing users there for clinical evidence, thus specifying its unique role.

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 provides explicit guidance: it names 'search_evidence' as the alternative for 'commerce-free clinical evidence,' which effectively tells the agent when not to use this tool. The label 'Legacy commerce tool' also signals its position among siblings.

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