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

With no annotations provided, the description carries the behavioral disclosure burden. It does disclose the core mutation semantics: it changes available inventory by a signed delta. However, it omits potential side effects, authorization requirements, idempotency, or response behavior, which are relevant for a write operation.

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 is two sentences with no filler. The core operation and delta semantics are front-loaded, and the prerequisite lookup guidance is placed in the second sentence without 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?

For a simple mutation with fully documented parameters and no nested objects, the description covers the necessary setup: how to obtain both required IDs and what delta means. It does not describe the return value or error cases, but nothing in the provided context suggests these are blocking for correct invocation.

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%, so the baseline is 3. The description reinforces the delta behavior and adds helpful workflow guidance for obtaining the two ID parameters, but it does not add substantial parameter semantics beyond what the schema already documents.

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 states a specific action ('adjust available inventory quantity'), a specific resource ('product variant at a location'), and the exact delta semantics (positive to add, negative to remove). This clearly distinguishes it from sibling update tools like update-product and update-variant-price.

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 gives clear prerequisite guidance, telling the agent to use get-product-by-id for the inventoryItem ID and get-locations for the location ID. It does not explicitly state when to avoid this tool or name an alternative, but the context is clear enough for selecting 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?

With no annotations, the description carries the burden of disclosing behavior. It does state the outcome (a discount code customers can enter at checkout) and the discount type/scope, but it omits side effects such as admin visibility, activation timing based on startsAt, duplication behavior, or what happens after creation.

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?

One tight, front-loaded sentence with no filler. Every clause adds relevant context: the action, the discount type, the scope, and how the code is used.

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?

The description is adequate for selecting the tool and understanding its core effect, but with no annotations and no output schema it leaves gaps: no indication of the response/return value, no prerequisites, and no warnings about duplicate or conflicting codes. For a 7-parameter mutation, this is a minimal but not fully complete 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 description coverage is 100%, so the schema already documents all seven parameters and defaults. The description adds no parameter-level details beyond the 'percentage or fixed amount' distinction, which is already expressed by the valueType enum.

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 a specific verb-resource pair ('Create a basic discount code') and immediately defines the scope: percentage or fixed amount off the whole order, entered at checkout. This clearly differentiates from sibling tools like update-product or adjust-inventory.

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 word 'basic' implies this tool is for simple, order-level discounts, but it never explicitly states when to use it versus alternative discount-creation flows or when not to use it. No exclusions or alternative tools are mentioned, leaving usage context to be inferred.

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?

With no annotations provided, the description carries the transparency burden. 'Get' plus 'profile along with their most recent orders' conveys a read operation and a scoped result, but it does not specify how 'recent' is defined, what fields the profile contains, or what the combined response looks like. It is minimally transparent but lacks behavioral depth.

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 entire description is one sentence that front-loads the primary resource and scope. There is no filler or redundant restatement of the tool name, making it appropriately concise and 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?

The tool has only two well-documented parameters and no output schema or annotations, so invocation basics are covered. However, the description does not explain the ordering rule behind 'most recent', the shape of the profile, or how profile and orders are combined, leaving an agent to infer important response details.

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?

The input schema already documents both parameters fully: customerId describes accepted ID forms and limit describes min, max, default, and purpose. The description's phrase 'most recent orders' adds mild context for why limit matters, but it does not add significant parameter meaning beyond the schema, so the 100% coverage baseline applies.

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 concrete verb and resource: 'Get a customer's profile along with their most recent orders.' It clearly distinguishes this tool from siblings like get-customers, get-orders, and get-order-by-id because it combines a customer profile with customer-scoped recent orders.

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 implies when to use the tool: when you need both a customer's profile and their recent orders. However, it never explicitly names alternatives or says when not to use it, so an agent must infer the boundary against sibling tools like get-customers and get-orders.

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?

With no annotations provided, the description carries the burden of behavioral disclosure. It does reveal that the tool lists data and supports query syntax like 'orders_count:>5', which is useful, but it doesn't mention pagination, ordering, response shape, or other behavioral details.

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?

One sentence, front-loaded with the action and object, and the parenthetical examples earn their place by clarifying the search syntax. There is no redundant or filler content.

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 list tool with two optional parameters and no output schema, the description gives enough information to invoke it correctly. It could be richer with return-format or pagination details, but those are minor for this low-complexity tool.

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?

The input schema already covers both parameters, so the baseline is 3. The description adds value by clarifying that searchQuery can match name, email, phone, or structured queries like 'orders_count:>5', going beyond the schema's simpler 'email address or name' example.

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 'List' and the resource 'customers', making the tool's purpose immediately clear. It also notes the optional filtering capability, distinguishing this customer-listing tool from sibling order- and product-related tools.

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 clearly establishes when to use the tool: when you need to list or search customers. It doesn't explicitly name alternatives or exclusions, but the context is clear enough given that no similar customer-listing sibling 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?

