Server Quality Checklist

Tool Scores

• scan_barcodeA
  4/5.0
  Behavior4/5

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

  No annotations exist, so the description carries full burden. It discloses sources (Open Food Facts, FDA), the matching against Clarity's database, and the recall verification via source_url. It does not explicitly state read-only nature, but the actions are clearly non-destructive. 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.

  Conciseness4/5

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

  The description is a single sentence that front-loads key actions (look up, match, return, flag). It is informative but slightly long; could be split for readability. No wasted content.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  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 returned data (flagged ingredients and recall info with source_url). However, it omits details on the format of flagged ingredients, error handling (e.g., barcode not found), and potential limitations. Adequate but not fully comprehensive.

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

  Parameters4/5

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

  Schema coverage is 100% with basic descriptions. The tool description adds context: lens is used for flagging ingredients, barcode lookup sources. This enhances understanding beyond schema, meriting a score above the baseline of 3.

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

  Purpose5/5

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

  The description specifies the tool's purpose: look up a barcode from Open Food Facts / Open Beauty Facts, match ingredients against Clarity's database, flag ingredients for a given lens, and flag FDA recalls. It clearly distinguishes from siblings like check_ingredient or check_recall by combining these actions.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  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 ingredient/recall analysis is needed, but does not explicitly state when to use it over alternatives (e.g., check_ingredient for ingredient-by-name queries). No exclusion criteria or comparative guidance is provided.

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

• check_stackA
  4.1/5.0
  Behavior4/5

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

  No annotations provided, so the description carries full burden. It discloses key behaviors: that the curated set is growing, that results include evidence-graded verdicts and interactions with type, severity, mechanism, and source. Also mentions human_url. 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.

  Conciseness4/5

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

  Two sentences, front-loaded with purpose. Some redundancy ('supplement/ingredient STACK' vs 'multiple supplements') but overall efficient. Every sentence adds value.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  No output schema, but description explains what results include (verdicts, interactions, type, severity, etc.). It also includes a safety caveat. For a complex tool with multiple inputs and outputs, the description is adequately complete.

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

  Parameters3/5

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

  Schema coverage is 100%, so baseline is 3. The description explains the tool's output (per-item verdicts, interactions) but adds little meaning to individual parameters beyond what the schema already provides. It implies the function of 'lens' and 'lenses' but doesn't elaborate on format or constraints.

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

  Purpose5/5

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

  The description uses specific verbs ('audit', 'plus') and clearly identifies the resource ('supplement/ingredient STACK'). It distinguishes from sibling tools like check_ingredient (single) and check_interaction (pairwise) by focusing on multi-ingredient stacks.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly states when to use ('when a user takes multiple supplements together'). Also warns that absence of an interaction is not proof of safety, providing critical context. Does not list alternatives or when not to use, but the purpose is clear.

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

