Server Quality Checklist

Tool Scores

• get_profileA
  3.8/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the full burden. 'Retrieve' indicates a read-only operation and 'single' clarifies the cardinality, but there is no mention of error behavior, permissions, or other side effects. The description is minimal but not misleading.

  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 that front-loads the action and resource. Every word earns its place, with no redundant information.

  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: one required parameter and an output schema exists, so return values need not be explained. The description covers the core purpose, but it lacks explicit guidance on when to use this tool vs. list_profiles. For a straightforward get-by-id, this is largely 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?

  The schema has one parameter, profile_id, with no description, so schema coverage is 0%. The description adds a little meaning by stating 'by its id', clarifying that the parameter is the unique identifier. However, it does not provide format, constraints, or how to obtain the ID.

  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 ('Retrieve') and resource ('a single customer profile by its id'). It distinguishes itself from sibling tools like list_profiles by specifying single-item retrieval via ID.

  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 fetching a specific profile by ID, but does not explicitly mention when to prefer this over list_profiles or any other alternative. No exclusions or conditions are provided, leaving usage to be inferred.

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

• get_orderA
  4/5.0
  Behavior3/5

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

  With no annotations, the description bears full responsibility for behavioral disclosure. It states the return includes line items and totals, but does not mention error handling, authentication requirements, rate limits, or side effects (though as a read operation side effects are unlikely). Basic behavior is covered, but deeper context is missing.

  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 unnecessary words. It communicates the main action and key details 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?

  For a simple get tool with one parameter and an output schema present, the description covers the essential purpose and return content. It does not discuss error cases or alternative tools, but these are less critical for a basic retrieval operation. The description is adequate if not exhaustive.

  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 provides only the parameter name and type (string), with zero description coverage. The description adds meaning by stating the order is retrieved 'by its id', clarifying the parameter's role. For a single self-explanatory parameter, this is sufficient compensation.

  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 retrieves a single order by its ID, including line items and totals. This specific verb-resource combination distinguishes it from sibling tools like list_orders (which likely lists multiple orders).

  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 use when you need a single order's details, but it does not explicitly mention when to use list_orders instead or any exclusions. Guidance is implied rather than directly stated.

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

• list_transactionsA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It usefully discloses that results are paginated at 50 per page and that time bounds are ISO-8601 UTC, but it does not mention whether the operation is read-only, requires permissions, or any rate limits. 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 two short sentences: the first states purpose and pagination; the second explains the parameters. It is front-loaded and contains no filler.

  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 an output schema exists, return values are covered. The description explains pagination and the filtering mechanism, which is sufficient for a list tool. It does not mention ordering or defaults, but these are minor gaps for a simple listing endpoint.

  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 description coverage is 0%, so the description must explain the parameters. It correctly names modified_after/modified_before (with format ISO-8601 UTC) and cursor for paging, giving them meaning beyond just field names. Cursor is not deeply defined, but adequate for usage.

  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 ('List'), the resource ('financial transactions for orders and donations'), and the page size. This distinguishes it from sibling list tools like list_orders (which lists orders, not transactions) and list_profiles.

  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 by stating what it lists and how to filter/page, but it does not explicitly compare against alternatives or state when not to use it. There is no mention of prerequisites or exclusions, so guidance is only implied.

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

• get_inventoryA
  4.2/5.0
  Behavior3/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 50-id-per-call limit and the read nature via 'retrieve,' but it does not specify error handling, idempotency, or authorization requirements. The limit is helpful, but other behavioral aspects are unaddressed.

  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 extremely concise: two sentences that combine the action and scope in the first and a clear usage condition in the second. Every word earns its place, with no redundancy.

  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 one-parameter read-only tool with an output schema, the description covers the essential input semantics, usage context, and a notable constraint (50 IDs). The output schema covers return values, so the absence of return details is acceptable. It is fairly complete for this simple case.

  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 provides only a bare 'variant_ids' array with no descriptions (0% coverage), so the description must compensate. It does so by explaining that the parameter accepts specific variant IDs and is capped at 50 per call, giving clear semantic meaning.

  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 opens with 'Retrieve inventory for specific variants (up to 50 ids per call),' using a specific verb and resource while scoping to exact variants, making it distinct from the sibling list_inventory tool. It clearly states what the tool does without ambiguity.

  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 phrase 'Use when you know exact variant ids and want their current stock' explicitly states the intended use case. However, it does not explicitly mention when not to use it or recommend an alternative for bulk inventory queries, so it lacks full exclusion guidance.

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

