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

With destructiveHint=true, idempotentHint=false and readOnlyHint=false already declared, the description adds real behavioral value: it explains the downstream effect ('so its items can be fulfilled again') and the implicit default resolution when no id is supplied. It does not address non-idempotency or permission requirements, so it stops at a 4.

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, no waste, and the operational constraint and default resolution are front-loaded where the agent reads them first.

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 destructive mutation with no output schema, the description covers the important ambiguities (preconditions and id resolution) and annotations carry the safety profile. The unexplained 'notify_customer' flag and the absence of any error/edge-case note (e.g., multiple unshipped fulfillments) keep it from being 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?

Schema coverage is only 33% - 'order' is documented and 'fulfillment_id' is bare - so the description must compensate, and it does explain the fallback behavior of the optional 'fulfillment_id'. However, 'notify_customer' is left entirely unexplained in both the schema and the description, so the compensation is incomplete.

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 a specific verb and resource ('Cancels a fulfillment') plus the qualifying scope ('that has not been shipped yet'), which cleanly separates it from sibling tools like cancel_order or create_shipment without needing the schema opened.

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?

It gives the applicability condition (unshipped fulfillment) and the fallback resolution rule when 'fulfillment_id' is omitted, which is genuine usage guidance. It stops short of naming an alternative tool or explicitly stating the when-not case (e.g., what to do instead for a shipped fulfillment), so it misses the top tier.

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 idempotentHint=true, so the safety profile is covered. The description adds real value beyond that: irreversibility and the active-fulfillment precondition. It does not describe the failure mode when the precondition is violated or what the caller gets back.

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 short sentences, front-loaded with the operation, then the confirmation requirement, then the precondition. Every clause carries information an agent needs.

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 destructive mutation, the annotations cover the safety profile and the description covers irreversibility, confirmation, and preconditions. Nothing needed to invoke it correctly is missing.

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% and the single 'order' parameter is documented as 'Order ID or order number'. The description adds no syntax or format detail beyond the schema, so the baseline of 3 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?

States a specific verb and resource ('CANCELS the order') with no ambiguity, and no sibling tool competes for the cancel operation, so the agent can route to it directly.

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?

Gives an explicit call-time requirement ('get explicit confirmation from the user before calling') and a precondition ('must not have active fulfillments'), which is strong contextual guidance. It stops short of naming alternatives, but none exist among the siblings.

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, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuine value by disclosing the money-moving effect and the two implicit-resolution rules (full remaining amount; sole uncaptured payment), which are not visible in the 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?

Two short sentences, effect stated first, default-resolution rules second. No filler; every clause carries 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 three-parameter mutation with no output schema, the description covers the action, its preconditions, and the optional-argument behavior. It could say more about partial captures or error conditions (e.g., over-capture, non-idempotency consequences), but nothing essential for invocation is missing.

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 67% and payment_id has no schema description, so the description compensates by explaining the 'only payment not fully captured' fallback; it also restates the amount default. It does not clarify accepted formats for order (ID vs number) beyond the schema, but overall adds real meaning.

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 a specific verb and resource ('Captures an authorized payment') and clarifies the effect in plain terms ('charges the customer'), which cleanly separates it from sibling refund_payment and mark_order_paid. An agent can identify the operation without opening the schema.

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 'authorized payment' implies the precondition that a prior authorization must exist, and the fallback clauses describe behavior when optional args are omitted. However, there is no explicit statement of when to prefer this over refund_payment/cancel_order or what happens if the payment is not authorized.

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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds nothing beyond restating the name: no state-transition rules (can a cancelled order be completed? does it require payment?), no side effects, no permission requirements.

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 short, front-loaded sentence with no wasted words. It is appropriately sized, though its brevity reflects under-specification rather than disciplined conciseness.

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 with a single well-documented parameter and annotations covering idempotency and safety, the description is minimally adequate. It omits the state-transition semantics an agent would need to call it correctly in edge cases (already-completed or cancelled orders).

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?

Only one parameter ('order') exists and the schema documents it fully at 100% coverage ('Order ID or order number'). Per the rubric, full schema coverage yields a baseline of 3, and the description adds no extra parameter meaning.

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 names a specific verb and resource ('Marks the order as completed'), so the operation is unambiguous. However, it does nothing to distinguish this from sibling mutations like cancel_order or create_fulfillment beyond the obvious wording of the name itself.

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?

There is no guidance on when this tool should be used versus alternatives such as cancel_order, nor any prerequisite (e.g., order must be paid/shipped). The agent must infer usage entirely from the name.

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 cover the safety profile (not read-only, not idempotent, not destructive), and the description adds value beyond them by disclosing the 'reserves stock' side effect and the required payment follow-up. It does not state what happens on failure or whether the reservation is reversible.

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 short sentences, action stated first, follow-up second. Every clause carries information and nothing is padded.

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 mutation with no output schema, the description covers the action, its side effect, and the next step. Missing only edge-case behavior (invalid/already-converted draft, error response), which is a small residual 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?

One parameter at 0% schema description coverage, so the description technically carries the burden, but it says nothing about draft_order_id. The name and string type are largely self-explanatory, so this is a minor gap rather than a blocking one.

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 a specific verb and resource ('turns a draft order into a regular order') so the agent knows exactly what mutation occurs. It does not, however, distinguish itself from the sibling complete_order, which an agent could plausibly confuse with this step.

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 second sentence supplies sequencing guidance by naming the follow-up tool ('Record the payment afterwards with mark_order_paid'), which tells the agent where this fits in the workflow. It still lacks an explicit when-not or a contrast against complete_order/cancel_order.

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 readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral fact that items must belong to published products and that this only creates a draft rather than a real order, but says nothing about permissions, error behavior, or side effects like customer notification.

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 compact sentences, front-loaded with the purpose, then item semantics, then the follow-up step. No filler, though the parenthetical asides make it slightly dense.

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 10-parameter, nested-object creation tool with no output schema and only half the schema documented, the description covers the core (what it makes, how items are specified, how to finalize) but omits how the customer is identified, what region/promo/shipping parameters do, and what the tool returns. Adequate but with real gaps.

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 only 50% across 10 parameters, so the description must carry weight. It usefully explains item identification (variant_id or SKU of published products) and optional custom unit_price, but leaves email/customer_id, region_id, promo_codes, shipping_amount, and the address objects entirely to the 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?

States a specific verb and resource ('Creates a draft order') plus the business context that scopes it (phone/e-mail orders, B2B). It also distinguishes itself from convert_draft_order by making clear this produces a draft, not a live order.

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?