• validate_claimA
  4.1/5.0
  Behavior3/5

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

  With no annotations, the description carries full burden for behavioral traits. It discloses the return types (supports/contradicts/does-not-cover plus citation) and adds a disclaimer ('not medical advice'). Missing information on permissions, rate limits, or any side effects, but for a read-only lookup this is minimally adequate.

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

  Conciseness5/5

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

  Three sentences, front-loaded with the core action, then an illustrative example, then usage guidance and disclaimer. Every sentence adds value with no redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description covers purpose, input semantics, and output summary completely. No obvious gaps remain.

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

  Parameters3/5

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

  Schema coverage is 100% (both parameters have descriptions). The description adds a concrete example for 'statement' and clarifies 'lens' as a condition filter, but does not significantly extend beyond what the schema already provides. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description uses a specific verb ('fact-check') and identifies the resource ('Clarity's human-curated, evidence-graded database'). It clearly distinguishes from siblings like check_ingredient or check_interaction by targeting free-text claims rather than specific entities.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The ending sentence explicitly states when to use the tool: 'check whether a health claim an agent already holds aligns with Clarity's curation.' However, it does not mention when not to use it or name alternative tools like check_ingredient for structured queries.

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

• strain_lookupA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the tool is a lookup (read-only) and lists return fields. It does not mention permissions or limitations, but for a simple lookup it is adequate.

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

  Conciseness5/5

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

  Two sentences with no redundant information. The purpose and return values are front-loaded, making it easy to parse.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple lookup with one parameter and no output schema, the description provides sufficient context about inputs and outputs. Could mention if multiple results are possible, but not critical.

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

  Parameters3/5

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

  Schema coverage is 100% for the single parameter 'species', which already includes an example. The description adds 'cannabis or mushroom' context but does not significantly enhance understanding beyond the schema.

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

  Purpose5/5

  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 in Clarity's database.' It specifies the resource (species/strain) and the return values (verdict, evidence, etc.), distinguishing it from sibling tools like 'check_ingredient' or 'validate_claim'.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies when to use: when you need to retrieve verdict and evidence for a species. However, it does not provide explicit exclusions or alternatives, though sibling tool names suggest other functionalities.

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

• check_ingredientA
  4.5/5.0
  Behavior4/5

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

  Discloses return structure (verdict, evidence tier, citation, per-lens breakdown, human_url). No annotations provided, so description carries full burden. It is transparent but could explicitly state read-only nature.

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

  Conciseness4/5

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

  Two sentences front-load the purpose. Second sentence is long but packs critical usage details. Could be slightly more concise, but no extraneous information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Fully explains what the tool returns for a lookup, including condition-aware features and human_url. No output schema exists, but description covers key outputs. Appropriate for a lookup tool with no destructive effects.

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

  Parameters5/5

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

  Adds significant meaning beyond the schema: explains difference between `lens` and `lenses`, max 5 for lenses, and the resulting per-lens breakdown. Schema descriptions are complete (100% coverage), yet the description enriches them.

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

  Purpose5/5

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

  Clearly states verb 'look up' and resource 'ingredient in Clarity's condition-aware database'. Specifies return fields and condition lens mechanism, differentiating it from siblings like scan_barcode or check_interaction by its condition-aware nature.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides clear guidance on using `lenses` array for multiple conditions vs `lens` for single, including a profile-shaped checking example. However, it does not explicitly state when to avoid this tool or mention alternatives for other ingredient queries.

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

• find_alternativesA
  4.6/5.0
  Behavior4/5

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

  No annotations provided, so description carries full burden. It discloses that the score is a general quality score (not condition verdict), returns up to 5 alternatives (though description says 2-3, slight inconsistency), and includes score, coverage, and URL. Does not mention error handling or rate limits, but for a read-only tool it is largely adequate.

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

  Conciseness5/5

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

  The description is concise (5 sentences), front-loaded with the main action. Each sentence adds essential information without redundancy. Achieves clarity efficiently.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  No output schema, so description compensates by detailing response fields (score, coverage, URL). It also provides guidance on verification. However, it lacks mention of error cases (e.g., no alternatives found). Overall fairly complete for a tool with moderate complexity.

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

  Parameters4/5

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

  Schema coverage is 100%, baseline 3. Description adds value by explaining that barcode is the preferred seed, product_name is a fallback, and clarifies the lens parameter as 'condition lens'. This enhances understanding beyond schema.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: find 2-3 safer swaps for a flagged product. It specifies the domain (food/skincare), criteria (good/excellent score, no flagged ingredient for condition), and seeding methods (barcode or product_name). It distinguishes from siblings by referencing related tools (scan_barcode, check_stack).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly states when to use: right after scan_barcode flags something, or via product_name. It notes that supplement swaps are not supported and advises verifying chosen alternatives with scan_barcode or check_stack. Provides clear context for usage.

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

• score_productA
  4.6/5.0
  Behavior5/5

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

  Given no annotations, the description fully covers behavioral traits: explains that scores are category-specific and never merged, details each category's sub-scores (e.g., food: nutrition/additive/processing/organic), describes per-lens fit, and states that data_quality/coverage is always included. This is comprehensive.

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

  Conciseness4/5

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

  The description is reasonably concise, starts with the main purpose, and adds necessary details about categories and data quality. It could be slightly shorter, but every sentence contributes useful information. It is well-structured.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Without an output schema, the description must explain return values. It does so thoroughly: category-specific scores, per-lens fit, match coverage, and data_quality/coverage. The parameter schema is complete, so the description compensates for missing output schema.

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

  Parameters4/5

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

  The input schema has 100% coverage, describing all three parameters. The description adds significant value by explaining the meaning behind the output and category-specific logic, which goes beyond the schema's parameter descriptions. It does not repeat parameter details but enriches context.

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

  Purpose5/5

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

  The description clearly states it returns a product quality score by barcode, with category-specific scores for food, skincare, and supplement. It also mentions per-lens fit with match coverage. This distinguishes it from sibling tools like strain_lookup or check_ingredient, 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.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies when to use this tool (to get a quality score by barcode) but does not explicitly state when not to use it or provide alternatives. However, the unique nature of the tool (scoring products) is clear, and the sibling list hints at other tools.

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

• check_interactionA
  4.8/5.0
  Behavior5/5

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

  No annotations are provided, so the description fully bears the burden. It discloses the return fields (interaction_type, severity, mechanism, etc.), explains that it queries both directions, and states it is descriptive with sources, not medical advice. This gives an agent a clear understanding of behavior.

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

  Conciseness5/5

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

  The description is highly concise and well-structured. It starts with the main purpose, then the two usage modes, followed by return information, and ends with important caveats. Every sentence adds value without redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Despite having no output schema, the description lists all relevant return fields and covers input, output, limitations, and authoritative disclaimers. The tool is simple, and the description provides enough detail for an agent to use it correctly and interpret results.

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

  Parameters5/5

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

  Schema coverage is 100%, and the description adds significant meaning beyond the schema. It explains the role of each parameter, provides examples (e.g., 'iron', 'calcium' + 'iron'), and clarifies the optional nature of ingredient_b with the effect of omitting it. This helps an agent craft correct invocations.

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

  Purpose5/5

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

  The description clearly states it checks Clarity's curated ingredient-to-ingredient interaction database. It specifies the two usage patterns (one ingredient to list all, two to check a pair) and distinguishes itself from sibling tools like check_ingredient or check_stack, which focus on other aspects.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explains when to use the tool (to check ingredient interactions) and how to use it (with one or two ingredients). It also provides an important caveat that absence of a result is not proof of safety. It lacks explicit when-not-to-use or direct sibling comparisons, but the examples and context suffice.

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

• check_recallA
  4.9/5.0
  Behavior5/5

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

  Without annotations, the description fully discloses behavioral traits: returns recall_flag, Class I info, records with classification/reason/date/status/source_url, and highlights data limitation (no barcode, text match). 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.

  Conciseness5/5

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

  Description is concise and well-structured: main purpose first, then details, caveats, and alternative. Every sentence adds value without redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Covers all essential aspects: scope, query parameters, return fields, data quality, verification, and alternative tool. No gaps given lack of annotations or output schema.

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

  Parameters4/5

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

  Schema coverage is 100% with both parameters documented. Description adds context: brand is primary, product_name is optional, and provides example values. This exceeds schema but is not fully novel.

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

  Purpose5/5

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

  Clearly states the tool checks for FDA/consumer recalls on consumer products (supplements, food, cosmetics) and explicitly excludes medical devices, distinguishing it from sibling tools. The verb 'check' and resource 'recall on file' are specific.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides explicit guidance: query by brand primary, optionally by product_name, and directs users to an alternative tool (radar MCP) for medical device recalls. Also advises confirming matches via source_url due to text matching.

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