Clarity by Health AI

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

With no annotations, the description carries full burden. It mentions 'condition-aware database' and return values, but does not disclose read-only nature, side effects, or error handling. Does not contradict annotations as none exist.

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 with clear front-loading of purpose. Every word adds value, no redundancy. Efficient 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?

Given the simplicity (2 params, no output schema), the description covers most needed context: what it does, what it returns (verdict, evidence tier, citation). It lacks explicit mention of error states or missing ingredients, but is largely complete for a lookup 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 100%, with each parameter having a description. The description adds context about return values tied to the lens parameter but does not provide new meaning beyond schema. Baseline 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 clearly states the verb 'Look up' and the resource 'ingredient', specifying the database type and the return values. It distinguishes from sibling tools like check_interaction and scan_barcode by focusing on ingredient lookup with condition context.

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 ingredient lookup with condition lens but does not explicitly state when to use versus alternatives like check_interaction or score_product. No exclusion criteria or alternative hints are 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?

No annotations provided, but description thoroughly explains return fields (interaction_type, severity, etc.), behavior (queries both directions), and limitations (curated set, not medical advice). Covers behavioral traits comprehensively.

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?

Single paragraph, well-organized with purpose, usage, return info, and caveats. Could be slightly more concise but still effective.

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 annotations and no output schema, description provides all necessary context: what tool does, how to use, what it returns, and important caveats. No missing information for this type of 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 covers 100% of parameters with descriptions, but description adds usage examples and explains the difference between providing one vs. two ingredients, which adds value beyond 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?

Explicitly states it checks a curated ingredient-to-ingredient interaction database. Differentiates from siblings like check_ingredient by focusing on interactions between ingredients.

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 clear guidance on using one ingredient for a full list or two for a specific pair. Includes caveats about absence of results not implying safety and that it's not medical advice, but doesn't explicitly mention when not to use.

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 provided, the description carries full burden. It discloses reliance on external sources (Open Food Facts, Clarity, FDA), mentions flagging FDA recalls with a source_url for verification, and indicates conditional output based on the lens parameter. It does not discuss destructive actions or side effects, which is acceptable for a read-like lookup.

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, dense sentence that front-loads the primary action 'Look up a product by barcode' and then lists additional outputs. It is efficient but could be improved by splitting into two sentences for readability.

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?

Despite no output schema, the description lists key return components: flagged ingredients for condition lens, recall_flag, recalls[], and source_url. It covers the main outputs but lacks detail on the structure of ingredient matches or product details.

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 already present for both parameters (barcode and lens). The description adds context by tying lens to 'condition lens' and explaining that it filters flagged ingredients, but this is incremental 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 clearly states multiple specific actions: looking up a product by barcode, matching ingredients against Clarity's database, flagging ingredients for a condition lens, and flagging FDA recalls. It distinguishes itself from sibling tools like check_ingredient and check_interaction by focusing on barcode-based lookup with comprehensive 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 for barcode-based product lookups, differentiating from siblings that handle ingredients (check_ingredient), interactions (check_interaction), scoring (score_product), strains (strain_lookup), or claims (validate_claim). However, it does not explicitly state when not to use it or provide alternative 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?

No annotations provided; description fully carries behavioral transparency. It discloses that scores are category-specific, never merged, include per-lens fit, and always provide data_quality/coverage. It also explains scoring logic for supplements.

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 moderately concise; front-loaded with main purpose, then provides detailed examples. Slightly verbose in listing category scores but overall 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?

Given no output schema, description adequately explains return structure (category scores, per-lens fit, data quality/coverage). Could be more explicit about response format but is sufficient for agent understanding.

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 baseline is 3. Description adds context about output behavior tied to category and lens parameters (e.g., what scores each category returns) but does not elaborate on parameter syntax or constraints beyond 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 retrieves Clarity's product quality score by barcode, with detailed category-specific breakdowns. It distinguishes from siblings like check_ingredient or validate_claim 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?

The description implies usage for obtaining product scores but does not explicitly state when to use this tool versus alternatives or list exclusions. Context from sibling names helps but lacks direct 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?

No annotations are provided, so the description carries the full burden. It discloses the return values (verdict, evidence tier, PMID citation, safety flags), which is helpful. However, it does not mention whether the operation is read-only, if it requires special permissions, or any limitations such as case sensitivity or exact match requirements.

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 sentence that front-loads the action ('Look up') and includes all essential information without any wasted words. It is efficient and clearly 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 the low complexity (single parameter, no output schema, no annotations), the description is adequate but not fully complete. It specifies the output fields but does not clarify if the lookup returns multiple results, if exact match is required, or what happens when no result is found. More context would be beneficial for an AI agent.

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 input schema has 1 parameter (species) with a description covering 100% of schema coverage. The tool description adds no additional semantics beyond what is already in the schema; it only restates 'cannabis or mushroom species/strain'. With high schema coverage, baseline is 3, and the description provides no extra 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 uses the specific verb 'Look up' and clearly identifies the resource as 'cannabis or mushroom species/strain in Clarity's database'. It distinguishes from sibling tools (e.g., check_ingredient, check_interaction) by focusing on species/strain lookup, which is a distinct operation.

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 vs alternatives. The description states what it does but does not specify when to choose it over sibling tools like check_ingredient or validate_claim. Usage context must be inferred from the tool name and 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?

Discloses non-medical-advice nature and return categories, but no annotations exist to provide further context. Lacks information on authentication, rate limits, or error handling, though the simple read operation may not require extensive disclosure.

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, two-sentence description that front-loads the main action and includes an example. No wasted words.

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?

Describes output categories despite no output schema, fitting for a two-parameter tool. Could mention edge cases (e.g., ambiguous statements) but overall 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 examples (e.g., 'fenugreek is safe while breastfeeding') that clarify usage beyond the schema descriptions. Since schema coverage is 100%, baseline is 3; the example adds practical 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?

Clearly states it fact-checks health/safety claims against a curated database, with examples and expected outputs (supports/contradicts/does-not-cover). Distinct from siblings which focus on ingredients, interactions, or barcode scanning.

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?

Describes when to use ('check whether a health claim an agent already holds aligns with curation'), but does not explicitly exclude alternative tools or list conditions for avoidance.

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