Server Quality Checklist

Tool Scores

• list_categoriesA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate read-only and non-destructive behavior. The description adds context by stating it is lightweight and safe, and details the return structure, which goes beyond annotations.

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

  Conciseness5/5

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

  The description is concise with a clear first sentence, followed by usage guidance, return format, and coverage. No redundant sentences.

  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?

  Given no output schema, the description adequately covers the return format and specific categories covered. Could include more detail on the 'note' and 'cta' fields, but overall sufficient for a parameterless tool.

  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?

  With zero parameters, baseline is 4. The description adds value by listing the categories covered (Grocery & Gourmet Food, etc.) and describing the return object structure, compensating for the lack of parameters.

  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 lists Amazon CPG categories with product counts and trend direction, using a specific verb and resource. It distinguishes itself from sibling tools by positioning as the first call in a pricing-analysis workflow.

  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 to use as the first call before category-specific queries and notes it is lightweight and safe. Could be improved by mentioning when not to use, but the context of siblings makes it clear.

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

• get_price_positionA
  4.6/5.0
  Behavior4/5

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

  Annotations already indicate read-only and non-destructive behavior. The description adds value by detailing the return fields (percentile_rank, price_index_label, position, category, last_refreshed, cta) and constraints (price must be >0 and <=10000). No contradictions 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.

  Conciseness5/5

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

  The description is well-structured with a clear purpose statement, bullet-point return values, and parameter explanations. It is concise, front-loaded, and every sentence adds value.

  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 required params, no enums, no output schema), the description covers all necessary aspects: purpose, usage context, parameter constraints, and return values. No gaps.

  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?

  The input schema has no descriptions (0% coverage), but the description compensates by providing clear explanations for both parameters: price format and range, category exact names and case-insensitivity, and a recommendation to use list_categories. This fully compensates for the schema gap.

  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 function: 'Percentile-rank a single product price against tracked Amazon competitors in a CPG category.' It provides specific use cases (e.g., checking if a $4.99 granola is competitively positioned) and distinguishes it from sibling tools like compare_products and list_categories.

  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 gives explicit guidance on when to use this tool ('Use when a multi-channel CPG brand asks where their Amazon listing price sits...') and suggests calling list_categories first to confirm category names. However, it does not explicitly state when not to use it or mention alternatives like compare_products.

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

• compare_productsA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the description's mention of comparisons and returns is consistent. It adds value by detailing the return structure and typical use cases. However, it does not explicitly state that no data is modified, but the annotations already cover that. 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 well-structured: purpose first, then use cases, then return fields, then args. It is slightly verbose with multiple example scenarios, but each sentence adds value. Could be tightened slightly but still effective.

  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 no output schema, the description lists all return fields. Input is fully described with constraints and examples. Usage context is thorough. The tool is self-contained and leaves little ambiguity.

  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 0%, yet the description fully defines the 'products' parameter as a list of objects with 'name' and 'price' (number in dollars), including constraints (min 1, useful 3-20). The 'category' parameter is explained with case-insensitivity and example values. This compensates entirely for the lack of schema property descriptions.

  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 'compare' and targets a clear resource: 'multiple product prices against an Amazon CPG category's peers'. It explicitly distinguishes from sibling tools like 'get_price_position' (single product) by framing the multi-product comparison use case.

  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?

  The description provides explicit when-to-use scenarios (e.g., stack-ranking SKUs, flagging underpriced products, building price-audit tables) and indicates a useful range of 3-20 items. It implies alternatives for single-product queries, providing clear guidance.

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

• get_category_overviewA
  4.7/5.0
  Behavior4/5

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

  Annotations already indicate readOnly=true, so no destructive concern. The description adds detail on return fields (product_count bucketed, price_tiers with dollar bands) and notes case-insensitivity, but does not address error handling or latency.

  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 well-structured with a clear first line, bullet points for returns, and an Args section. No redundancy; 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?

  Given only one parameter and no output schema, the description covers purpose, usage, return fields, and parameter constraints. Lacks details on error cases or data freshness guarantees, but sufficient for most agents.

  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?

  With 0% schema coverage, the description fully documents the single parameter: it lists allowed enum-like values and states case-insensitivity, adding critical meaning beyond the schema's minimal type and title.

  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 pricing-tier breakdown and category stats for an Amazon CPG category, with specific return fields listed. It distinguishes from siblings like get_category_trend and compare_products by focusing on overview and tier analysis.

  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?

  Explicit use cases are provided (sizing up a shelf, evaluating entry tiers, benchmarking), and it mentions exact allowed category values. It implicitly suggests when not to use (for product-level comparison) by contrasting with sibling tools.

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

• get_category_trendA
  4.7/5.0
  Behavior4/5

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

  Annotations already indicate read-only and non-destructive. Description adds return fields (trend_direction, confidence with product count, etc.) and notes case-insensitivity. No contradictions; the added context is valuable but not exhaustive.

  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?

  Description is well-structured with sections for purpose, usage, returns, and args. Around 150 words, front-loaded with purpose. Could be trimmed slightly but efficiently conveys necessary 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?

  For a simple tool with one parameter and no output schema, the description covers purpose, usage, parameter constraints, and return fields. No gaps given complexity.

  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 has no enum or description (0% coverage). Description compensates by listing exact allowed category names and stating case-insensitivity. This is critical for correct invocation.

  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?

  Description clearly states the tool reports 30-day Amazon price-trend direction for a CPG category. It uses specific verb 'Report' and distinguishes from siblings like get_category_overview and get_price_position by focusing on trend direction.

  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 when-to-use scenarios (e.g., pricing ops lead asking trend, setting promo calendar, deciding wholesale prices, catching price war). Examples give clear context, though it does not mention when not to use; the vivid use cases fully suffice.

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

• server_statusA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations (readOnlyHint, destructiveHint), the description adds the staleness threshold (10 days), degraded reason behavior, and specific return fields. This fully discloses operational 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?

  Description is concise, front-loads purpose and usage, then lists return fields. Every sentence adds value; 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 no parameters and no output schema, the description fully explains all return fields with types and conditions. It is complete for this low-complexity tool.

  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?

  Input schema has no parameters (0 params, 100% schema coverage). Baseline of 4 is appropriate since description has no need to explain parameters.

  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 server health, data freshness, and degraded-state reason. It distinguishes from siblings like compare_products and get_category_overview by focusing on server status rather than product or category data.

  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 explicitly advises using this tool to verify category seeding currency before trusting downstream tools, providing clear context. It lacks explicit when-not-to-use but the guidance is sufficient.

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