Regenique Elegance Commerce

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

Annotations declare non-read-only and non-idempotent status. Description adds prerequisite context ('existing cart') implying cart must exist first, but misses opportunity to clarify mutation behavior, quantity handling, or error conditions beyond what annotations provide.

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

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

optimally compact at two sentences. First establishes operation, second provides critical parameter sourcing hint. No redundant text or unncessary elaboration.

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

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

Adequate for a focused cart mutation tool. With full schema coverage and clear annotations, description doesn't need to explain return values (no output schema) or parameter formats. 'Existing cart' constraint satisfies behavioral context needs.

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

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

With 100% schema coverage, baseline is 3. Description adds value by specifying provenance of variantId ('from product details'), helping agents understand the tool chain. Could enhance further by noting cartId typically comes from 'create_cart' or 'get_cart'.

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

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

Excellent specificity with clear verb ('Add'), resource ('product variant'), and target ('existing cart'). Distinguishes from sibling 'create_cart' (which creates new carts) by emphasizing 'existing cart', and from 'remove_from_cart' by action direction.

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

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

Provides implicit workflow guidance ('Use the variant ID from product details') suggesting prerequisite use of 'get_product', but lacks explicit when-to-use vs 'create_cart' or 'remove_from_cart' guidance, and doesn't mention cart existence requirement.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false. The description adds crucial behavioral context that the tool 'Returns the cart ID', which is essential given the absence of an output schema. It also notes the optional nature of initial items, complementing the structured data without contradicting annotations.

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

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

Two sentences with zero waste. Front-loaded with the core action ('Create a new shopping cart'), followed by optional parameters and return value. Every phrase earns its place.

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

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

Given no output schema exists, the description adequately covers the critical gap by documenting the return value (cart ID). With annotations covering safety hints and 100% schema coverage, the description provides sufficient context for tool selection, though it could explicitly reference sibling workflow relationships.

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

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

Schema description coverage is 100% (lines, variantId, quantity all documented). The description mentions 'optionally with initial items' which aligns with the schema but does not add significant semantic detail beyond the structured schema. Baseline 3 applies for high coverage schemas.

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

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

The description uses specific verb 'Create' with resource 'shopping cart'. It effectively distinguishes from sibling 'get_cart' via the word 'new' and by explicitly stating it returns 'the cart ID needed for subsequent operations', clarifying its role in the workflow.

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

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

The phrase 'Returns the cart ID needed for subsequent operations' implies this is the first step in a cart workflow, providing implicit context. However, it lacks explicit guidance on when to use this versus 'get_cart' or clear prerequisites (e.g., 'use when no cart exists').

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

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

Annotations declare readOnlyHint=true, covering safety profile. Description adds context about narrowing selection but omits operational details like pagination behavior (despite cursor/limit params), default result set when no filters applied, or sorting methodology.

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

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

Two efficient sentences with no redundancy. Action and scope front-loaded, followed by utility statement. Every word earns its place.

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

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

Adequate for a read-only filtering tool with complete schema annotations, but omits important behavioral context: that all 7 parameters are optional (zero required) and implications thereof, plus pagination mechanics despite cursor presence.

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

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

With 100% schema description coverage, baseline is 3. Description maps mentioned criteria to parameters (vendor/brand→vendor, price range→minPrice/maxPrice) but adds no syntax guidance beyond what schema already provides.

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

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

States specific action ('Filter products') and lists filterable dimensions (vendor/brand, type, price, availability). However, it lacks explicit differentiation from sibling 'search_products' (text search vs. structured filtering) or 'get_collection_products'.

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

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

Provides only vague utility ('Useful for narrowing down') with no explicit guidance on when to prefer this over 'search_products' or when filters are optional vs. required. No mention of prerequisites or exclusions.

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

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

Beyond the readOnlyHint annotation indicating safety, the description adds valuable behavioral context by specifying exactly what data is returned—'contents and total'—which compensates for the missing output schema.

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

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

Single sentence front-loaded with action and scope. No redundancy or unnecessary words—every element earns its place.

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

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

For a simple single-parameter read operation with annotations present, the description is sufficiently complete, though it could briefly mention error cases (e.g., invalid cart ID) or the need for prior cart creation.

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

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

With 100% schema description coverage for the single parameter, the baseline applies. The description does not add additional parameter context beyond the schema's 'Cart ID (Shopify GID format)' description.

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

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

The description uses a specific verb ('Get') with clear resource ('shopping cart') and specifies the scope ('contents and total'), distinguishing it from siblings like get_checkout_url, create_cart, and update_cart.

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

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

While the description implies usage by stating what is retrieved ('contents and total'), it lacks explicit guidance on when to use this versus alternatives or prerequisites like needing to call create_cart first.

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

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

While annotations declare readOnlyHint=true (safe operation), the description adds critical workflow context: that the URL triggers external redirection, requires human escalation, and that the AI stops at URL generation without completing payment—essential behavioral traits for agent orchestration.

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

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