Gives clear context for use (manual/phone/e-mail/B2B orders) and explicitly routes two dependencies: shipping options come from get_store_info and the draft is finalized with convert_draft_order. It does not state any when-not-to-use condition (e.g. don't use for storefront checkout flows), 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.

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

Annotations already declare this is a non-idempotent write (readOnlyHint=false, idempotentHint=false, non-destructive). The description adds genuinely useful behavioral context beyond them: the implicit bulk action of fulfilling all remaining quantities when items is omitted, and the single-location fallback. It does not disclose the customer-visible effect of notify_customer, which is the one notable 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?

Three short sentences, each earning its place, with the core action front-loaded and the two conditional defaults following immediately.

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 non-idempotent mutation with no output schema, the description covers the essential default behaviors an agent must know before calling. Missing only the notify_customer side effect and the failure mode when no location_id is given and multiple locations exist.

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 75% and the description adds cross-parameter semantics the schema cannot express: the default expansion of items to 'everything remaining' and the conditional resolution of location_id. Only notify_customer's customer-facing effect remains unexplained.

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 a specific verb and resource: 'Creates a fulfillment for an order.' An agent can distinguish it from order-mutating siblings like complete_order and cancel_order, though it doesn't explicitly separate itself from the closest sibling create_shipment.

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 conditional default behavior ('Without items...', 'Without location_id...') which implies when the optional parameters can be omitted, but it never states when to prefer this tool over create_shipment or gives any prerequisites/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?

Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=true. The description adds useful default behavior (draft status, default sales channel, default shipping profile) but does not discuss permissions, duplicate-creation risk, or return behavior beyond what annotations cover.

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?

Four efficient sentences, front-loaded with the purpose, then mode guidance, defaults, and ID sourcing. Nothing is repetitive or wasted.

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 21-parameter tool with nested objects and no output schema, the description covers the main creation modes and defaults but omits return values, permission needs, and many optional parameter details. It is adequate for common cases but leaves clear gaps.

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 only 48% schema description coverage, the description compensates by explaining core relationships: prices for a simple product, options plus one variant per combination, and the default status/sales channel/shipping profile. It still leaves many optional parameters unexplained, but it adds real meaning for the main creation paths.

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 a specific verb ('Creates') and resource ('a product with its variants and prices'). It also distinguishes two creation modes (simple vs variant), which sets it apart from sibling tools like create_variant and update_product.

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?

Clearly explains how to use the tool for a simple product versus a variant product, and points to list_catalog for category/collection IDs. It does not name alternatives or when not to use it, but the in-tool guidance is strong.

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 disclose write/non-idempotent/open-world behavior, so the bar is lower. The description adds genuinely useful context the annotations don't: plain dates are interpreted in the reporting timezone, and restriction arrays change the discount's scope. It stops short of covering duplicate-code handling or failure modes.

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?

Front-loaded with the core purpose, then four tight sentences covering the main configuration axes. Dense but every clause carries information; no filler.

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 17-parameter write tool with no output schema, the description covers the high-risk semantics (scope, dates/timezone, free-shipping, automatic vs code). Remaining gaps are advanced fields like extra_rules, which the schema documents adequately.

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 71%, and the description compensates on the ambiguous parts: it explains the applies_to default logic, the free-shipping recipe, and the timezone interpretation of starts_at/ends_at, none of which appear in the schema. Parameters like extra_rules and customer_group_ids are left to the schema, so it isn't exhaustive.

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 a specific verb and resource ('Creates a discount code (or an automatic promotion)') and immediately enumerates the discount forms it produces (percentage/fixed, order/products/shipping). This clearly distinguishes it from the sibling list_promotions, update_promotion and delete_promotion.

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 concrete configuration recipes ('Free shipping = applies_to "shipping", percentage 100') and states that restricting to products/categories/collections scopes the discount, which implies when to use each mode. However, it never names an alternative tool or an explicit when-not condition, so usage is only 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?

The annotations already declare this is a non-destructive, non-idempotent, open-world write. The description reinforces the two-phase workflow but adds little about behavior beyond what the schema states (default to all shipped items). It omits any warning that repeated calls are not idempotent, leaving a behavioral 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?

Four short sentences, each earning its place, with the core action front-loaded and the routing hints following. No filler.

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 5-parameter, no-output-schema tool, the description covers the action, the default scope, and the two follow-up tools well. It leaves out the response shape and any auth/permission requirements, but nothing essential to invoking it correctly is missing.

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 high (80%), so the baseline is 3, but the description adds real value by telling the agent that 'reason_id' values come from get_store_info and that 'items' defaults to every shipped item, tying parameters to their source of truth.

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 a specific action and resource ('Requests a return of order items') and clarifies direction ('the customer is sending them back'). It explicitly distinguishes itself from siblings receive_return and refund_payment, so an agent can route without opening schemas.

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?

Gives explicit when-to-use and when-to-use-something-else rules: call receive_return when the parcel arrives, refund separately via refund_payment. It also notes that omitting 'items' returns every shipped item, so the agent knows the default scope.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds the non-obvious fallback behavior when fulfillment_id is omitted, which is genuine extra context, but it says nothing about notify_customer's effect, validation failures, or what happens when multiple unshipped fulfillments exist.

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 short sentences with no filler; the primary purpose is front-loaded and the fallback rule follows immediately. 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 5-parameter mutation tool with 20% schema coverage and no output schema, the description covers purpose and one default rule but omits the role of the other three optional parameters and any error/precondition behavior. It is adequate to identify the tool but thin for calling it correctly.

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 only 20% and 5 parameters exist, so the description must compensate and largely does not. Only fulfillment_id gets any explanation; tracking_number, tracking_url, and notify_customer (default true) are left entirely undocumented, so the agent must guess whether they are required or what they control.

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 a specific verb and resource ('Marks a fulfillment as shipped') plus the side effect (attaches a tracking number), which is enough to distinguish it from siblings like create_fulfillment and complete_order. It stops short of explicitly naming those siblings, so it falls 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.

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

The description adds one useful conditional rule ('Without fulfillment_id it uses the only unshipped fulfillment'), which is closer to behavioral context than usage guidance. It never says when to prefer this over create_fulfillment or complete_order, nor any prerequisite for shipping, so usage is only 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?

Annotations already declare readOnly=false, openWorld=true, idempotent=false and destructive=false, so the safety profile is covered. The description adds genuinely new behavioral information beyond them: that 'options' must name every product option and that unknown option values are created automatically as a side effect.

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 tight sentences with zero filler; the core action comes first and the non-obvious constraint about 'options' follows immediately. Every clause carries 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 13-parameter creation tool with nested objects, no output schema and openWorld=true, the description covers only the options mechanic. It omits how the required 'prices' and 'stock'/'location_id' pair behave and gives no sense of the created resource, leaving notable gaps for such a wide 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 54%, so roughly half the 13 parameters are undocumented by the schema. The description compensates for the most important one by explaining 'options' semantics ('must name every product option'), which the schema does not say, but says nothing about the required 'prices' array, stock/location_id interaction, or the identifier fields.

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 verb and resource ('Adds a variant to an existing product') and adds a concrete example ('e.g. a new size'), so the agent knows exactly what is created. It doesn't explicitly contrast with siblings like update_variant or create_product, so sibling differentiation is only implied by 'existing product'.

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 'to an existing product' implies a prerequisite (the product must already exist), which is useful context. However, there is no explicit guidance on when to use this over create_product (new product with variants) or update_variant, and no exclusions are stated.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the blast radius (products are retained, only the category association is removed) and mandating user confirmation, though it omits irreversibility and failure behavior for a bad or missing category_id.

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 short sentences, front-loaded with the destructive action and immediately followed by the side effect and the confirmation requirement. No filler.

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 mutation with annotations covering safety and no output schema, the description supplies the essential effect and the user-confirmation rule. Only the parameter's expected value and error conditions are missing, which is a modest 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?

Schema description coverage is 0% and there is one required parameter, so the description carries the burden of explaining category_id. It says nothing about the identifier's format, source (e.g. from list_catalog or save_category), or behavior on an unknown id, leaving the sole parameter undocumented in both places.

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 a specific verb (DELETES) and resource (product category), and the parenthetical clarifies the non-cascading effect, which meaningfully separates it from siblings like delete_product and delete_collection. It does not name an alternative tool directly, 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.

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

"Confirm with the user first" is a process prerequisite, not selection guidance. It never says when to delete a category versus e.g. reassigning products or using save_category to edit, so usage is only implied by the verb.

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 idempotentHint=true. The description adds real value beyond them by disclosing the non-cascading effect (products survive, only membership is removed) and mandating user confirmation — both are behavioral facts the annotations cannot convey.

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 short sentences, front-loaded with the action and its side effect, then the safety instruction. No filler; the capitalized DELETES signals the destructive nature immediately.

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 destructive tool with annotations covering the safety profile and no output schema, the description covers action, side effect, and confirmation requirement. The only gap is guidance on where collection_id comes from.

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?

Only one parameter (collection_id) is required and its name is self-explanatory, but schema description coverage is 0%, so nothing explains the identifier's source or format. The description implies which collection is targeted but adds no syntax or lookup detail.

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 a specific verb (DELETES) and resource (collection) and disambiguates the semantics with the parenthetical that products are not deleted, only unlinked — which matters given delete_product and delete_category siblings. It does not explicitly name an alternative tool, 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.

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

"Confirm with the user first" gives an explicit behavioral precondition, which is useful usage guidance. However, there is no when-to-use vs when-not guidance and no reference to alternative siblings, so usage is only 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond them: it discloses the cascade effects (price lists and promotions targeting the group stop applying) and explicitly states the non-obvious side effect that member customers are preserved.

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 short clauses, each load-bearing: the action, the non-destructive side effect, and the cascade consequence, with the confirmation rule last. No filler.

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 destructive tool with no output schema, the description covers action, side effects, and the required user-confirmation step. The only gap is that the group_id parameter is left entirely undocumented.

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 0% and group_id carries no format, ID-prefix, or sourcing guidance in either the schema or the description. With one undocumented parameter and a low coverage signal, the description should have compensated and does not.

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 verb and resource ('DELETES a customer group') and immediately clarifies scope with '(the customers stay)', which separates it from sibling group tools like save_customer_group and list_customer_groups.

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?

It gives one actionable usage rule — 'Confirm with the user first' — which is meaningful for a destructive tool, but never says when deletion is preferred over alternatives (e.g., leaving the group, or using save_customer_group to modify it) or what prerequisites exist.

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, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuine business consequence – 'its prices stop applying immediately' – which is not derivable from structured fields and is the key risk an agent must convey to a user. It stops short of describing failure behavior on a missing/invalid ID.

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 short clauses, front-loaded with the verb and the consequence before the caution. No filler; the only soft cost is the all-caps emphasis, which is stylistic rather than wasted length.

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 destructive tool with no output schema, the description covers the action, the immediate effect, and a confirmation requirement, while annotations cover reversibility and safety. Missing only edge-case behavior (what happens if the price_list_id does not exist).

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 0%, so the description carries the burden and mentions no parameter at all. The single parameter is a self-explanatory identifier (price_list_id), which limits the damage, but the description adds no semantics or format guidance beyond the name.

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 in caps plus exact resource: it deletes a price list. Among siblings like delete_product, delete_category, delete_collection and delete_variant, the resource noun alone pins down which entity is affected, so an agent can select it without opening the schema.

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?

'Confirm with the user first' is a safety caution, not usage guidance. Nothing tells the agent when to prefer this over save_price_list, list_price_lists, or other deletion tools, nor what preconditions the target must satisfy.

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, but the description adds substantially: the irreversible nature, the cascade to all variants, and the non-obvious caveat that inventory items are only deleted when nothing is reserved. That is exactly the behavioral context an agent cannot get from the structured 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?

Three short sentences, front-loaded with the destructive action and the confirmation requirement; every clause carries information with no padding.

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 destructive tool with no output schema, the description covers confirmation, irreversibility, and cascade semantics. It omits what happens when confirm_title does not match (error vs. silent refusal) and whether the inventory caveat can be overridden, but the essentials are present.

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 only 33%, so the description must compensate. It does explain the confirm_title safeguard and the default behavior of delete_inventory_items, but product_id is undocumented in both places and the exactness requirement for confirm_title largely repeats the schema text. Adequate but with a real gap.

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 a specific verb (DELETES) and resource (product with all its variants), and the scope of the cascade is included. This clearly separates it from update_product among the siblings.

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 instructs the agent to obtain user confirmation before calling and explains the confirm_title safeguard condition, which is real usage guidance. It does not name update_product as the non-destructive alternative, so it stops short of full when-not-to-use routing.

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 idempotentHint=true, so the safety bar is pre-set; the description goes beyond them by disclosing the cascade behavior ('A campaign created for its dates ... is deleted too') and the human-confirmation requirement. That is exactly the kind of consequence detail annotations cannot express.

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?

Four short sentences, each load-bearing: effect, safer alternative, human gate, side effect. The destructive consequence 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.

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

For a destructive mutation with no output schema, it covers impact, cascading deletion, and the confirmation requirement well. The only real hole is the ambiguity between code and promotion_id, which an agent calling this tool could get wrong.

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 0% for two parameters (code, promotion_id) and neither is marked required, so the description must carry the load. It only alludes to 'the code' as the identifying handle and never explains what promotion_id is, whether one or both must be supplied, or how they interact.

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?

Names a specific verb + resource ('DELETES a promotion') and immediately clarifies the operational consequence ('the code stops working'), which distinguishes it from the sibling update_promotion. An agent can tell exactly what this does without opening the schema.

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 routes the alternative case: 'To pause it, prefer update_promotion with status inactive', and adds a procedural prerequisite ('Confirm with the user first'). Both when-to-use and when-not-to-use are stated, not 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it states the operation is irreversible, discloses a side effect (the inventory item is deleted by default) plus the condition that limits it (only when nothing is reserved), and defines the confirmation contract. This is exactly the extra behavioral context annotations cannot carry.

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 sentences, zero filler, and the destructive verb and irreversibility are front-loaded before the parameter mechanics. Every sentence carries distinct information (scope, safety, confirm contract, side effect).

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 destructive single-resource delete with no output schema, the description covers what an agent actually needs: irreversibility, the human-confirmation requirement, the exact confirm value, and the conditional inventory side effect. The annotations handle the safety profile, so no material gap remains.

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 only 25% (only 'confirm' is documented), so the description must compensate. It restates the confirm semantics (SKU, or title when no SKU) and, more usefully, explains the meaning of the undocumented delete_inventory_items flag: on by default, deleting the inventory item only when nothing is reserved. product_id and variant_id remain unexplained, keeping this short of a 5.

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 first line gives a specific verb and a precisely scoped resource: 'DELETES one variant of a product.' The singular scope ('one variant') cleanly separates it from delete_product, delete_category, delete_collection, and delete_promotion in the sibling set, so an agent can route by resource without further inference.

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?

It provides one concrete operational rule ('confirm with the user first'), which is real usage guidance for a destructive call. However, it never names an alternative (e.g. update_variant or setting status instead of deleting) or states a when-not-to-use condition, so the routing guidance is implied rather than explicit.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing what is returned (addresses, groups, counts, total spent, recent orders), which is needed since there is no 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?

One tight sentence with no filler, and the resource is front-loaded. It is appropriately sized for a simple single-parameter read, though the parenthetical enumeration is slightly dense.

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?

With no output schema, the description compensates by naming the return contents, and annotations cover the safety profile. For a one-parameter read tool it is nearly complete, missing only a note about error/not-found behavior.

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 single customer_id parameter (with the 'cus_…' format hint) is fully documented in the schema. The description adds no additional parameter semantics beyond that, making the baseline 3 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?

States a specific verb+resource (get customer) and enumerates the detail returned: addresses, groups, order history. It implicitly distinguishes itself from the sibling list_customers by being a single-customer detail call, but never names that sibling explicitly.

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 is only implied: 'detail' vs the sibling 'list_customers' suggests this is for one customer rather than enumeration. No explicit when-to-use, when-not-to-use, or alternative is stated.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing the returned payload (payments including captures and refunds, fulfillments, tracking numbers, returns), which is real behavioral value given there is no 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?

Two tight sentences with no filler: the scope and returned contents come first, the accepted identifier formats second. Every clause 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?

With no output schema, the description usefully compensates by enumerating what comes back, and the single required parameter is fully documented in the schema. Only minor gaps remain, such as what happens for an unknown or deleted order.

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% and the schema already states the parameter accepts an order ID (order_…) or order number, so the description's identical statement adds nothing beyond structured data. Baseline 3 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 gives a specific verb+resource ('Full order detail') and enumerates the payload contents (line items, addresses, payments, fulfillments, tracking, returns), which makes the tool's scope unambiguous. It does not name the sibling list_orders as the contrasting option, so sibling differentiation is only implied by the word 'Full'.

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 is implied: fetch the complete record for a single order when you already have its ID or number. There is no explicit statement of when to prefer this over list_orders or update_order, and no preconditions or error behavior (e.g., order not found) are mentioned.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds that the response is a full detail payload enumerating related entities, but says nothing about not-found/error behavior or how the linked entities are shaped.

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 dense sentence, front-loaded with the resource name followed by the payload contents; no filler. The long field list is justified since there is no output schema, though it reads as a comma dump rather than structured 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?

With no output schema, the description's enumeration of returned fields is the only source of return-value information and it covers the main ones. Single-parameter tool with annotations covering safety, so little else is needed, though routing guidance against list_products is absent.

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% and there is a single required product_id with its format documented in the schema, so the baseline of 3 applies. The description adds no further meaning about the identifier beyond what the schema 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 a specific verb+resource ('Product detail') and then enumerates the data it returns: variants, prices, inventory items, options, categories, collection, tags, images, sales channels. That clearly separates it from list_products and update_product, though no sibling is named explicitly.

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 no when-to-use guidance, no prerequisites, and never mentions the alternative siblings (list_products for browsing, update_product for changes). The detail-fetch use case is only inferable from the name and the field list.

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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine context beyond that by enumerating the payload categories returned, which is valuable since there is no output schema. It stops short of detailing structure or shape, keeping it at a 4.

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, zero filler. The return contents come first and the usage hint second, which is the right front-loading for a discovery tool.

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?

With no output schema present, the description carries the burden of describing return values and does so by listing each category. Combined with annotations that cover the safety profile, an agent has everything needed to call this correctly.

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 takes no parameters, so there is nothing to document and the baseline of 4 applies. The description correctly implies a zero-argument, whole-store lookup.

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 gives a specific verb ('Returns') and enumerates the exact resource categories (regions/currencies, sales channels, stock locations, shipping options/profiles, return/refund reasons). No sibling tool in the list exposes store configuration, so an agent can immediately distinguish this from the order/customer/product CRUD 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?

It states clear usage context: 'A good first call to learn the IDs other tools need,' which tells the agent to invoke this up front for ID discovery. It does not name any exclusion or alternative, but for a read-only metadata tool there is no meaningful competing sibling to route away from.

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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description usefully adds that categories carry their parent so the tree can be rebuilt, but says nothing about pagination, result size, or what happens when a section is empty.

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 tightly packed sentence that leads with the returned resources and uses the parenthetical only to justify why parent data matters. No filler, though the four-resource list plus aside is slightly dense.

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?

With no output schema, the description does much of the work by naming the returned entity types and their IDs, which is good. However, it omits the existence of the text filter and any indication of result shape or volume, leaving gaps for a catalog-listing 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?

Schema description coverage is 100%, so the single 'q' parameter (full-text filter applied to every section) is already fully documented. The description adds no extra meaning about filtering behavior, so the baseline 3 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 enumerates the concrete resources returned (product categories, collections, tags, product types), which clearly separates it from siblings like list_products or list_customers. The retrieval verb itself is only implied by the tool name, but the resource scope is unambiguous.

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 'with IDs for other tools' implies the intended workflow (fetch IDs to feed save_category, delete_category, save_collection, etc.), but there is no explicit when-to-use or when-not-to-use statement, nor any mention of an alternative tool.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only a domain definition and does not disclose pagination behavior, default result size, filtering behavior, or any permission constraints 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?

The description is a single short sentence with no filler. It is front-loaded with the entity definition, though the sentence is so minimal that it omits the tool's action entirely.

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 list tool with q, limit, and offset parameters and no output schema, the description is missing the core action, filtering semantics, and pagination context. The annotations cover read-only safety, but the description does not give an agent enough to invoke or interpret results confidently.

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 67%, with the q search parameter undocumented in the schema. The description adds no meaning for q, limit, or offset, so it does not compensate for the coverage gap. An agent gets no help understanding what q searches or how pagination behaves.

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 defines what a customer group is (e.g. B2B, VIP) but never states the tool's action. It does not say it lists or retrieves customer groups, and it does not distinguish this tool from save_customer_group or delete_customer_group. The name and title carry the actual purpose, so the description itself is largely tautological domain 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?

There is no when-to-use guidance and no mention of alternatives such as list_customers or save_customer_group. The phrase 'used by price lists and promotions' describes the entity's domain role, not when an agent should call this listing tool.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds the scoping constraint (name/email/company, optional group) but says nothing about result caps, pagination behavior, or what happens when no filters are supplied.

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 efficient sentence with the primary search capability front-loaded. Nothing is wasted, though it is short enough that the missing usage guidance reads as omission rather than brevity.

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 6-parameter read-only list tool with no output schema, the description covers the search intent but leaves pagination, the has_account filter, and default result behavior unaddressed. Minimum viable, with clear gaps.

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 83%, so the schema already documents q, limit, offset, group_id and has_account. The description restates the q/group_id semantics but adds no format or interaction detail (e.g., whether email overrides q, or that has_account is a guest/registered switch).

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 names a specific verb (searches) and resource (customers) plus the searchable fields, so an agent can tell it apart from get_customer's single-record lookup. It does not explicitly say it is the list/browse counterpart, but the scope is unambiguous.

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?

'Optionally within a customer group' hints at the group_id filter but there is no when-to-use guidance, no mention of get_customer for single-record lookup, and no explanation of how the multiple filter parameters combine.

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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral detail by enumerating the returned quantity fields (stocked, reserved, available) and clarifying that the threshold filters rather than sorts, but says nothing about pagination defaults or result limits beyond what the schema states.

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 tight sentences, front-loaded with what the tool returns before the optional filter modifier. No filler or repetition.

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 read-only list tool with no output schema and fully documented parameters, this covers what an agent needs: the payload shape and the one non-obvious filter. Missing only pagination/ordering guidance, which the schema partially implies via limit/offset.

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 all six parameters are already documented, including that low_stock_threshold compares against available quantity — which the description simply restates. Baseline 3 for high coverage with no meaningful added meaning.

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 names the resource (inventory items with per-location stocked/reserved/available quantities) and a filtering behavior, so an agent knows exactly what data comes back. It stops short of an explicit 'list' verb and never distinguishes itself from list_products, a close sibling in the same catalog.

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?

There is no statement of when to use this tool versus list_products or get_product, and no prerequisites or exclusions. The only usage signal is implicit in the low_stock_threshold sentence.

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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: results are ordered newest-first, and date filter inputs are YYYY-MM-DD interpreted in the reporting timezone — neither of which the schema states (created_from/created_to say only 'From date, e.g. ...'). It stops short of describing result size or pagination behavior.

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, no filler. The core behavior and sort order come first, then the filter list — exactly the order an agent needs them.

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 9-parameter, zero-required read tool with no output schema, the description covers ordering, date format/timezone, and filter categories. It leaves default behavior when no filters are supplied and result-set/pagination implications of limit/offset to the schema, 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?

Schema coverage is 78%, and the description fills the most important gaps: it supplies the timezone semantics for the date range parameters and confirms that 'customer' maps to the otherwise undocumented customer_id field. It also groups status vs payment_status vs fulfillment_status for the reader, though it adds no enum values beyond the 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?

States a specific verb and resource ('Lists orders') plus the sort order ('newest first') and the full set of filter dimensions. The list-vs-get distinction against the sibling get_order is implied rather than named, and no sibling is explicitly referenced, so it falls short of the top band.

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 enumeration of available filters implies the browsing/search use case, but there is no explicit when-to-use guidance and no mention of the closest alternative, get_order, for retrieving a single order. Usage is inferable but not stated.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful domain context (what 'sales' and 'override' price lists mean) and notes that supplying price_list_id returns the list with all its prices, but it says nothing about pagination behavior, default result counts, or ordering despite limit/offset being present.

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, no filler, and the domain definitions are front-loaded before the price_list_id behavior. It is economically sized for the information it carries, though the parenthetical example is slightly verbose.

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?

There is no output schema, so the description carries return-shape burden; it partially meets this by noting that price_list_id returns the list with all its prices. But the default listing response, q/status filtering, and pagination semantics are unaddressed, leaving gaps for a 5-parameter listing 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?

Schema coverage is only 40%: limit and offset are documented in the schema itself, but q and status have no description anywhere. The description explains price_list_id's dual role (filter vs. single-fetch), which is real added value, but it leaves q and status semantics entirely unexplained. Partial compensation for a real gap.

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 resource (price lists) and clarifies that it covers two kinds -- sales (temporary discounts) and overrides (customer-group/B2B prices) -- which meaningfully distinguishes it from siblings like save_price_list and list_promotions. The implicit 'list' verb comes from the name, not the text, so it's clear but not maximally explicit.

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?

It implies a mode switch: pass price_list_id to fetch one list with its prices, otherwise list them. However, it never states when to prefer this tool over list_promotions, list_catalog, or get_product for pricing data, and offers no exclusions or prerequisites. Usage is inferable but not spelled out.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that variants/SKUs are returned alongside products, but says nothing about pagination behavior, ordering, or result size beyond what the schema states. Reasonable but thin given annotations carry most of the load.

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 compact sentences, front-loaded with the core purpose followed immediately by filtering capability. No filler or 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 read-only list tool with annotations covering the safety profile and no output schema, the description gives enough to call it correctly: purpose, filter dimensions, and variant inclusion. Minor gaps around pagination and result ordering keep it from a 5.

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 only 29% (just limit/offset), but the description names the five filter dimensions that map directly to the otherwise-undocumented q, status, collection_id, category_id, and tag_id parameters. It compensates for the coverage gap by identifying what can be filtered, though it omits ID-format expectations.

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 a specific verb (Lists) and resource (products) and adds scope detail that it includes variants/SKUs, which single-product tools like get_product do not. It does not explicitly differentiate itself from adjacent collection tools such as list_catalog or list_inventory, so an agent must infer the boundary.

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?

It enumerates the filter dimensions (full-text, status, collection, category, tag), which implies how to narrow results, but gives no explicit when-to-use guidance or alternatives (e.g., use get_product for a single product, list_inventory for stock). Usage is implied rather than stated.

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 readOnlyHint=true and openWorldHint=false, so the safe-read profile is covered. The description adds that returned promotions carry value, conditions, usage and validity, which is useful content-level context, but says nothing about pagination or ordering behavior.

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 efficient sentence with no padding. It is well sized for a simple list tool, though it front-loads resource content rather than the list action.

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 read-only list tool with complete parameter schema and safety annotations, little more is strictly required. However, with no output schema, the description could say more about the shape of returned promotions, and there is no routing guidance among the many list_* siblings.

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 every parameter (q, code, limit, offset) is already documented in the schema. The description adds no filter syntax or usage detail beyond that, so the baseline 3 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 adds real content beyond the name/title by clarifying that 'promotions' covers both discount codes and automatic promotions, and lists the attributes involved (value, conditions, usage, validity). It has no verb, but the resource scope is unambiguous.

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 guidance on when to use this vs. siblings like list_price_lists or get_product, and no note of when to filter with 'code' vs. 'q'. The agent must infer usage entirely from the name and schema.

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 the safety profile (not read-only, non-destructive, idempotent, open-world), so the bar is lower. The description adds the useful auto-selection behavior when fulfillment_id is omitted, but does not disclose side effects such as whether a shipping/delivery notification is sent or what error condition arises with ambiguous fulfillment selection.

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 tight sentences, zero filler, and the fallback behavior is front-loaded. Every clause 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 mutation tool with no output schema, the description covers the main ambiguity (optional fulfillment_id) but leaves the caller without knowledge of return values, side effects, or behavior when multiple undelivered fulfillments exist. Adequate but with clear gaps.

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 50% — 'order' is documented but 'fulfillment_id' is not. The description compensates by explaining exactly what omitting fulfillment_id does, which is semantic information the schema lacks. This is a genuine addition beyond structured data.

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 a specific verb ('Marks') and resource ('a fulfillment as delivered'), which clearly separates it from siblings like create_fulfillment and cancel_fulfillment. It does not name a sibling explicitly, but the resource is specific enough to distinguish.

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 a conditional rule — omit fulfillment_id to target the single not-yet-delivered fulfillment — which is real usage guidance implied for the caller. It stops short of saying when to prefer this over alternatives like cancel_fulfillment or what error/behavior occurs if multiple undelivered fulfillments exist.

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 cover the safety profile (non-read-only, idempotent, non-destructive, open world). The description adds real behavioral value beyond them: it discloses the side effect that orders lacking a payment collection (e.g. converted drafts) will have one created for the outstanding amount. It does not mention required permissions or what amount is ultimately recorded.

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 tight sentences, front-loaded with the primary action and followed by the edge-case behavior. No filler, though the second sentence is dense and could be split for clarity.

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 mutation with no output schema, the description covers the core action, the trigger scenario, and the notable side effect. Return behavior and permission requirements are unstated, but annotations carry the safety profile and the tool is simple enough that this is 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?

Schema description coverage is 100% and the single 'order' parameter is already documented as 'Order ID or order number'. The description adds no further syntax or format detail, so the baseline of 3 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 gives a specific verb+resource: 'Records a manual payment ... for the order's unpaid payment collection', and the parenthetical examples (bank transfer, cash on delivery) pin down the exact scenario. It does not explicitly name the closest sibling, capture_payment, so an agent must infer the manual-vs-automatic distinction.

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 examples imply when this is appropriate (offline/manual settlement rather than a gateway capture), but there is no explicit when-to-use or when-not-to-use statement and no named alternative such as capture_payment or complete_order. Usage must be inferred from the examples.

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 openWorldHint=true, but the description adds unusually valuable context beyond them: which method performs which mutation, that api-keys/users/invites writes are blocked, that changes should be confirmed with the user, and that amounts use major units. These are non-obvious constraints an agent could not infer from the 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?

Front-loaded with the tool's role, then alternative routing, then method/field/unit conventions, then the safety block. Five dense sentences, each carrying a distinct operational fact with no filler.

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 an open-world proxy with no output schema, the description covers routing, mutation semantics, blocked resources, and value conventions well. The one gap is response behavior (error shape, pagination, partial failures), which matters for a catch-all endpoint caller but is not addressed.

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 75% schema description coverage the schema already documents path, body, and query. The description adds semantics the schema does not: the '+field' / '*relation' modifiers for the fields query key and the major-unit convention for amounts. It does not document the method enum's practical implications further, keeping it just short of a 5.

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 a specific verb and resource ('Calls any Medusa v2 Admin API endpoint directly') and immediately bounds the scope with concrete example paths. It explicitly distinguishes itself from the ~40 sibling tools by positioning itself as the fallback for uncovered endpoints.

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?

Gives explicit when-to-use ('anything the other tools do not cover') and when-not ('Prefer the dedicated tools when one fits'), plus a concrete confirmation rule for destructive calls. An agent has no ambiguity about routing between this and domain-specific siblings.

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 cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), and the description adds a key side effect beyond them: received items are restocked. It does not, however, disclose the notify_customer behavior or permission requirements.

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, front-loaded with the core action and consequence, then two tightly-scoped conditional clauses. 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 mutation tool with no output schema, the description covers the primary effect and the two most important defaulting rules. Only the notify_customer side effect and the role of 'order' vs 'return_id' resolution are left unaddressed.

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 60% schema coverage, the description usefully explains the defaulting behavior of 'items' and 'return_id'. It leaves the semantics of 'note', 'order', and 'notify_customer' (default true) to the schema/reader inference.

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 a specific verb+resource ('Records that returned items arrived') and adds the concrete consequence ('they go back to stock'). This clearly distinguishes it from the sibling create_return, though it never names a sibling explicitly.

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 conditional rules for two parameters (defaults when 'items' or 'return_id' are omitted), which is helpful operational guidance, but says nothing about when to prefer this over create_return or other return-related siblings.

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 flag destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description reinforces this with 'Irreversible' and adds genuine context beyond the annotations: the automatic payment-selection behavior when payment_id is absent. It does not disclose what the call returns or whether partial refunds against a payment are constrained.

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 short sentences, each earning its place: the destructive/confirmation warning is front-loaded, followed by the default-resolution rule and the value-source pointer. Zero filler.

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 destructive mutation with no output schema, the description covers irreversibility, a user-confirmation requirement, parameter defaulting, and reason-code lookup. Only the response shape and any refund-eligibility constraints are left implicit.

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 only 40%, so the description must compensate, and it does for the two undocumented functional params: payment_id's defaulting behavior and where refund_reason_id values come from (get_store_info). The 'note' param remains unexplained in both schema and 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?