• get_productA
  4.4/5.0
  Behavior4/5

  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 adds meaningful behavioral detail by explaining that a comma-separated list of up to 50 ids is accepted, which goes beyond the simple string schema. It also notes 'Products v2' for version context. It does not discuss errors or permissions, but for a read-only retrieval tool this 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?

  The description is two sentences, front-loaded with the primary purpose and followed by a brief, focused detail on parameter flexibility and usage context. There is no wordiness, and every sentence contributes 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?

  For a simple retrieval tool with one parameter and an output schema, the description covers the core purpose, when to use it, and the parameter format. It omits details like error handling or response structure, but these are largely covered by the output schema and the tool's simplicity. Overall, it is sufficient for correct selection and invocation.

  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 parameter schema has no description (0% coverage). The description compensates by explaining that product_id can be a single id or a comma-separated list of up to 50 ids, adding critical semantic information about the parameter's format and constraints beyond the schema's bare string type.

  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 'Retrieve product(s) by id,' with a specific verb and resource. It distinguishes itself from siblings like get_order or get_inventory by resource, and from list_products by operation type (get by id vs list all).

  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 says 'Use when you already know the id(s),' providing a clear usage condition. It does not explicitly name alternatives or exclusion criteria, but the context is sufficient for an agent to know when to select this tool over a list tool.

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

• list_inventoryA
  4.5/5.0
  Behavior4/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 discloses pagination behavior ('50 per page' and 'Page forward with cursor from the prior response'). The 'List' verb implies read-only, but an explicit safety statement would have been stronger.

  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, front-loaded with the primary action, no redundancy. Every phrase 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?

  For a simple list tool with one optional parameter and an output schema, the description is sufficient. It covers resource, scope, pagination, and intended use without needing additional details.

  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 has zero description coverage for the cursor parameter, but the description explicitly explains that cursor is used for pagination and comes from the prior response, adding meaningful semantics beyond the schema's bare type definition.

  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 inventory items (stock levels) across variants with a specific verb and resource. It distinguishes from siblings by focusing on multi-variant stock listing rather than single-item retrieval (get_inventory) or other list types (list_products).

  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 phrase 'Use to audit stock' gives a clear use case. It does not explicitly mention alternatives or exclusionary conditions, but the context is adequate for a listing tool.

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

• list_profilesA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of disclosing behavior. It adds pagination details (50 per page, cursor usage) beyond the schema, and includes the clarification that customer profiles include contacts/customers. It does not mention rate limits or sorting, but for a simple list it provides key behavioral context.

  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 sentences, front-loaded with the core purpose, and every word earns its place. No fluff or repetition beyond the needed clarification of 'contacts/customers'.

  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 an output schema exists, the description doesn't need to enumerate return fields. It covers the main purpose and pagination behavior sufficiently. It doesn't mention filtering or sorting, but those are not implied by the schema. A slightly more explicit note about being the list-counterpart to get_profile would push it to 5.

  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 only parameter, cursor, is given clear meaning: it comes from the prior response and is used to page forward. Schema description coverage is 0%, so the description fully compensates by explaining how to obtain and use the cursor.

  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 ('List') and identifies the resource ('customer profiles') with clarification ('contacts/customers'). It also states the pagination limit (50 per page), making the tool's function unmistakable. It is clearly distinct from siblings like get_profile or list_products.

  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 clearly indicates how to use the tool for pagination ('Page forward with cursor from the prior response'), providing context on the only parameter. It does not explicitly mention alternatives or when-not-to-use, but the context is clear enough for a list operation.

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

• fulfill_orderA
  4.6/5.0
  Behavior5/5

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

  The description opens with "MUTATES THE LIVE STORE" in all caps, a strong warning about side effects. It also explains that customer notifications are sent when should_send_notification is true. With no annotations provided, the description carries the full burden and does so effectively by disclosing these 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.

  Conciseness5/5

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

  The description is concise and well-structured: a front-loaded mutation warning, a one-sentence purpose statement, then a compact enumeration of key details. No fluff or redundant phrases. Every sentence provides valuable information.

  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 output schema exists, the description does not need to explain return values. It covers the main contextual aspects: mutation warning, usage condition, and detailed parameter semantics for the non-obvious fields. The only minor omission is more explanation about order_id, but that is trivial.

  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 0% description coverage and the shipments object is loosely defined with additionalProperties: true. The description compensates by enumerating the accepted fields (carrierName, service, shipDate, trackingNumber, trackingUrl) and explaining the default and effect of should_send_notification. Order_id is not detailed but is self-evident from the name.

  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: "Mark an order fulfilled with shipment details." This is specific and distinguishes it from sibling read/list tools like list_orders and get_order. The verb "fulfill" and resource "order" are unambiguous, and the context of shipment details adds clarity.

  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 says "Use only when actually shipping an order," which is a clear usage guideline. However, it does not mention when not to use it or explicitly name alternatives, though the sibling tools are primarily read operations. The context of "actually shipping" provides enough guidance.

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