No annotations are provided, so the description carries the burden. The verb 'List' implies a read-only, non-destructive operation, but the description does not disclose output format, pagination, or any other behavioral details. For a simple list operation with no parameters, this is adequate but not rich.

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 is a single well-formed sentence that front-loads the main action and then provides the key motivating context about location IDs. There is no wasted text.

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 zero-parameter list tool with no output schema and no annotations, the description is complete. It states what is listed and why the output matters, connecting directly to the adjust-inventory sibling tool.

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?

The tool has zero parameters and an empty input schema, so the schema coverage is effectively complete. The description adds no parameter details, but none are needed. Baseline for zero-parameter tools is 4.

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 and resource: 'List the store's inventory locations.' It clearly identifies what the tool returns and distinguishes it from sibling tools like get-products, get-orders, and get-customers. Mentioning that location IDs are needed for inventory adjustment gives additional purpose context.

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 gives clear context by stating that location IDs are needed to adjust inventory, which tells the agent when to call this tool. It does not explicitly discuss when not to use it or name alternatives, but the intended use case is well implied.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It does share what the response includes (line items, shipping address, totals), which is useful, but it does not mention behavior on missing/invalid order IDs, authorization requirements, or any rate limits. It is adequate but not thorough.

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 is a single, front-loaded sentence with no filler. Every word adds value: the action is first, the resource is bounded, and the return details are listed succinctly.

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 one-parameter read operation, the description plus schema supply what an agent needs: how to identify the order and what to expect in the response. It could be more complete by explicitly differentiating from get-orders, but this is a minor gap given the clarity of 'a single order' and the orderId parameter.

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?

The schema covers the only parameter, orderId, with a description that includes accepted formats. Since schema description coverage is 100%, the baseline is 3 and the description adds no additional parameter-level meaning 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?

The description clearly states the action ('Get full details') and the resource ('a single order'), and specifies what is included (line items, shipping address, totals). This distinguishes it from sibling tools like get-orders, which lists multiple orders, and get-product-by-id, which targets a different resource.

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?

Usage context is implied by the phrase 'a single order' and the required orderId parameter, making it evident this tool is for fetching one specific order. However, there is no explicit guidance about when to use this instead of get-orders or any other alternative, leaving some inference to the agent.

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?

With no annotations provided, the description carries the full burden of disclosing behavior. It clearly conveys a read-only list operation and mentions 'recent' as a scoping behavior, but it does not clarify what 'recent' means, whether pagination affects completeness, or what fields the returned orders include.

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?

A single sentence that front-loads the core purpose ('List recent orders') and then packs useful filter examples with no wasted words.

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 two-parameter list operation with no output schema and no annotations, the description covers the main intent and filter capabilities well. It is slightly incomplete only in not defining the recency window or the response shape, but it is sufficient for an agent to call the tool correctly in most cases.

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?

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds meaningful value by giving concrete searchQuery examples beyond the schema's single example, such as financial_status, created_at comparisons, and order name syntax.

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 ('List'), a clear resource ('orders'), and immediately signals optional filtering with concrete Shopify search query examples. This clearly distinguishes it from get-order-by-id, which is a single-order lookup.

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 context of listing recent orders with optional filters is clear, but the description never explicitly says when to choose this over get-order-by-id or get-customer-orders. The usage is implied by the list-oriented phrasing, but no alternatives or exclusions are named.

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?

No annotations are provided, so the description carries the behavioral disclosure burden. The verb 'Get' implies a non-mutating read operation, and listing the returned categories adds some clarity. Still, it does not address error/not-found behavior, authorization needs, or response shape beyond the listed fields.

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 is a single efficient sentence that front-loads the core purpose and immediately adds useful detail about the returned content. There is no filler or redundant restating of the tool name.

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 one-parameter read operation, the description plus schema covers the essential invocation needs: what the tool returns and how to specify the product. It is slightly incomplete because it omits not-found/error behavior and does not explicitly route users to get-products for listing, but the low complexity makes this a minor gap.

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?