States a specific verb (refunds), the resource (money/customer payment) and the mechanism (through the payment provider). It is unambiguously distinct from siblings like capture_payment, cancel_order, or create_return, with no overlap.

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?

Gives concrete pre-call guidance ('confirm the amount with the user') and an explicit fallback rule for when payment_id is omitted. It also routes the agent to get_store_info for valid refund reasons. It stops short of naming alternative tools for adjacent scenarios (e.g., when a refund is not possible and a return/cancel is appropriate).

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 and openWorldHint=false, and the description adds real behavioral context: canceled and draft orders are excluded, amounts are per-currency (so no cross-currency rollup), and a time series is produced. It stops short of disclosing performance, limits, or empty-range behavior.

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 tight sentences, front-loaded with the metric list and followed by the important scoping caveats. No filler or 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?

With no output schema, the description usefully enumerates the returned metrics and the exclusion rules that determine the numbers, which is the key information an agent needs. It omits how currency grouping interacts with the totals and what the top-products ordering is based on.

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 83%, so the schema already documents from/to/top_n/timezone/only_paid. The description only indirectly echoes parameters by mentioning day/week/month buckets and top products, and does not clarify only_paid or timezone semantics beyond the schema. 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?

States a specific verb (computes) and resource (sales report) and enumerates the exact metrics returned: order count, revenue, AOV, units, unique customers, time series, and top products. This makes it clearly distinguishable from the sibling list/get tools, which return raw entities.

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?