Three tightly constructed sentences with zero redundancy: first establishes purpose, second specifies redirection behavior, third defines escalation requirement. Information 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.

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

For a single-parameter URL retrieval tool, the description adequately covers the operational context (redirection) and escalation requirements. Absence of output schema is mitigated by the tool name and first sentence implying the return value is the checkout URL.

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

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

With 100% schema coverage ('Cart ID (Shopify GID format)'), the schema fully documents the parameter. The description references the cart concept implicitly but does not add syntax or format details beyond the schema, meriting the baseline score for high-coverage schemas.

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

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

The description opens with the specific verb 'Get' and resource 'Shopify checkout URL', clearly distinguishing this from sibling cart management tools (get_cart, add_to_cart, etc.) by focusing on the payment initiation flow rather than cart operations.

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

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

Explicitly states the user 'must be redirected to this URL to complete payment' (when to use) and clarifies 'This requires human escalation as the AI cannot complete payment' (capability boundary/alternative), providing clear guidance on the human-AI handoff.

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

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

Annotations declare `readOnlyHint: true`, which the description correctly aligns with using 'Get'. The description adds useful context that collections represent 'category' organization. However, it omits pagination behavior details (despite cursor/limit params) and error handling for invalid handles.

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

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

Two efficient sentences with no redundancy. Front-loaded with the action ('Get all products') followed by the required parameter context ('Use the collection handle').

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

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

Appropriate for a read-only list operation with simple parameters. The description explains the categorical nature of collections, which helps agents understand the Shopify domain model. No output schema exists, but the tool's purpose is clear enough that return values don't need explicit description.

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

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

Schema coverage is 100%, establishing baseline 3. The description semantically links the `collectionHandle` parameter to 'category' organization, but does not add details about `limit` or `cursor` beyond what the schema already provides.

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

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

States specific verb (Get), resource (products), and scope (within a specific collection). Mentions the collection handle mechanism. However, it does not explicitly differentiate from sibling tools like `filter_products` or `search_products`.

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

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

No explicit guidance on when to use this tool versus alternatives like `search_products` or `filter_products`. No mention of prerequisites 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.

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

While the readOnlyHint annotation confirms this is a safe read operation, the description adds valuable behavioral context by disclosing what data is returned: 'full product details including all variants, images, and availability.' This compensates for the missing output schema by setting expectations about the response payload.

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

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

The description consists of two highly efficient sentences with zero waste. The first sentence front-loads the action and identifier requirements, while the second immediately addresses the return value, respecting the reader's attention.

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

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

Given the straightforward transactional nature (retrieve one product), the combination of full schema coverage, the readOnly annotation, and the explicit mention of return data (variants, images, availability) provides sufficient context. The only minor gap is explicit differentiation from 'search_products' or 'filter_products' in the sibling set.

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

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

With 100% schema description coverage, the input parameters are already well-documented ('Product ID (Shopify GID format)', 'Product handle'). The description references these parameters correctly but does not significantly expand their meaning beyond what the schema already provides, warranting the baseline score.

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

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

The description uses a specific verb ('Get') with a clear resource ('product') and scope ('specific'). It distinguishes from siblings like 'search_products' and 'filter_products' by emphasizing retrieval of a single item 'by its handle (URL slug) or ID' versus searching or filtering lists.

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

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

