Server Quality Checklist

Tool Scores

• set_locationA
  4.2/5.0
  Behavior4/5

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

  The description goes well beyond the annotations by disclosing that the tool changes session state, alters the serving store, and directly affects the results returned by search_products and get_product. It also discloses the ambiguity behavior: matches are returned and the agent should ask for clarification. There is no contradiction with the 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?

  Two sentences deliver the core purpose, the downstream effects, and the edge-case handling with no redundant wording. The main action is front-loaded, and every sentence earns its place.

  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 one-parameter setter, the description covers the action, its impact, and the ambiguous-input behavior. It does not describe the exact success response format, but the tool has no output schema and the narrative description is sufficient for an agent to invoke it correctly.

  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 already fully documents the single 'suburb' parameter, including an example and a note that partial names match. The description reinforces the ambiguity-handling behavior but does not add substantially new parameter-level meaning beyond the schema. Given 100% schema description coverage, this is an appropriate baseline score.

  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 states a specific verb ('Switch the session') and a clear resource ('a New Zealand suburb'), and it explains the consequence of changing the serving store. It is easily distinguished from sibling tools like get_location, which reads the current location rather than setting it.

  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 clear context for when to use the tool: to switch the session's delivery location and thereby affect product prices and availability. It also instructs the agent to ask for a more specific name when matches are returned, which is practical usage guidance. It does not explicitly name alternative tools, but the alternatives are structurally different read-type operations.

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

• search_productsA
  4.3/5.0
  Behavior5/5

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

  Annotations already provide readOnlyHint=true and openWorldHint=true, but the description adds substantial non-obvious behavior: the exact return fields, coverage semantics, ANDing of query words, ranking padding, unitPrice formatting and absence, and per-location prices. This goes well beyond what annotations or schema convey, with 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?

  The description is five dense sentences, each earning its place: purpose, return values, query ANDing and ranking caveat, unitPrice caveat, and location dependence. It is front-loaded with the core function and return shape, followed by high-value warnings. No filler.

  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, the description compensates by naming the return fields and explaining the coverage sentence, which is essential for correct reasoning. It also covers ranking padding, unitPrice comparability, and location context. An agent has what it needs to avoid common wrong answers when searching the catalogue.

  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 100%, and the schema already documents each parameter's purpose, including the department filter's post-search application and CUPAsc's unit caveat. The description reinforces unitPrice-related output caveats but adds little parameter-level meaning beyond the schema, so the baseline 3 applies.

  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 opens with a specific verb and resource: 'Search the Woolworths New Zealand catalogue by keyword.' This clearly identifies what the tool does. It does not explicitly differentiate from the sibling search_products_batch, so it stops short of a 5.

  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 clear context for when to use the tool, especially the instruction to read the coverage sentence before answering cheapest/only/none questions and to call get_location/set_location for location-dependent prices. It does not mention search_products_batch as an alternative for batch or multi-query use, so it misses an explicit exclusion.

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

• browse_categoryA
  4.4/5.0
  Behavior4/5

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

  Beyond the readOnlyHint and openWorldHint annotations, the description explains single-page returns, the need to read 'coverage' before making existence or best/cheapest claims, and the pagination termination rule. It also discloses location-dependent prices and availability, which is valuable behavioral context not present in the 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?

  Four compact, front-loaded sentences carry the purpose first, then essential operational caveats. Every sentence adds information needed for correct invocation, with no filler or repetition of schema content.

  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?

  With no output schema, the description explains the most important output-related behaviors: one page at a time, a coverage field, and how to detect the final page. It could say more about the exact product fields returned, but the operational guidance is sufficient for the main use cases described.

  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 value by clarifying the dependency between department, aisle, and shelf slugs, and by tying prices/availability to the current delivery location. It does not need to restate the schema's already detailed parameter 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 states a specific verb and resource: 'List the products in a department, aisle or shelf', and further clarifies that slugs come from list_categories. This cleanly distinguishes browse_category from search_products and get_product without opening any schemas.

  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 gives explicit guidance on when to use the tool: after list_categories, with the caveat that narrower levels require wider slugs. It also points to get_location/set_location for location-dependent pricing. It does not explicitly state when to prefer search_products over browse_category, so it stops 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.