Implicitly signals it is an aggregation tool rather than a record lister, and notes that canceled and draft orders are excluded. However, it never states when to prefer this over list_orders plus manual aggregation, nor any prerequisite or exclusion guidance.

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 idempotent=true, destructiveHint=false and openWorld=true. The description adds meaningful semantics beyond them: updates are partial ('only the given fields'), name is required only on creation, and the call can mutate product associations. It doesn't clarify permissions or what happens to omitted fields on update, but it is well above the annotation-only bar.

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 dense sentences, front-loaded with the mode switch, no filler. Every clause carries information an agent needs.

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 an 11-param, no-required, no-output-schema tool, the description covers the essential decision logic and the side-effect on product associations. Return shape and behavior when category_id is absent/invalid are unaddressed, but the core calling contract is clear.

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 64%, so the schema documents the more subtle params (metadata merge, rank as sibling position, parent_category_id null behavior). The description supplies the critical semantic that category_id switches create vs update, and that add_products/remove_products are side-effect lists, but says nothing about the remaining params (is_active, is_internal, handle).

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 a specific verb+resource (create/update a product category) and disambiguates the two modes by the presence of category_id. It also flags a secondary effect (add/remove products). It doesn't explicitly differentiate itself from the similarly named save_collection or delete_category, but the purpose is unambiguous.

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 a clear branching rule for when to use each mode (no category_id = create, with category_id = update), which is genuine usage guidance. However, it names no alternatives (e.g. delete_category for removal) and states no 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?

