Server Quality Checklist

Tool Scores

• create_replenishment_orderA
  4.9/5.0
  Behavior5/5

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

  The description goes far beyond the annotations. It discloses that every call issues a new order_id with no idempotency token, that retries load a second truck, that orders are append-only with no cancel/delete/amend, and that access errors guarantee nothing was written. It also explains the real-world physical consequence of a submitted order. This is exceptional behavioral disclosure, far exceeding the minimal hint from annotations.

  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 long and detailed, but it is very well-structured with uppercase section headers, bullet points, and a clear flow from warning to returns to usage rules. Some redundancy exists (e.g., 'never infer a quantity' appears multiple times, no-idempotency is emphasized in both a section and later limitations), which prevents a 5. However, given the high-stakes nature of the tool, the length is largely justified.

  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 is remarkably complete. It covers return values (order_id format, status, confirmation line), error semantics (rejected-before-submission guarantee, credential failures), edge cases (SKU not ranged), and integration with sibling tools. It even advises on how to handle ambiguous buyer instructions and failed calls. No output schema exists, so this detailed textual description fully compensates.

  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?

  Although schema coverage is 100%, the description adds critical safety context. For quantity, it clarifies that the number must be explicitly approved by the buyer, never inferred or rounded to case/pallet size. For reason, it explains the audit-trail function and requires evidence from get_stock_position. For store_id, it adds the constraint that it must be a store just checked and warns against rerouting on auth errors. These enrich the schema meaning substantially.

  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 a precise verb and resource: 'Submit a replenishment order for one SKU to one Korral store in StoreLink.' It explicitly labels itself as the 'ONLY write tool on this server,' instantly distinguishing it from its read-only siblings. The scope (one SKU, one store) is also stated up front.

  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 contains dedicated 'WHEN TO USE IT' and 'WHEN NOT TO USE IT' sections. It positions the tool as step 3 in a named workflow (lookup_sku -> get_stock_position -> create_replenishment_order -> get_replenishment_status), specifies that it should only be used after a positive gap and buyer approval, and explains what the tool cannot do (cancel, amend, create purchase orders). This is explicit, actionable guidance with alternatives.

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

• get_replenishment_statusA
  4.9/5.0
  Behavior5/5

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

  Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavioral context: status lifecycle, the requirement to pair order_id from creation, the inseparable store scope, not-found semantics vs. access errors, and the impossibility of mutation. This goes far beyond the annotations and contains no contradiction.

  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?

  Long but tightly organized with clear section headers (WHAT IT RETURNS, WHEN TO USE IT, SCOPE CHECK, ACCESS ERRORS, WHEN NOT TO USE IT). Every sentence carries operational significance—return fields, status-timestamp pairing, error disambiguation, and alternative tools. Nothing is redundant.

  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 tool is complex due to order-state semantics, store scoping, and error-prone access failures. With no output schema, the description fully covers return content, usage context, scope assertions, error interpretation, and non-mutability. It is self-sufficient for an agent to select and invoke correctly.

  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% and both parameters already carry detailed descriptions. The tool description adds meaning by explaining the dependency on a prior create_replenishment_order call, the lack of search/recovery, and the strict pairing requirement. This is a modest increment over the schema, so 4 rather than 5.

  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 a specific verb ('Read back') and resource ('single replenishment order') scoped to its store. It clearly distinguishes itself from siblings by stating there is no browse/search/list capability and explicitly contrasts with get_stock_position for current shelf stock.

  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 workflow positioning ('Step 4 and the final step of the standard workflow'), concrete buyer-intent triggers ('did that order go through?'), and a dedicated 'WHEN NOT TO USE IT' section naming alternatives (e.g., get_stock_position) and exclusions (no cancel/delete/amend).

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

• get_stock_positionA
  4.9/5.0
  Behavior5/5

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

  Despite readOnlyHint=true and openWorldHint=true annotations, the description goes far beyond by detailing the exact computation of gap, the knife-edge gap=0 interpretation, the five distinct error modes with appropriate responses, and explicit warnings like never passing gap into create_replenishment_order's quantity. It also discloses that units_sold_last_24h is an aggregate with no underlying baskets or timestamps.

  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?

  Although long, the description is impeccably structured with clear headings (WHAT IT RETURNS, HOW TO READ gap, WHEN TO USE IT, ERRORS, WHEN NOT TO USE IT). Every sentence earns its place, covering complex edge cases without redundancy, and the core purpose is front-loaded in the first line.

  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?

  With no output schema and complex per-store error semantics, the description fully compensates by explaining return fields, gap interpretation, error types, and limitations. It also places the tool in the broader workflow, making it complete for an agent to use correctly.

  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%, so the baseline is 3. The description adds marginal value by reinforcing the workflow context ('Pass every store the buyer cares about in one call rather than looping') and clarifying the per-store error behavior for store_ids, though most parameter details are already in the schema. The description's examples (e.g., store_id '47') and the call to resolve SKUs via lookup_sku add a little extra semantic color.

  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 a precise verb+resource: 'Read the current StoreLink inventory snapshot for one SKU across one or more Korral stores, and compute the replenishment gap.' It clearly distinguishes itself from siblings by stating its role as the read-only gap calculator between lookup_sku and create_replenishment_order, and the workflow section reinforces this.

  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?

  A dedicated 'WHEN TO USE IT' section explicitly places the tool as Step 2 of the standard workflow, names the exact conditions for use (e.g., always before proposing an order, pass all stores at once), and 'WHEN NOT TO USE IT' lists exclusions like no supplier info, no trend analysis, and no ORDER quantity derivation. This is explicit when-to-use and when-not-to-use guidance.

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

• lookup_skuA
  4.9/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and openWorldHint annotations, the description discloses matching behavior (case-insensitive substring, prefix/exact SKU match), empty-match behavior (returns empty array and hint, not an error), and re-query guidance. It also explicitly lists what is not included (stock, sales, order history, supplier info). No contradiction 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 long but efficiently structured with distinct sections (WHAT IT RETURNS, WHEN TO USE IT, WHEN NOT TO USE IT). Every sentence provides actionable information, with front-loaded purpose and clear formatting. No fluff or 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?

  There is no output schema, so the description carries the full burden of explaining return values. It details the matches array fields (sku, name, category, unit) with examples and explains the unit system. It also covers edge cases (no matches, ambiguous matches) and clearly states limitations relative to sibling tools. Complete for the tool's role.

  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 already provides a detailed description of the query parameter, so baseline is 3. The description adds matching rules ('case-insensitive substring on name, plus exact or prefix match on sku') and clarifies the meaning of an empty result ('it is not an error'). This goes beyond the schema's parameter text, though schema coverage is already high (100%).

  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 a specific verb+resource: 'Resolve a product name fragment or SKU code to Korral StoreLink SKU records.' It clearly distinguishes itself from siblings by positioning it as 'step 1 of the standard workflow' and contrasting with get_stock_position which handles stock levels.

  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 'WHEN TO USE IT' and 'WHEN NOT TO USE IT' sections give explicit guidance: use as the first call, when buyers mention product names, or when get_stock_position returns an unknown-SKU error. It also explicitly names get_stock_position as the alternative for stock data, and explains what it cannot retrieve. This is exemplary usage guidance.

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