• get_order_historyA
  4.4/5.0
  Behavior5/5

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

  Beyond the annotations, the description discloses a key behavioral trait: the site returns only its default recent window, so an order's absence is not evidence it was never placed. It also states the authentication prerequisite, which is not covered by readOnlyHint or openWorldHint.

  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 short, front-loaded with the main purpose, and every sentence earns its place: the listing statement, the coverage caveat, and the authentication instruction. There is no redundancy or filler.

  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 parameterless, read-only, open-world tool, the description is complete: it specifies the returned data fields, warns about incomplete data, and provides the auth prerequisite. No output schema exists, but the field list adequately covers return expectations.

  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 there is nothing for the description to explain beyond what the schema shows. The baseline of 4 for a parameterless tool is appropriate, and no additional parameter detail is needed.

  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 ('List') and resource ('the account's past orders') and enumerates the returned fields: references, dates, fulfilment slots, statuses and totals. It is clear but does not explicitly distinguish it from the sibling get_past_purchases, so an agent must infer the difference from 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 description gives clear usage context: it requires a signed-in session and tells the agent how to achieve that (run npm run login or call sign_in). It also warns about the default recent window caveat, but it does not explicitly state when to prefer this over alternatives or when not to use it.

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

• get_product_labelA
  4.4/5.0
  Behavior4/5

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

  The annotations already establish readOnlyHint and openWorldHint, so the description adds non-obvious behavioral context: images are token-expensive, the photo may not show the panel, and label reading is not a substitute for physical packaging. 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?

  Four sentences, front-loaded with the purpose and trigger condition, followed by cost and reliability caveats. Every sentence earns its place; nothing is redundant or 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?

  For a one-parameter read-only tool, the description covers what it returns, why to use it, when to call it, and important limitations. It does not specify the exact image response format, but the description's clarity is sufficient for correct invocation.

  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 single required parameter 'sku' is already fully described in the schema with 100% coverage, so the description does not need to repeat parameter details. It adds usage context around ordering one product at a time but no additional parameter semantics, matching the baseline.

  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 states a specific verb ('Return') and resource ('product's packaging photo'), and explains its purpose: to surface details the API does not publish, especially ingredients and allergens. This clearly differentiates it from get_product and other siblings.

  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?

  It gives an explicit trigger condition: call when get_product reports allergens or ingredients as 'notStated' and the answer matters. It also provides cost-driven usage constraints (one product at a time, only when needed) and a caution that photos may not be sufficient for allergy decisions.

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

• get_specialsA
  4.4/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint and openWorldHint, and the description builds on them rather than repeating them: it discloses pagination ('Returns one page'), the wasPrice return field, and the open-world caveat in actionable form ('read coverage before claiming anything is the best or only special available'). It also surfaces the non-obvious location-dependence of prices and availability. 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?

  Four sentences, roughly 60 words, every one earning its place: purpose first, then return shape, pagination caveat, and location dependency. The most important operational traps (coverage, location) are stated explicitly with no filler and no repetition of schema content.

  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 moderate-complexity tool with no output schema, the description covers the risky behaviors: single-page results, the coverage field, per-location pricing, and the wasPrice field, while the schema handles the sort and page quirks. It slightly underspecifies what coverage actually contains (e.g., total specials count), but nothing critical is left to guesswork.

  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 100%, so all four parameters (page, sort, department, includeOutOfStock) already carry descriptions, including a thorough note on the CUPAsc quirk. The description adds only the department-narrowing mention ('optionally narrowed to one department'), so it sits at the baseline 3 without needing to compensate.

  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 opening sentence states a specific verb and resource ('List products currently on special') plus the optional narrowing condition (department). The scope — current specials rather than general product search — distinguishes it from siblings like search_products, browse_category, and get_product from the first clause.

  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 clear context: use this when you need current specials, optionally per department, and it warns that results are location-scoped, advising get_location/set_location as prerequisites. It stops short of explicitly naming alternatives (search_products, browse_category) and stating when to prefer them, so it misses the top of the scale.

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

• remove_from_cartA
  4.4/5.0
  Behavior4/5

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

  Annotations already mark the tool destructive and idempotent; the description adds the signed-in session requirement and explains that a removal requires no pricing unit. This meaningfully supplements the structured metadata without contradicting it.

  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 short sentences, each adding distinct value: the operation and its effect, the pricing-unit exception, and the authentication prerequisite. Information is front-loaded and there is 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?

  For a single-parameter mutation with annotations covering idempotence and destructiveness, the description covers the operation, its effect, authentication, and a special condition for invocation. It does not mention the response or error cases, but the absence of an output schema and the low complexity make this a minor gap.

  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 documents sku with 100% coverage, so the baseline is 3. The description adds useful context by clarifying that the SKU identifies the line to remove and that no pricing unit is needed, which goes 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 uses a specific verb and resource: 'Remove a line from the trolley entirely,' and clarifies the exact effect by comparing it to setting quantity to 0. This also distinguishes it from sibling tools like set_cart_quantity.

  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 statement 'the same as setting its quantity to 0' plus 'No pricing unit is needed' gives clear context for when this tool is appropriate versus a quantity-setting alternative. It does not explicitly name alternative tools or state when not to use it, so it stops 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.

• auth_statusA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare this as a read-only operation, and the description adds useful behavioral context beyond that: it clarifies that catalogue tools are unaffected by auth state and that cart/purchase-history tools depend on it. It also discloses that the tool reports whether sign-in is possible at all, not just current status.

  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 purpose, followed by a relevant scoping note about which tool families are affected. Every sentence earns its place with no redundancy or filler.

  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 parameterless status tool, the description fully covers what the call reports and why it matters. Since there is no output schema, the wording 'Report whether...' adequately implies a boolean or status-style response, and nothing needed to invoke the tool correctly is missing.

  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, and schema description coverage is vacuously 100%, so the description does not need to explain parameter meaning. It still contributes by framing the no-input call as a session-level status check.

  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 ('Report') and names the exact resource being queried: whether this session is signed in to a Woolworths account and whether sign-in is possible. This clearly differentiates it from the sibling sign_in tool, which performs the action rather than reporting status.

  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 clear context by explaining that catalogue tools work signed out while cart and purchase-history tools need a signed-in session, which implies when auth_status is useful. It does not explicitly state 'use this before cart tools' or name exclusions, but the context is strong enough for an agent to infer the right moment to call it.

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

• get_locationA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and openWorldHint, and the description does not contradict them. It adds useful behavioral context by explaining that the returned location affects every other tool's results and enumerating the returned fields, which goes beyond the structured 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 sentences with no filler. The main purpose is front-loaded, and the second sentence earns its place by telling the agent when the result matters.

  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 zero-parameter read-only tool with a simple return concept, the description is complete. It names the exact return components and explains how the output should be used in the larger workflow, with no output schema required.

  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 schema fully covers parameter semantics and the baseline is 4. The description adds no param details, but none are needed; it instead clarifies what the response will contain.

  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 the specific verb 'Report' and names the exact resource: the delivery location for the current session, including suburb, fulfilment method, and store id. It clearly separates this from sibling tools like set_location by characterizing it as the source of truth for all other pricing and availability tools.

  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 clear guidance on when to call this tool: before trusting any price or availability result, since all other answers are scoped to this location. It does not explicitly mention when not to use it or name alternatives such as set_location, so it falls just short of the top score.

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

• list_categoriesA
  4.5/5.0
  Behavior4/5

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

  Annotations already cover read-only and open-world behavior, so the safety profile is established. The description adds meaningful behavioral detail: the tool is hierarchical, has exactly 13 departments at the top level, and switches output granularity based on the presence of the department argument. This goes beyond the annotations without contradicting them.

  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 short sentences, each with a distinct purpose: orient the user, describe the no-argument behavior, describe the slug behavior, and explain how to use the output. There is no redundancy or filler, and the most important information is front-loaded.

  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, the description must explain the return shape, and it does: departments and slugs at the top level, aisles and shelves at the department level. It also provides the natural next step (browse_category). For a simple read-only tool with one optional parameter, nothing essential is missing.

  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 100% coverage for the optional department parameter, so the baseline is 3. The description adds the key semantic that providing a slug changes the result to that department's aisles and shelves, which is not explicit in the schema description. This lifts it to 4.

  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 states the tool lists the Woolworths browse tree: with no argument it returns 13 departments with slugs, and with a department slug it returns aisles and shelves. This is a specific verb and resource, and the pointer to browse_category distinguishes it from that sibling.

  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 explains both invocation modes: omit the argument for top-level departments, or pass a department slug to get its aisles and shelves. It also tells the user to feed the returned slugs into browse_category. It does not explicitly name alternatives or state when not to use the 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.

• sign_inA
  4.6/5.0
  Behavior5/5

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

  The description discloses critical behavioral traits beyond the annotations: it never performs sign-in, cannot perform sign-in because of Auth0's non-browser challenges, never sends credentials, and never touches the account. The readOnlyHint being false is not contradicted because the description does not claim the operation cannot read or report local session state; it makes a stronger, consistent safety statement.

  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 tightly structured: the core purpose is front-loaded, followed by the critical limitation and external alternative, then the safety guarantee. Every sentence carries necessary information and there is no filler.

  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 zero-parameter tool with no output schema, the description is complete: it explains what the tool reports, what the caller should do if signed out, why sign-in cannot happen in-process, and that credentials are never touched. The 'report whether' phrasing sufficiently frames the expected result for an agent.

  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 zero parameters and 100% coverage, so the description does not need to document parameter meaning. The baseline of 4 is appropriate because no parameter detail is missing or required.

  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 clearly states that the tool reports signed-in status and explains how to sign in if needed, while explicitly saying sign-in is not performed here. This is a specific and useful definition, though it does not explicitly differentiate itself from the sibling auth_status tool.

  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 gives explicit when-to-use guidance: call it to report session status and sign-in instructions. It also gives a clear when-not-to-use condition and a named alternative: actual sign-in happens via `npm run login` in a real browser, not through this tool.

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

• find_storesA
  4.7/5.0
  Behavior5/5

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

  The annotations already declare readOnlyHint and openWorldHint, and the description adds valuable behavioral detail beyond them: unfiltered results are only a sample, each store appears once, and the 'areas' field contains every region under which the store is listed. It also clarifies the relationship to the delivery-location concept, which the annotations do not cover.

  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 compact and front-loaded with the core purpose, then adds the critical sampling caveat and the distinction from the delivery-location tool. Every sentence conveys necessary operational context with no filler.

  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 read-only tool with one optional parameter, the description covers everything needed to invoke it correctly: what it lists, how filtering works, the sample behavior, the uniqueness of stores, the 'areas' field, and the separation from delivery-location tools. No output schema exists, but the description provides enough field context ('areas') and behavioral expectations for the agent.

  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 input schema already documents the only parameter, 'query', with meaning and an example. The description adds 'name or address fragment' but this largely restates the schema description. With 100% schema coverage, the description does not need to compensate, so a baseline of 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 states a specific verb ('List'), a specific resource ('Woolworths New Zealand pick-up locations'), and the filtering behavior ('by a name or address fragment'). It also explicitly distinguishes these collection points from the separate delivery-location tool, making its 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 Guidelines5/5

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

  The description gives concrete usage guidance: an unfiltered call returns only a sample, so the agent must search before concluding a store does not exist. It also names the alternative tools for the delivery location ('get_location and set_location') and explains why they are separate, effectively telling the agent when not to use this tool.

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

• get_cartA
  4.7/5.0
  Behavior5/5

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

  The description details the response shape (`lines`, `lineCount`, `totalQuantity`, `totals`) and explains aggregation semantics with a concrete example of 19 lines summing to 23 items. It also discloses the authentication requirement, complementing the readOnlyHint annotation without contradicting it.

  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?

  Every sentence contributes: purpose, return payload semantics, and the session prerequisite. It is compact, front-loaded, and free of filler.

  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 zero-parameter read-only tool with no output schema, the description fully compensates by enumerating the return fields and their meaning, plus the login prerequisite. Nothing needed for correct invocation is missing.

  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 no parameters, so the empty schema fully covers this dimension. With zero parameters, the baseline is 4; there is nothing more the description could add about parameter 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 opens with 'List the trolley,' a specific verb and resource, and then elaborates on the exact returned fields. It is unmistakably about reading the current cart, separate from product search or cart mutation siblings.

  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 clearly states the key precondition for use: a signed-in session, with concrete instructions to run `npm run login` or call sign_in. It does not explicitly name alternative tools, but the purpose and prerequisite strongly frame when this tool is appropriate.

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

• get_past_purchasesA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnly and openWorld annotations, the description discloses a critical behavioral trap: one section is retailer advertising and must never be described as the shopper's purchases, habits, or preferences. It also instructs the agent to read each section's coverage before drawing conclusions, which is highly valuable non-obvious 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?

  Three sentences with no filler: the purpose is front-loaded, followed by the essential data-integrity warning, and finally the actionable auth prerequisite. Every sentence earns its place.

  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 zero-parameter, read-only tool with no output schema, the description covers how to authenticate, what the returned sections mean, which section reflects real purchases, and how to use coverage before drawing conclusions. Nothing essential is missing for correct invocation and interpretation.

  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 and 100% schema description coverage, so the input schema already covers everything. The description's references to isPurchaseHistory and coverage are output semantics, not parameter semantics, and there is nothing more the description needs to add here.

  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 and resource: it returns the site's previously-purchased sections and immediately clarifies that these are separated and labelled. The isPurchaseHistory caveat distinguishes this tool from a plain order-history lookup and from siblings like get_order_history.

  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 states the prerequisite of a signed-in session and gives actionable auth steps. It also explains how to interpret the returned sections correctly. However, it does not explicitly name alternative sibling tools or state when this tool should not be used, so it stops short of full when/when-not 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.7/5.0
  Behavior5/5

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

  Despite readOnlyHint and openWorldHint annotations, the description adds substantial behavioral context: allergens/ingredients are often not published, 'notStated' means absence of data rather than safety, 'purchasingUnit' maps to cart tool requirements, and prices are per delivery location. These details materially change how an agent should use the result and are not available from annotations or schema.

  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 dense but every sentence carries operational value: the first sentence names the resource and payload, and the following sentences address the non-obvious caveats that an agent must know before presenting results. It is well-structured, front-loaded with the core purpose, and contains no filler.

  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, the description carries the full burden of explaining what the agent can expect. It lists the returned fields and clarifies the ambiguous ones: unit_price may be absent, purchasingUnit and canBuyByWeight affect downstream cart behavior, allergen/ingredient statuses require careful interpretation, and location affects price/availability. This is sufficient context for correct invocation and interpretation.

  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 input schema is fully covered at 100% and already documents the single 'sku' parameter with an example. The description's mention of 'by SKU' reinforces this but adds no additional parameter-specific semantics beyond what the schema provides, so the baseline score of 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 opens with a specific verb and resource — 'Fetch one product by SKU' — and enumerates the exact data fields returned. This clearly distinguishes get_product from search-oriented siblings like search_products and from get_product_label, which is mentioned as a packaging-reading alternative.

  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 gives explicit routing guidance: use get_product_label when packaging-level allergen information is needed, and use get_location/set_location because prices and availability are location-dependent. It also warns against treating 'notStated' as allergy assurance, which functions as a clear when-not-to-interpret instruction.

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

• search_products_batchA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnly and openWorld annotations, the description discloses substantive behavior: ranking pads results, extra query words are ANDed, truncated groups cannot answer cheapest/only/none questions, and prices/availability depend on delivery location, with pointers to get_location and set_location. 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?

  Three sentences, each earning its place: main purpose first, then per-group behavior and caveats, then location context. There is no filler or repetition of schema details.

  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, the description still tells the agent results are grouped by query and that each group carries its own coverage sentence. It also covers ranking, truncation, AND semantics, and location dependence, making the tool safely callable without missing critical context.

  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 100%, so the baseline is 3. The description adds extra meaning by explaining how queries are interpreted (extra words ANDed) and that truncated results affect question-answering, which enriches the queries and resultsPerQuery parameters 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 uses a specific verb and resource: 'Run several catalogue searches in one call and get the results grouped by query.' This clearly distinguishes the tool from the single-query search_products sibling and matches the title's promise of searching several things at once.

  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 first sentence states the batching rationale — 'so finding many products costs one round trip' — making it clear the tool is for multiple searches. It references search_products for caveats but does not explicitly say 'use search_products for a single query,' so the guidance is strong but not fully explicit.

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

• set_cart_quantitiesA
  4.8/5.0
  Behavior5/5

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

  Goes well beyond the annotations by disclosing that quantity is absolute and 0 removes the line, that results report each item as written or failed, that a failure never drops items from results, and how `adjusted` and `adjustment` fields work. It also warns about the `Kg`/`canBuyByWeight` edge case, which is exactly the behavioral nuance an agent needs.

  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?

  Every sentence earns its place: the main purpose is front-loaded, then the most important quantity semantics, pricing unit constraints, result handling, adjustment behavior, and auth prerequisite. It is dense but not bloated, with no filler.

  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 has no output schema, so the description compensates by explaining the per-item result shape, failure semantics, adjustment fields, and auth requirement. It covers enough edge cases that an agent can safely call this mutation tool without further lookups.

  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?

  Even though the schema already documents `sku`, `quantity`, and `pricingUnit`, the description adds crucial semantics beyond it: absolute-not-delta behavior, 0-removes semantics, using `purchasingUnit` verbatim, and the 'Kg' only-valid-with-`canBuyByWeight` rule. This materially improves 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?

  States a specific verb and resource: 'Set many products' trolley lines in one call.' It clearly differentiates from the singular sibling set_cart_quantity by emphasizing batch operation, and the title reinforces 'several trolley lines at once.'

  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?

  Clearly implies this is for setting multiple cart lines in one call rather than one at a time, and gives important prerequisites like needing a signed-in session and running `npm run login`. It does not explicitly name sibling alternatives or state when not to use it, so it falls just short of full guidance.

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

• set_cart_quantityA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations (idempotentHint=true, destructiveHint=false), the description discloses subtle behavior: quantity is absolute not a delta, 0 removes the line, Woolworths may silently substitute quantity and report it via adjusted/adjustment, and trolleyTotalQuantity is a sum across the whole trolley. This is rich behavioral context that genuinely helps an agent anticipate non-obvious outcomes.

  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 every sentence carries substantive information: core behavior, parameter rules, return-value nuance, alternative tool, and auth requirement. It fronts the main behavior and then layers detail logically, 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?

  Despite having no output schema, the description explains the important return fields (requestedQuantity, appliedQuantity, adjusted, adjustment, trolleyTotalQuantity) and what they mean. It covers auth, the source of pricingUnit, a caveat about weight purchases, and the sibling tool for multiple updates, making the tool fully usable by an agent.

  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 covers the parameters at 100%, which sets a baseline of 3. The description adds valuable semantics beyond the schema: sourcing pricingUnit from the product's purchasingUnit field, requiring canBuyByWeight for decimal 'Kg' quantities, and warning that 'Kg' for a counted item orders a kilogram. This clearly exceeds the baseline.

  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 the specific action 'Set one product's trolley line to an exact quantity, adding it if absent,' clearly indicating the verb and resource. It also differentiates itself from the sibling set_cart_quantities by noting it handles one line rather than several.

  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?

  It explicitly says 'To change several products, use set_cart_quantities instead,' giving a direct alternative and selection criterion. It also states the auth prerequisite — 'Needs a signed-in session; run npm run login...' — and provides detailed usage rules for pricingUnit and canBuyByWeight.

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