Annotations already disclose that this is a non-destructive, idempotent, open-world write, so the safety profile is covered. The description adds one genuinely behavioral fact: 'a product belongs to at most one collection', which warns the agent that adding a product may implicitly move it. It does not explain what happens to title/handle conflicts, or whether removed products are deleted or merely detached.

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 dense sentences, front-loaded with the create/update branch that determines everything else. Every clause earns its place; the only minor cost is that the parenthetical product-membership rule is squeezed in rather than given its own emphasis.

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 dual-mode tool with six parameters, no required markers, and no output schema, the description covers the decision-critical facts: mode selection, the required field for creation, and the product-membership side effect. Gaps are minor — no mention of handle conflicts or validation behavior — and the absence of an output schema excuses return-value detail.

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 only 50%, and the schema marks zero parameters as required, so the description carries real load: it states title is required for creation, and it explains add_products/remove_products by describing the one-collection membership constraint. handle and the update-mode requirements remain undocumented in the description, but it meaningfully compensates for the coverage gap.

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 verb+resource pair (create/update collection) and makes the branch condition explicit: 'Without collection_id creates a collection (title required); with collection_id updates it.' That conditional framing is more precise than the title alone and lets an agent pick the right mode without opening the schema. It does not, however, compare itself to sibling tools such as delete_collection or save_category.

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?