The description provides clear context for when to use the tool—when you have a specific product identifier (handle or ID). However, it lacks explicit guidance on when not to use it (e.g., 'use search_products if you don't know the specific ID') or explicit exclusion criteria.

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

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

Complements the readOnlyHint annotation effectively by disclosing the specific return structure (names, descriptions, handles) since no output schema exists. Does not contradict annotations. Could mention pagination limits but schema covers that.

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

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

Two well-structured sentences with zero waste: first defines the action/resource, second defines the return values. Appropriately front-loaded.

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

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

For a simple 2-parameter read tool with 100% schema coverage, the description is sufficiently complete. It compensates for missing output schema by describing return fields. Could mention optional nature of parameters but not critical.

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

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

With 100% schema description coverage (limit range and cursor purpose fully documented), baseline 3 is appropriate. Description doesn't redundantly explain parameters, which is acceptable given schema completeness.

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

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

Clear verb 'List' and resource 'product collections/categories'. Specifies returned data (names, descriptions, handles). However, it does not explicitly differentiate from sibling 'get_collection_products' (which retrieves items within a collection), so sibling distinction is implicit only.

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

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

Provides implied usage context via 'for navigation' suggesting when to use it (browsing scenarios). However, lacks explicit when-to-use guidance or named alternatives like 'use get_collection_products to retrieve items within a specific collection'.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, establishing the mutation safety profile. The description adds that removal targets 'line IDs' specifically (not cart destruction) and supports 'one or more' items (batch capability), adding useful scope context beyond 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.

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

Single sentence, 11 words. Every word earns its place: action verb, target, and key parameter reference. Front-loaded and efficient with zero redundancy.

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

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

Appropriate for a 2-parameter destructive operation with complete schema coverage and clear annotations. Description clarifies the operation targets line items (not the cart itself). Lacks output description, but no output schema exists; description covers the behavioral scope adequately for tool selection.

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

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

Schema coverage is 100% with both parameters fully documented (cartId as 'Shopify GID format', lineIds as 'Cart line IDs to remove'). Description mentions 'line IDs' reinforcing the parameter purpose but adds no format, syntax, or constraint details beyond the schema. Baseline 3 appropriate for high-coverage schema.

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

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

Specific verb (Remove) + resource (items from the cart) + scope (by their line IDs). Clearly distinguishes from siblings like 'add_to_cart' (opposite action) and 'update_cart' (modification vs deletion) via the explicit 'remove' operation.

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

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

No explicit guidance on when to use versus alternatives (e.g., when to use this vs 'update_cart' to set quantity to zero). No prerequisites mentioned (e.g., needing cartId from 'get_cart'). Only states what the tool does, not when to invoke it.

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

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

Complements the readOnlyHint annotation by disclosing the return value structure (titles, descriptions, prices, images), which is essential since no output schema exists. Does not contradict safety annotations.

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

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

Three efficient sentences covering purpose, returns, and usage. Front-loaded with the core action. Slight ambiguity regarding 'browse by category' given the lack of a category parameter, but generally well-structured.

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

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

Adequate for a read-only search tool; compensates for the missing output schema by listing what fields are returned in the description. All three parameters are well-documented in the schema itself.

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

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

Input schema has 100% description coverage. Description mentions 'keyword' to reinforce the query parameter's purpose but does not add syntax details, examples, or semantics beyond what the schema already provides. Baseline 3 appropriate per rubric for high-coverage schemas.

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

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

Description clearly states 'Search for products by keyword' with a specific verb and resource. However, it does not explicitly distinguish from sibling tools like filter_products or get_product that may overlap in functionality.

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

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

Provides context ('Use this to find specific products or browse by category') but lacks explicit guidance on when to prefer alternatives like filter_products or get_collection_products versus this tool, nor does it clarify how category browsing works with only a 'query' parameter.

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

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

Aligns correctly with annotations: 'Add or update' confirms the idempotentHint=true (upsert semantics) and readOnlyHint=false. Adds checkout workflow context. However, it omits behavioral details like validation rules, whether partial updates are allowed, or side effects (e.g., triggering validation emails).

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

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

Single sentence packs all essential information: operation type, target fields, resource location, and workflow context. No redundancy or waste.

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

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

Complete for a 4-parameter update tool: all params documented in schema, idempotency declared in annotations, and checkout context provided. Minor gap: no mention of return value or success behavior given the lack of output schema.

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

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

With 100% schema description coverage, the schema already documents all parameters. The description lists the three optional buyer data fields (email, phone, country) confirming their purpose, but adds no additional format guidance or semantic constraints beyond the schema (e.g., noting that only cartId is required enables partial updates).

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

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

Description uses specific action verbs ('Add or update') with clear resource ('buyer information'), location ('on the cart'), and purpose ('for checkout'). It clearly distinguishes from sibling 'update_cart' by specifying this targets buyer data (email, phone, country) rather than cart items or attributes.

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

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

Provides clear workflow context ('for checkout') indicating when to use during the purchase flow. However, it lacks explicit guidance on alternatives (e.g., when to use 'update_cart' instead) or prerequisites (e.g., requiring an existing cart from 'create_cart').

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

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

Annotations declare idempotency and non-read-only status; the description adds crucial behavioral detail that setting quantity to 0 performs item removal. This 'soft delete' pattern is not inferable from annotations alone and represents meaningful added transparency about side effects.

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

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

Two tightly constructed sentences: first establishes core purpose, second provides critical operational detail (quantity=0 behavior). Zero wasted words; information density is high with purpose front-loaded.

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

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

Adequate for a focused cart mutation tool. Given 100% schema coverage, idempotency annotations, and explanation of the quantity=0 removal pattern, the description provides sufficient context for invocation. Minor gap: does not mention Shopify GID format constraint for cartId, though this exists in schema.

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

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

Schema coverage is 100%, with 'cartId' and 'lines' array fully documented. The description mentions 'quantities' aligning with the schema but does not add syntax, format constraints, or field semantics beyond what the structured schema already provides. Baseline 3 is appropriate given complete schema self-documentation.

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

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

Specific verb ('Update') + resource ('quantities of items already in the cart') + scope constraint ('already in the cart'). This clearly distinguishes the tool from sibling 'add_to_cart' (for new items) and implies it operates on existing cart state.

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

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

Provides clear behavioral context via 'Set quantity to 0 to remove an item,' which implicitly guides the agent to use this for quantity adjustments including removal, distinguishing it from 'remove_from_cart.' Lacks explicit 'when not to use' exclusions (e.g., 'do not use for adding new products'), though 'already in the cart' provides partial implicit guidance.

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