• list_productsA
  4.6/5.0
  Behavior4/5

  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 key behavioral traits: pagination limit (up to 50 per page), cursor-based pagination mechanics, and a critical constraint that cursor cannot be combined with filters. It also specifies ISO-8601 UTC format for date parameters. This is strong transparency, though it doesn't explicitly state read-only nature 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.

  Conciseness5/5

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

  The description is succinct yet packed with necessary details. It front-loads the primary purpose, then uses structured bullet-like formatting for filters and pagination. Every sentence earns its place, with no filler or repetition.

  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 complexity (5 optional params, pagination, no annotations) and presence of an output schema, the description is complete. It covers the main use case, all filter options with formats, pagination behavior, and the cursor constraint. No critical operational guidance is missing.

  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 description coverage is 0%, but the description fully compensates by explaining every parameter: modified_after/modified_before with format and example, type with allowed values (PHYSICAL | SERVICE | GIFT_CARD | DIGITAL), query as free-text search, and cursor usage with a caveat. This adds substantial meaning beyond the raw 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 begins with 'List store products', a specific verb+resource construction that clearly states the tool's function. It distinguishes itself from sibling tools like get_product (singular retrieval) and other list_* tools by focusing on products. Mentioning 'Products v2' adds version context.

  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 phrase 'Use to browse the catalog' provides a clear general context. The description gives concrete usage guidance for filters and pagination, but it does not explicitly name alternatives (e.g., 'for a single product, use get_product') or state when not to use this tool, so it falls short of a 5.

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

• adjust_inventoryA
  4.8/5.0
  Behavior5/5

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

  With no annotations, description discloses the destructive side effect (mutates live store), exact overwrite semantics, idempotency key, and 204 normalization to {}, which goes well beyond structured data.

  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?

  Four tight sentences, front-loaded with the critical mutation warning; every sentence adds operational value (set semantics, idempotency, return normalization, usage caveat).

  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 two-param mutation with no annotations but an output schema, the description covers side effects, input semantics, return behavior, and usage condition—everything an agent needs to decide and invoke safely. The output schema supplies return details, so no duplication.

  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%, but description adds semantic meaning to both parameters: variant_id is the stock target and quantity is exact finite target value, explicitly a set not a delta. This fully compensates for schema's lack of 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?

  Clearly identifies as a mutation to set a variant's stock to a concrete quantity, using specific verb 'set' and resource 'variant's stock'; distinguishes from sibling read-only inventory tools by emphasizing live store mutation and set-not-delta. No ambiguity.

  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 warns 'Use only when you intend to change real inventory' and states MUTATES THE LIVE STORE, giving clear context for when to invoke. It does not explicitly name alternative tools or exclusions, but this is sufficient guidance among inventory/order siblings.

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

• list_ordersA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description carries all behavioral disclosure: page size (up to 50), sort order (newest-modified first), filter values, and cursor-based pagination. This goes beyond the bare schema and provides actionable details for correct invocation.

  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 concise sentences, front-loaded with the primary purpose. Every piece of information (filters, pagination, ordering) serves a clear function 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?

  The description fully covers the tool's behavior: listing, filtering options, pagination mechanism, and ordering. With an output schema present, the description does not need to explain return fields. It is complete for an agent to invoke the tool correctly.

  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 schema has no descriptions, but the description explains all three parameters: fulfillment_status with its allowed values, modified_after with ISO-8601 format, and cursor for pagination. This fully compensates for the 0% schema coverage.

  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 'List store orders' with a specific verb and resource, and differentiates from siblings like get_order (single order) and list_transactions (transactions vs orders). It adds pagination and ordering context, making the tool's purpose unmistakable.

  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?

  It provides clear context for when to use the tool (listing orders with optional filters and pagination) and explains the filter semantics. It does not explicitly mention exclusions or alternatives, but the context is sufficiently clear to guide the agent.

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