It gives clear routing guidance on the create-vs-update decision, which is the primary ambiguity for a 'save' tool. It also implies product-association usage via add_products/remove_products. It stops short of naming when to avoid this tool (e.g., use delete_collection instead), so no explicit 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?

Annotations declare non-read-only, non-destructive, idempotent, open-world, and the description is consistent with them while adding real value: partial-update semantics (only given fields change) and the create-vs-update switch. It does not disclose error behavior or what happens if customer_id doesn't exist, which for a mutation tool would be the remaining 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?

Two dense sentences, front-loaded with the create/update distinction, with no filler. The second sentence packs three capabilities together, which is slightly run-on but still efficient.

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 10-parameter, nested-object mutation with no output schema and low schema coverage, the description covers the essential decision logic and side effects. It omits failure modes and return behavior, but nothing that would cause a wrong 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 coverage is only 30% across 10 parameters, so the description must compensate, and it does: it clarifies the customer_id gating logic, that email is required for creation, and the roles of add_address, add_to_groups and remove_from_groups. It still leaves some params (phone, company_name, metadata merge behavior) unexplained in prose.

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 a specific verb and resource and, crucially, splits the tool's two modes by the presence or absence of customer_id. An agent immediately knows this is an upsert-style save, not a read or delete, and can distinguish it from list_customers/get_customer siblings.

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?