The input schema already fully documents the single parameter, including both acceptable ID formats (numeric or gid://shopify/Product/...). Schema description coverage is 100%, so the description itself adds no parameter-level meaning. Baseline 3 is appropriate.

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 clearly states a specific verb ('Get') and resource ('single product') and identifies the included detail categories (description, images, variants). This distinguishes it from sibling list tools like get-products by signaling a targeted, single-item lookup.

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 tool name and 'single product' wording imply usage when a specific product ID is known, and get-products is the obvious sibling for listing. However, the description never explicitly states when to prefer this tool over get-products or what conditions make it the right choice.

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?

No annotations are present, so the description carries the full burden. It discloses the optional filtering behavior and provides query examples, and 'List' implies a read-only operation. However, it does not mention pagination, default limit behavior, or any potential side effects, leaving some behavioral traits unspecified.

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?

A single, front-loaded sentence states the main action first ('List products') and then the optional filter. It contains no redundant words and efficiently conveys the tool's primary purpose.

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 two-parameter list tool with fully described parameters, the description is largely adequate. It covers the operation and search behavior, but since there is no output schema or annotations, it does not explain return format or pagination details, which would make it fully complete.

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

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

Input schema coverage is 100%, so the baseline is 3. The description adds value by giving a distinct extra example ('tag:sale') and clarifying that the query can be a title fragment, status, or tag, which goes slightly beyond the schema descriptions.

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 'List' with a clear resource 'products from the Shopify store', making it obvious this tool retrieves multiple products. This distinguishes it from siblings like get-product-by-id (single product) and update-product (mutation).

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 does not say when to use this tool versus alternatives such as get-product-by-id, nor does it mention any exclusions or prerequisites. While 'List' implies a collection context, there is no explicit guidance on choosing between this and other product-related tools.

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?

No annotations are present, so the description carries the full burden. The word 'Get' implies a read-only operation and the listed fields indicate what will be returned, but the description does not explicitly state that data is never modified or mention authentication/error behavior. For a simple getter this is adequate but not rich.

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 is a single sentence with no filler. The action, target resource, and key output fields are all front-loaded, and every word contributes meaningful information.

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 parameterless getter, this definition is complete. It states the connected-store context and enumerates the returned fields, and no output schema is needed to understand these simple scalar values.

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?

The tool has zero parameters, so the baseline of 4 applies. The description's field list (name, domain, currency, plan) describes response content rather than parameters, which is appropriate since there is nothing for the caller to configure.

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 ('basic information about the connected Shopify store') and enumerates the exact fields returned (name, domain, currency, plan). This clearly distinguishes it from sibling resource-specific tools such as get-products and get-orders.

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 makes the context obvious: use it when store-level metadata such as currency or plan is needed. It does not explicitly list alternatives or exclusions, but no sibling tool appears to target store-level info, so the intended usage is clear enough.

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?

With no annotations, the description carries the full burden of disclosing behavior, but it only says 'update' without explaining whether this is a partial update, whether unmentioned fields remain unchanged, what permissions are needed, or what the response looks like. The status enum in the description merely restates schema information.

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 is a single front-loaded sentence with no filler. Every word contributes core information about the verb, resource, and updatable fields, making it easy to scan.

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 mutation tool with no annotations and no output schema, this description is too thin. It omits required behavior context such as whether updates are idempotent, whether partial updates are allowed, error cases, or the return value. An agent would need to infer or guess important operational details.

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%, so the schema already documents all parameters including the enum values and the productId format. The description repeats the fields but adds no new semantic meaning beyond naming them. It does not clarify the mapping between the word 'description' and the parameter 'descriptionHtml'.

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 ('Update') and resource ('a product') and names the exact mutable fields: title, description, and status. It is clear enough to distinguish from siblings like get-products (read-only) and update-variant-price (different resource level), though it does not explicitly contrast them.

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 no guidance on when to use this tool versus alternatives. It never mentions update-variant-price or get-products, nor does it state prerequisites like the product must exist. Usage is only implied by the tool name and the presence of sibling tools.

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?

No annotations are provided, so the description must disclose side effects. It conveys that the operation mutates variant pricing, but it does not mention whether the price is overwritten, whether omitted compareAtPrice is cleared or preserved, validation behavior, or permission requirements. For a mutation tool, this is a significant transparency gap.

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 is a single front-loaded sentence with no filler. It states the core operation and the one key option (compare-at price) immediately, earning 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 small mutation tool with 100% schema coverage, the purpose and parameters are adequately documented. However, with no annotations and no output schema, the description does not cover behavioral expectations or return values, leaving a moderate completeness gap that prevents a higher score.

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 documentation covers all four parameters, including the decimal-string format and accepted variant ID forms, so the baseline is 3. The description adds only the optionality of compare-at price, which is already reflected by the schema's required list, so no meaningful new parameter semantics are contributed.

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 states a specific action (Update), a precise resource (product variant), and the target fields (price, optionally compare-at price). This clearly differentiates it from sibling update-product, which operates at the product level, and from adjust-inventory, which handles stock rather than pricing.

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 intended use is implied by the action: call this when a variant's price or compare-at price needs to change. However, it does not explicitly state when to prefer this over update-product or exclude product-level updates, leaving some routing inference to the agent.

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