Server Quality Checklist

Tool Scores

• update_productC
  2.6/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Replace the editable fields', which is ambiguous about whether it performs a full replacement or partial update, and it omits any mention of validation, side effects, or error handling.

  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, concise sentence with no wasted words. It is front-loaded and easy to read, though its brevity contributes to insufficient detail.

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

  Completeness2/5

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

  Given 5 parameters, no annotations, and the presence of an output schema, the description is too sparse. It fails to explain important context like whether the product must exist, whether fields are fully replaced, or how the update interacts with related tools, making it incomplete for reliable use.

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

  Parameters1/5

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

  The schema has zero description coverage, and the tool description does not compensate by explaining any of the 5 parameters. The term 'editable fields' is generic and does not clarify the meaning, purpose, or constraints of product_id, name, price, stock, or description.

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

  Purpose4/5

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

  The description uses a specific verb 'replace' and identifies the resource as 'existing product', which clearly distinguishes it from sibling tools like create_product and delete_product. However, 'editable fields' is vague and doesn't specify which fields are affected.

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

  Usage Guidelines2/5

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

  No guidance is given on when to use this tool versus alternatives like create_product or update alternatives. There is no mention of prerequisites, exclusions, or a clear use case beyond the implied 'modify an existing product'.

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

• create_productB
  3.3/5.0
  Behavior2/5

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

  With no annotations, the description carries the transparency burden. It discloses price/stock constraints but does not mention side effects, return behavior, required authorization, or behavior on duplicate products. This leaves critical behavioral aspects unspecified.

  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 two short sentences, front-loaded with the action and followed by a relevant constraint. No wasted words.

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

  Completeness2/5

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

  For a create mutation with no annotations, the description is minimal. While an output schema exists, the description omits behavioral context like id generation, duplicate handling, and prerequisites. It fails to fully prepare the agent for using the tool effectively.

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

  Parameters2/5

  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. It adds validation constraints for price and stock but leaves name and description unexplained. The addition is partial and insufficient for a 4-parameter tool.

  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 action (create) and resource (product), distinguishing it from siblings like update_product, delete_product, and get_product. 'One product' also clarifies scope, preventing confusion with bulk operations.

  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 its use case (creating a new product) but provides no explicit alternatives or exclusions. The constraint on price/stock gives some context, but the tool's role relative to siblings is only implicit.

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

• list_productsA
  3.7/5.0
  Behavior3/5

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

  With no annotations provided, the description must carry the disclosure burden. It mentions pagination and the limit constraint, which is useful. However, it does not describe offset behavior, default sorting, possible empty results, or whether authentication is required. The added limit range is a small but positive contribution.

  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 two short sentences, front-loaded with the primary function, and contains no filler. Every word earns its place, making it highly efficient.

  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?

  For a simple list tool with an output schema, the description provides the core purpose and one parameter constraint. However, it leaves offset undefined and omits behavioral details like ordering or edge cases. Given the lack of annotations and schema descriptions, it is minimally sufficient but not thorough.

  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 description coverage is 0%, so the description must compensate. It explains 'Limit is between 1 and 100,' adding meaning to the limit parameter. However, the offset parameter is not explained at all, only implied by the word 'pagination.' The description covers one of two parameters partially.

  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: 'List products with pagination.' The verb 'list' is specific and distinguishes it from sibling tools like create_product, get_product, update_product, and delete_product. The resource 'products' is unambiguous.

  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 for listing products, but it does not explicitly state when to choose this over get_product or provide any exclusion criteria. The mention of pagination hints at use for large result sets, but no concrete guidance is given.

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

• database_healthA
  3.8/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden. It only states 'Check' which implies a read-only operation, but it does not disclose any side effects, permissions needed, return format, or failure behavior. The description is too minimal to provide meaningful behavioral transparency beyond the basic action.

  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 a single concise sentence (8 words) that front-loads the purpose. There is zero wasted wording, making it extremely efficient and 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?

  Given the tool's low complexity (no parameters) and the presence of an output schema, the description is mostly sufficient. It could be slightly more explicit about what constitutes a healthy check or what the output indicates, but for a read-only health check of a database connection, it provides a clear enough scope.

  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 tool has zero parameters, so the input schema is empty. The description does not need to explain parameters, and the baseline for zero parameters is 4. The description does not contradict the schema, so this score 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 clearly states the tool's function: 'Check the selected database backend and its connection.' This is a specific verb (check) with a specific resource (database backend and connection), and it clearly distinguishes from sibling product CRUD tools.

  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 usage context is implied: use this tool to verify database health. However, there is no explicit guidance about when to use it versus alternatives or when not to use it. With only one sentence, it provides no exclusions or alternative references.

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

• get_productA
  4.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It explicitly says "Read," indicating a non-destructive operation, and specifies a positive numeric ID constraint. However, it does not disclose behavior for missing/invalid IDs, authentication requirements, or return format nuances, leaving gaps beyond the basic read action.

  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 a single, front-loaded sentence with no wasted words. It immediately communicates the tool's purpose and key constraint.

  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?

  The tool is simple with one parameter and an output schema that likely covers return values. The description is largely sufficient, but it does not mention what happens when the product ID does not exist (e.g., error vs. null), which would make it fully complete.

  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 schema only defines product_id as an integer with no description (0% coverage). The description adds meaningful semantics: "positive numeric ID" implies a validation constraint and clarifies the parameter's role as an identifier. This exceeds what the bare schema provides.

  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 "Read one product by its positive numeric ID" clearly states the verb (Read), resource (product), and scope (one product by ID). It distinguishes from siblings like list_products (multiple), create_product, update_product, and delete_product (mutations).

  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 the usage context: use when you have a product ID and need a single product. It does not explicitly name alternatives or exclusions, but the contrast with list_products and mutation tools is clear from the wording and sibling context.

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

• delete_productA
  4.3/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 destructive nature ('permanently delete') and adds a safety requirement (confirm user intent). This is more transparent than a generic 'delete' description, though it doesn't detail related data effects or error conditions.

  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 concise sentences with the most critical information front-loaded. Every word earns its place, and the reminder to confirm user intent is a valuable addition without unnecessary verbosity.

  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 delete operation with one parameter and an existing output schema, the description is complete. It notes permanence and a required safety step, which covers the main context an agent needs. No significant gaps are apparent.

  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?

  The schema has zero description coverage and only one required integer parameter. The description adds 'by ID' but does not explain the product_id semantics beyond what the parameter name and type imply. It's sufficient for a simple identifier, but the description could have explicitly stated that product_id is the identifier of the product to be deleted.

  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 action ('Permanently delete'), the resource ('one product'), and the scope ('by ID'). It distinguishes itself from sibling tools like create_product, update_product, and list_products by specifying deletion semantics and permanence.

  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 includes a crucial usage guideline: 'Confirm user intent first,' which warns the agent to verify user intent before invoking this destructive action. It doesn't explicitly mention alternatives, but the purpose is clear enough that an agent would know when to use this over update_product or list_products.

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