Gives clear conditional usage: omit customer_id to create (email required), include it to partially update. It does not name alternatives or explicitly say when not to use it (e.g. to fetch a customer), so it stops short of full routing guidance.

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 cover the safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=true), so the bar is lower. The description usefully adds that behavior branches on group_id and that members can be added/removed, but it does not disclose permission requirements, what happens to membership on rename, or whether removing customers has 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 short sentences, zero filler, with the mode-switching rule front-loaded before the secondary capability. Every clause 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 5-parameter, no-required-params mutation tool with no output schema, the description covers the critical decision logic (create vs update, name requirement). It falls short only on permissions, error/partial-update behavior, and the metadata merge semantics, which the schema partially covers.

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 only 60%, and the description compensates by tying group_id to the update path and clarifying that name is only required in the create path. add/remove customers are described loosely ('Can add/remove customers') while metadata is left entirely to its schema 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?

States a specific verb+resource (create/rename a customer group) and distinguishes its two modes via the presence or absence of group_id. It is less explicit about how it differs from siblings like save_customer or list_customer_groups, but the create-vs-update framing is clear.

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 each mode applies (no group_id = create, group_id = rename), which is genuinely useful, but it never names alternatives or states prerequisites/exclusions against sibling tools such as save_customer or delete_customer_group.

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 mutation, idempotency and non-destructiveness, so the bar is lower, and the description still adds real behavioral context: that title is required only on create, that remove_variants drops variants from the list, that 'sale' vs 'override' changes displayed pricing semantics, and that plain dates use the reporting timezone. It stops short of describing auth requirements, partial-failure behavior, or what a successful call returns.

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?

Four tightly packed clauses with no filler, front-loaded with the create-vs-update discriminator and then the sub-operation semantics. Every sentence carries information an agent needs to call the tool correctly.

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 10-parameter mutation tool with no output schema and only 60% schema description coverage, the description covers the operation mode, the two array operations, type semantics and date handling. Gaps remain on customer_group_ids scoping, status behavior on update, and error/partial-apply behavior, so it is strong but not exhaustive.

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 10 parameters at 60% schema coverage, the description compensates by explaining the conditional role of price_list_id and title, the semantics of set_prices and remove_variants, and the sale/override meaning of 'type' plus the timezone convention for plain dates. It leaves customer_group_ids, status, description and starts_at/ends_at removal semantics to the schema, so it does not fully close the coverage gap.

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 the exact verb+resource and disambiguates the dual mode with a concrete rule: 'Without price_list_id creates a price list (title required); with price_list_id updates it.' It also enumerates the sub-operations (set_prices, remove_variants) so an agent can separate this from siblings like set_variant_price or list_price_lists without reading the schema.

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?

