Clarity by Health AI

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

No annotations are provided, so description bears full burden. It discloses returns and condition-awareness but omits limitations, error behavior, or read-only nature. Some behavioral context is added but not comprehensive.

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 sentences, front-loaded with purpose and returns. Every sentence adds value with no redundancy. Highly concise and well-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?

With 2 parameters, no output schema, and no annotations, the description provides adequate but not complete context. Lacks details on condition lens interpretation, search behavior, or response structure. Could be more thorough.

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 baseline is 3. The description adds little beyond the schema—only restating 'condition lens' and providing an example similar to the schema's description. No additional semantic value.

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 'look up', the resource 'ingredient', and the context 'condition-aware database'. It also specifies return values (verdict, evidence tier, citation), distinguishing it from siblings like check_interaction or scan_barcode.

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 checking an ingredient under a condition lens but does not explicitly state when to use vs. alternatives, or provide exclusions. Usage is implied by the tool name and 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?

With no annotations, the description fully carries the burden. It discloses the database is curated/growing, queries both directions, returns specific fields, and is not medical advice. No behavioral 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?

The description is concise with no wasted words, front-loaded with purpose, then usage, output details, and caveats. 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 no output schema, the description lists all return fields and explains the tool's limitations. It provides complete context for an interaction checking 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% with descriptions for both parameters. The description adds value by explaining the semantic difference between providing one vs. two ingredients, which is not fully captured in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks a curated ingredient-to-ingredient interaction database, with specific usage for one or two ingredients. It distinguishes itself from sibling tools like 'check_ingredient' by focusing on interactions.

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 explains when to use the tool with one or two ingredients and includes a caveat about absence of results not proving safety. It does not explicitly contrast with sibling tools or state when not to use, but context 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?

No annotations are provided, so the description carries the full burden. It discloses the tool's multi-step behavior, data sources (Open Food Facts, Open Beauty Facts, FDA), and return elements (recall_flag, recalls[], source_url). However, it does not mention whether it is read-only or any required permissions.

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, grammatically dense sentence that efficiently conveys multiple actions and outputs. While it is comprehensive, splitting into shorter sentences could improve readability slightly.

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 complexity (multiple lookups, external APIs, recall flagging), the description is thorough. It mentions key output elements (recall_flag, recalls array, source_url) even without an output schema, though it does not detail the full structure of ingredient matches.

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 includes descriptions for both parameters. The description adds context by explaining how the 'lens' parameter is used to flag ingredients for a condition, and confirms 'barcode' format (UPC/EAN, 6-14 digits), adding value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool looks up a product by barcode, matches ingredients, flags ingredients based on condition lens, and checks for FDA recalls. It clearly distinguishes from siblings like 'check_ingredient' and 'check_interaction' by encompassing multiple steps.

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 a barcode is available and full product analysis with recall check is needed. It does not explicitly state when not to use or suggest alternatives, but the context of sibling tools provides indirect 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?

Discloses category-specific scoring, non-merging of scores, per-lens fit, and data_quality/coverage. With no annotations, this provides good behavioral insight, though no mention of auth or rate limits.

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 purpose, then details scope and constraints. Slightly verbose but every sentence adds value, with clear structure.

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?

Covers return value behavior (data_quality/coverage, per-lens fit) despite no output schema. Parameters well explained; tool complexity moderate and description adequate.

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?

Adds significant meaning beyond the input schema by detailing category-specific sub-scores and explaining the lens parameter purpose. Schema coverage is 100%, but description enriches understanding.

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 the tool gets a product quality score by barcode, with specific verb and resource. Distinguishes from siblings like check_ingredient and scan_barcode by focusing on scoring.

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?

Implies usage for obtaining quality scores, but lacks explicit when-to-use or alternatives. The sibling list provides context but no direct guidance in the description.

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?

No annotations are provided, so the description must carry the burden. It discloses that the tool returns verdict, evidence tier, PMID citation, and safety flags, but does not mention whether it is read-only, required permissions, or other behavioral traits.

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 two sentences: the first states the purpose and the second lists return values. It is well-front-loaded, but could include more context without being verbose.

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 should explain the return values in more depth. It mentions 'verdict, evidence tier, PMID citation, and safety flags' but does not define these terms or address edge cases like partial matches or case sensitivity. The tool is simple, but the description feels 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?

The schema covers 100% of parameters with clear description (e.g., 'Species or strain name, e.g. ‘Cannabis sativa’ or ‘Lion’s Mane’'). The tool description adds no additional meaning beyond what the schema provides, so baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Look up a cannabis or mushroom species/strain') and the resource (Clarity's database). It effectively differentiates from sibling tools like check_ingredient or check_interaction, which serve different purposes.

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 lacks any guidance on when or when not to use this tool versus alternatives. No explicit context about prerequisites or conditions for use is provided.

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?

Without annotations, the description carries full burden. It discloses that the tool returns a position (supports/contradicts/does-not-cover) plus a citation, and notes it is 'Descriptive — not medical advice.' This is adequate for a read-only lookup tool.

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

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

Three well-structured sentences. The main purpose is front-loaded, an example is given, and behavioral notes are included. No fluff.

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 no output schema, the description explains the return value well. It covers purpose, parameters, and behavior. Missing error conditions, but overall complete for an agent to use.

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% (both parameters described). The description adds an example ('fenugreek is safe while breastfeeding') and explains the role of the lens parameter, providing context beyond the schema's 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?

The description clearly states the tool's action ('fact-check'), the resource ('Clarity's human-curated, evidence-graded database'), and the output (supports/contradicts/does-not-cover with citation). It distinguishes from sibling tools by focusing on free-text claims against a curated database, unlike specific ingredient checks or product scoring.

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 tells when to use the tool ('to check whether a health claim an agent already holds aligns with Clarity's curation') and gives an example context. It does not explicitly state when not to use it, but the purpose is clear enough. Sibling tools are listed but not compared, so a 4 is appropriate.

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