It gives clear context for choosing create vs update and for choosing set_prices vs remove_variants within the call. It never names an alternative sibling (e.g. set_variant_price for changing a single variant's price, or list_price_lists/delete_price_list), so routing to competing tools is left to inference.

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 the safety profile (readOnly=false, idempotent=false, destructive=false, openWorld=true), so the bar is lower. The description adds real side-effect context: omitting location_id falls back to the item's only location, and an unstocked item is auto-added at that location. It does not, however, spell out the non-idempotent nature of 'adjust_by'.

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?

Four short sentences, fully front-loaded with the core action first, followed by the quantity mode, the identification modes, and the location fallback. No filler or repetition.

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?

With no output schema, the description must cover behavior; it does describe the write and its auto-create side effect. Minor gaps remain on error/failure behavior and whether the two quantity parameters are mutually exclusive or mandatory.

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 only 20%, so the description carries most of the load: it explains the stocked_quantity/adjust_by mutual alternative and the sku/inventory_item_id identification choice, and clarifies location_id's defaulting behavior. It does not state whether exactly one of the two quantity modes must be supplied (required count is 0).

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 a specific verb and resource with scope: 'Sets the stocked quantity of an item at a location.' It is unmistakably distinct from the sibling read tool list_inventory and from the variant/price tools, so an agent can select it without opening the schema.

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?

Gives clear operational context: absolute 'stocked_quantity' vs relative 'adjust_by', and the id-or-SKU identification choice. It stops short of naming an alternative tool for reading stock levels (e.g. list_inventory) or stating any when-not-to-use condition.

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 readOnlyHint=false, idempotentHint=true and destructiveHint=false. The description adds genuinely useful behavior the annotations do not: all other prices of the variant are preserved, so the agent knows this is a partial, non-clobbering write. It does not state permission requirements or what the response returns, keeping it below a 5.

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 tight sentences with zero filler, and the core operation plus its scope constraint is front-loaded before the format note and the alternative routing. Every clause 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 no-output-schema mutation tool, the description supplies the behavioral context an agent needs: scope of the write, preservation of sibling prices, unit format, and where to go for other price types. Nothing required to invoke it correctly is missing.

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 only 25% (just currency_code), so the description must compensate. It does for the most ambiguous field: 'amount is in major currency units (e.g. 49.99 = 49.99 EUR)', which clarifies the number type that the schema leaves bare. product_id and variant_id remain unexplained in both places, so the coverage is not complete.

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 a specific verb and resource (sets the base price of a variant) plus a scoping qualifier (one currency, base only, no price rules). It also differentiates itself from the price-list path, so an agent can distinguish it from siblings like save_price_list without opening a schema.

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 routes the agent elsewhere for a related but different need: 'For sale or customer-group prices use price lists.' That is a clear alternative-selection rule. It stops short of a full when/when-not treatment (e.g. what to do when the variant already has overlapping price rules), so it is strong but not exhaustive.

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 readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds genuinely non-derived behavior: an address field fully replaces the previous address rather than merging it, which is a partial-overwrite hazard the schema never states (the schema just calls these 'Postal address'). It does not mention permissions, validation failures, or rate limits, but the replacement semantics are the key disclosure and are present.

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, zero filler, with the field scope front-loaded before the update-semantics caveat. Every clause changes how an agent calls the tool.

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 full annotation coverage and no output schema, the description covers what can change and the two non-obvious update rules (partial send, full address replacement). It omits error/edge behavior on a non-existent or completed order, but nothing essential to a correct call is missing.

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 80% schema description coverage the baseline is 3, and the description earns above it by clarifying semantics the schema does not: that updates are partial ('send only what should change') and that no field is required beyond the order identifier. It also signals the email/address/metadata parameter families by name, though the metadata merge-vs-delete rule lives only in the 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?

The description gives a specific verb ('Changes') plus resource ('the order's') and enumerates the exact mutable fields: email, shipping/billing address, and metadata. This scoping implicitly separates it from siblings like complete_order, cancel_order, and get_order without the agent needing to open any schema.

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?

'Send only what should change' is a real invocation guideline for a partial-update tool, and it prevents an agent from resending unchanged fields. However, it says nothing about when to choose this tool over alternatives such as complete_order or cancel_order, and lists no prerequisites (e.g. order must exist, must not be cancelled), so usage is only implied rather than contrasted.

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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description goes beyond them by disclosing two non-obvious behaviors: partial-update semantics (only changed fields are sent) and that list fields (category_ids, tags, images, sales_channel_ids) fully replace prior values rather than appending. That replace behavior is the kind of data-loss nuance annotations do not capture, though it omits permission/return context.

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 written sentences, front-loaded with the core action, followed by the patch instruction and then the list-replace caveat. Every sentence earns its place with no 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 16-parameter mutation with no output schema, the description covers the most important behavioral surprises (patch semantics, list replacement) but omits return behavior, permission requirements, and semantics for roughly half the parameters. It is adequate but not complete for the tool's complexity.

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 only 25%, so the description must compensate and it only partially does so. It clarifies the replace semantics for the four list params and names the field families, but leaves many of the 16 params (weight, subtitle, thumbnail, discountable, shipping_profile_id, description) without added meaning, and does not explain the null-removes-collection behavior.

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 ('Updates product fields') and enumerates the exact field families affected (texts, status, handle, images, collection, categories, tags, sales channels, metadata). An agent can tell it apart from create_product, get_product, and update_variant from the text alone, though it never explicitly names those siblings.

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?

'Send only the fields that should change' is a useful patch-semantics guideline for how to call it, but there is no statement of when to prefer this over create_product, update_variant, or the various set_* siblings, and no prerequisites or exclusions. Usage is implied rather than spelled out.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), so the bar is lower. The description adds that activation/deactivation is done via status and lists what is mutable, but omits partial-update semantics, error behavior, and permission requirements for a mutation tool.

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, zero filler, with the mutability list and the identification method front-loaded. Every clause 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 an 8-parameter optional-field mutation with 50% schema coverage and no output schema, the description covers the what (fields) and the how-to-identify, but says nothing about unspecified fields remaining unchanged, validation constraints (e.g., value > 0, date ordering), or the result. Sufficient to start, incomplete for safe use.

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 only 50%, so the description must compensate. It does: it clarifies that promotion_id or code is used to locate the record and that new_code performs a rename, a meaning absent from the schema, and ties value/usage_limit/dates/status to concrete changes.

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 a specific verb (changes) and resource (a promotion), then enumerates the mutable aspects: status, code, value, usage limit, validity dates. It also distinguishes itself from list/create/delete_promotion by naming the update operation and the identifier fields used to target the record.

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 is implied: use this to modify an existing promotion, identified by promotion_id or code. It does not state when to prefer it over siblings (e.g., delete_promotion for removal) or any preconditions such as needing an existing promotion id. Adequate but not explicit.

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 readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds the scope of mutation (which fields change) but says nothing about partial-vs-full replacement semantics, merge behavior, or validation failures; it is adequate but thin given the lower bar set by 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 compact sentences with zero filler; the positive scope comes first and the routing exception second. Nothing is repeated from the title or schema.

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 an 11-parameter mutation tool with a nested metadata object and no output schema, the description covers the mutation scope, the key field groups, and the price exception. The notable remaining omission is whether unspecified fields are preserved, which matters for an update tool, but nothing essential for correct invocation is missing.

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 only 36%, so the description has to compensate, and it does by grouping the updatable fields (title, SKU, barcodes/ean/upc, inventory tracking/manage_inventory, backorders/allow_backorder, weight, metadata). Only the required identifiers product_id and variant_id go unnamed, which is a minor gap; the remaining semantics like grams and metadata merge are already documented in the 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?

States a specific verb (updates) and resource (variant) and enumerates the mutable field groups: title, SKU, barcodes, inventory tracking, backorders, weight, metadata. It also explicitly separates itself from the nearest sibling by stating that prices belong to set_variant_price, so an agent can route without opening schemas.

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 a clear exclusion rule and names the alternative tool for the price case ('For prices use set_variant_price'). It stops short of broader when-to-use context, such as preferring this over delete_variant/create_variant or noting that it is a partial update, but the routing guidance is explicit and actionable.

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