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

With no annotations at all, the description carries the full burden and does disclose a genuinely non-obvious behavior: media is processed asynchronously and items return as UPLOADED or PROCESSING rather than READY. That prevents an agent from misreporting success. It still omits auth/scope requirements, failure handling for unreachable URLs, and whether re-adding the same URL duplicates media.

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 action, then the async caveat, then the verification pointer. Every sentence contributes information an agent needs; 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 low-complexity 2-parameter tool with no output schema and no annotations, the description covers the action, the URL requirement, the async lifecycle, and the verification path. The main remaining gap is what the call itself returns (media IDs/statuses) and error behavior for invalid or private URLs.

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

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

Schema coverage is 100%, with productId's GID format and originalSource's 'publicly accessible image URL' both documented in-schema, so the baseline is 3. The description reinforces the public-URL requirement for media but adds nothing about the 'alt' field or array semantics 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 ('Attach images to an existing product') and adds a hard constraint ('by public URL') that distinguishes it from any upload-from-file or update-product tool. Among the many product siblings (create-product, update-product, manage-product-variants, get-product-media), it is unambiguous which job this performs.

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 to get-product-media as the follow-up verification step once media is added, which is real alternative-aware guidance. It does not say when *not* to use it (e.g. that media cannot be attached to a nonexistent product) or whether it appends rather than replaces existing media, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It hints at the state change (draft becomes a real order) but says nothing about irreversibility, required scopes, what happens to payment when no gateway is passed, whether inventory is reserved, or side effects like order confirmation. A finalization mutation tool needs more than this.

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 effect, with no filler or repetition. 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 mutation with zero annotation coverage and no output schema, the description omits too much: what is returned (presumably the created order), failure modes (draft already invoiced, missing inventory), and irreversible consequences. The schema covers inputs, but the behavioral contract is under-specified.

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%, with both parameters documented including a GID example format, so the baseline of 3 applies. The description adds only "optionally specify a payment gateway", which the schema already conveys via the empty required list and "(optional)" note.

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 ("Complete a draft order") and adds the concrete effect ("converting it into a real order"), so an agent can predict the outcome without opening the schema. It does not name sibling tools such as create-draft-order or order-mark-as-paid, so differentiation is left implicit.

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 versus the draft-order siblings or when not to (e.g. an already-completed order, an unpaid draft). "Optionally specify a payment gateway" is a parameter remark, not usage 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?

With no annotations, the description carries the full burden and delivers almost nothing: it does not disclose whether email uniqueness is enforced, whether a duplicate returns an error or silently creates, whether any fields are required, or what the created object looks like. The only inference an agent can safely make is that this is a mutation, which comes from the verb rather than from any stated 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?

The single sentence is front-loaded and free of waste, but its brevity is under-specification rather than economy. There is nothing to trim, yet nothing has been invested either.

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 nine-parameter mutation tool with no annotations, no output schema, and 0% schema coverage, the description should explain required vs optional fields and side effects such as duplicate handling. It explains none of this, leaving the agent unable to call the tool correctly without guessing.

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% across nine parameters, including non-obvious ones like metafields (namespace/key/value/type tuples), taxExempt, and the addresses array with provinceCode/countryCode. The description supplies zero parameter meaning, so an agent gets no information about formats, constraints, or which fields matter.

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 ('Create a new customer'), which is immediately distinguishable from its siblings get-customers, update-customer, delete-customer, and customer-merge. It does not explicitly name or contrast with those siblings, but the verb+resource pairing alone 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 versus update-customer (for existing records) or customer-merge (for deduplication), which is a realistic confusion point given the sibling set. No prerequisites, no mention that all nine fields are optional, so an agent cannot tell what a minimally valid call looks like.

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

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

No annotations are provided, so the description carries the full behavioral burden. It says "draft" (implying a non-final, unpaid order) but never states that the draft is inert until completed, what permissions/plan are required, whether inventory is reserved, or what identifying handle is returned for later completion — significant gaps for an unannotated mutation tool with 12 parameters.

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 purpose and use cases front-loaded. Slightly more structure could have been gained by folding the lifecycle next-step into the second sentence, but there is no wasted prose.

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?

This is a 12-parameter, nested-object mutation with no annotations and no output schema, yet the description never says what an agent gets back (e.g., a draft order ID/GID required for complete-draft-order) or what constraints apply to lineItems beyond the 499 cap buried in the schema. For this complexity, the description is noticeably under-specified.

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 83%, so the schema already documents nearly every field, including the variantId-vs-custom-line-item distinction and discount valueType. The description's mention of "custom line items, discounts, and customer association" mirrors what the schema says rather than adding new meaning, making 3 the appropriate baseline.

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 ("Create a draft order") plus concrete scenarios (phone/chat sales, invoicing, wholesale), which is well beyond a restatement of the name. It does not differentiate from the obvious sibling complete-draft-order or explain the create→complete lifecycle, so it stops short of full sibling differentiation.

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 listed scenarios (phone/chat, invoicing, wholesale) imply when to reach for this tool over the read-oriented order siblings. However, there is no explicit when-not, no prerequisite (e.g., customer must exist, or that a draft must later be completed via complete-draft-order), and no exclusion against other creation paths.

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

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

With no annotations, the description carries the burden, and it does add the key behavioral fact that this marks items as shipped (a state change) and that IDs must be pre-fetched. However, it omits reversibility, partial-fulfillment implications, and permission requirements; the notifyCustomer warning lives in the schema, not the description.

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: the action first, then the critical prerequisite flagged with IMPORTANT. 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 nested, mutating tool with no annotations and no output schema, the description covers purpose and ID sourcing but says nothing about the result (fulfillment status returned), error/partial-success behavior, or that fulfilling all line items is the default when the line item array is omitted. The rich schema compensates for field-level gaps but not for outcome expectations.

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

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

Schema description coverage is 100%, so the schema already explains every field, giving a baseline of 3. The description adds value by highlighting that fulfillmentOrderId and line item GIDs come from get-fulfillment-orders, which is the most error-prone part of the call.

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 ("Create a fulfillment") and clarifies the business effect with "mark items as shipped", so the agent knows exactly what happens. It names the prerequisite sibling get-fulfillment-orders, giving partial differentiation, though it doesn't contrast with other order-mutation tools like order-mark-as-paid.

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 prescribes the workflow: call get-fulfillment-orders first to obtain IDs. That is a concrete usage condition rather than an implied one. It does not state when NOT to use this tool (e.g., cancellations or refunds), which keeps it below 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?

With no annotations, the description carries the whole load, and it discloses a genuinely non-obvious behavior: option values get registered but only one default variant is created at $0, plus the remedial follow-up. It omits other behavioral context such as required scopes, whether the product is immediately published, and what identifier is returned on success.

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, and the core action is front-loaded before the caveat. Every clause (option values registered, single $0 variant, follow-up strategy) 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-parameter nested-object creation tool with no annotations and no output schema, the description covers the hardest pitfall but leaves out the shape of the response (product ID/GID for chaining), default DRAFT status implications, and most optional field semantics. It is adequate to call the tool, but not to call it confidently end-to-end.

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% across 11 parameters, so the description needs to compensate, and it does so for the most complex parameter (`productOptions`, including a max of 3 implied by the schema). The other parameters — tags, vendor, productType, descriptionHtml, collectionsToJoin, metafields — get no elaboration beyond their names, leaving 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?

"Create a new product" gives a specific verb and resource, and the second sentence narrows the tool's scope by naming `manage-product-variants` as the follow-up for real variants. It stops short of explicitly contrasting with siblings like `update-product` or `create-draft-order`, but the resource is unmistakable.

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 an explicit conditional workflow: when `productOptions` is supplied, follow up with `manage-product-variants` using strategy=REMOVE_STANDALONE_VARIANT. That is actionable 'when to use what' guidance, though it does not say when to prefer this tool over other capture/creation paths or state prerequisites (e.g. permissions, publication status).

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

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

With no annotations, the description carries the full behavioral burden and leaves the critical trait undisclosed: which of customerOneId/customerTwoId is the surviving record and which is deleted, plus whether the merge is reversible or restorable. There is also no mention of required scopes or what happens to orders/addresses attached to the consumed record. Only the existence of default merge rules is hinted at.

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 operation and followed by the optional qualifier — nothing wasted. The second sentence is slightly vague relative to the schema's precise override list, but it earns its place as a pointer to the optional parameter.

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?

This is an irreversible mutation with a nested-object parameter, no annotations, and no output schema, so the description should explain survival semantics, reversibility, and return value. It covers none of these, leaving an agent unable to predict the outcome of the call beyond 'records are combined'.

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

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

Schema description coverage is 100%, so the schema already documents every field including the override sub-properties, making 3 the baseline. The description adds the useful framing that overrides are optional and express 'which customer to keep the field from', but it does not resolve the asymmetry between customerOneId and customerTwoId, which is the one semantic gap the schema also omits.

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 ('Merge two customer records into one') that no sibling covers — the closest siblings are get-customers, update-customer and delete-customer, none of which imply combining records. The second sentence adds the notion of field-level override. It stops short of naming which record survives, but the operation itself 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 indication of when to prefer merging over update-customer plus delete-customer, no prerequisites (duplicate verification, permissions), and no warnings about when not to merge. The agent must infer everything about applicability from the verb alone.

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

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

With no annotations, the description carries the full burden, yet it discloses nothing about irreversibility, permission requirements, or what happens to the customer's orders, addresses, and metafields. A single line for a destructive mutation is a material 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?

It is a terse, front-loaded fragment with no wasted words, but its brevity reads as under-specification rather than economy. Three words do not carry enough content for a destructive operation.

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?

A destructive write tool with zero annotations and no output schema should explain consequences, cascade effects, and error behavior. The description covers none of these, leaving the agent unable to judge what deletion actually destroys or how to recover.

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 explains the numeric-ID format and the GID warning, so the description need not repeat it. Baseline 3 applies since the description adds nothing but nothing is missing.

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?

"Delete a customer" is a direct restatement of the tool name delete-customer, adding no distinguishing detail. An agent can infer the verb+resource, but nothing separates it from siblings like update-customer, customer-merge, or delete-product-variants beyond the obvious noun.

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 versus update-customer or customer-merge, and no statement of prerequisites (e.g. customer must have no orders). The destructive verb implies intent but the description provides no exclusions or alternatives.

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

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

No annotations are provided, so the description carries the full behavioral burden for a destructive operation. It does not state that deletion is irreversible, whether the batch is atomic, what permissions/access scopes are required, or what happens if an ownerId/namespace/key combination does not 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?

A single front-loaded sentence with no filler. It is efficient, though it stops short of including any operational detail.

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

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

The schema is fully described and there is only one parameter, so invocation is unambiguous. However, for a destructive tool with zero annotation coverage and no output schema, the absence of irreversibility and error-handling context leaves a material 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%, so types and the ownerId GID format are already documented in the schema. The description restates the addressing triple but adds no batching semantics or error behavior beyond what the schema says.

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 (delete) and resource (metafields) plus the identifying triple (owner ID, namespace, key), and clarifies scope with 'any Shopify resource'. It is distinguishable from get-metafields and set-metafields by verb alone, though siblings are never named.

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 versus set-metafields or when a metafield should not be removed. The existence of the sibling set_metafields/get_metafields family is left for the agent to infer.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure, yet it says nothing about permanence, whether deletion cascades to variants/media/metafields/publications, required scopes, or whether the operation is reversible. For a destructive irreversible action this is a serious omission.

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 zero waste, but its brevity comes from under-specification rather than disciplined concision — there is no structure or front-loaded detail beyond a restatement of the name.

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

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

For a destructive mutation with no annotations and no output schema, an agent needs to know about irreversibility, cascade effects on variants and media, and auth requirements — none of which are present. The complete schema partially compensates on the input side only.

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% — the sole 'id' parameter is fully documented with a Shopify GID example in the schema. The description adds no parameter information, so the 3 baseline applies; nothing is missing but nothing is contributed either.

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 ('Delete a product'), so the basic operation is clear, but it adds nothing beyond what the tool name already conveys and does not distinguish it from siblings such as delete-product-variants or 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?

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, and no indication of how it relates to delete-product-variants for removing only part of a product.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. 'Delete' signals a destructive mutation, but it doesn't state irreversibility, what happens to associated inventory levels or order history, whether partial failures are possible with multiple variantIds, 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?

A single front-loaded sentence with no wasted words. The scope ('one or more') and the resource are stated 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 an un-annotated destructive bulk-delete operation with no output schema, the description is far too thin – it doesn't cover side effects, idempotency, failure semantics for multiple IDs, or what a successful response returns.

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% – productId and variantIds are both documented as Shopify GIDs, and required/minItems constraints are declared. The description adds nothing 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?

The description states a specific verb ('Delete') and resource ('one or more variants from a product'), which is unambiguous. It doesn't explicitly distinguish itself from siblings like manage-product-variants or delete-product, but the operation itself 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?

There is no guidance on when to use this versus manage-product-variants (which likely also handles variant removal) or delete-product, nor any stated prerequisites such as product ownership or permissions. The agent is left to infer the context entirely.

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

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

With no annotations, the description carries the full disclosure burden. It usefully states that products are paginated and that field selection shrinks the response, but it says nothing about permissions, not-found behavior, or that the call is a safe read — gaps that matter for a tool with zero annotation coverage.

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 resource and payload, then the field-selection tip. Slight redundancy with the schema's own 'fields' documentation keeps it from a 5.

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?

No output schema or annotations exist, and the description compensates by enumerating the returned sections and the pagination/field-selection controls. It falls short only on error/edge-case behavior for an unknown collectionId.

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 schema's 'fields' description already covers the enum, defaults, and the token-saving rationale in more depth than the prose does. The description's mention of 'fields' only duplicates the schema, so the baseline 3 applies.

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

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

The description uses a specific verb and resource ('Get a single collection') and enumerates the payload (products, ruleSet, SEO, image), which clearly distinguishes it from the sibling get-collections list tool. It never names that sibling explicitly, so the differentiation is implicit rather than stated.

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 hints at usage by recommending 'fields' to reduce response size, but it never says when to pick this over get-collections or what happens when the ID is unknown. The when-to-use guidance is implied by the name and payload rather than articulated.

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

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

No annotations, so the description must carry the behavioral burden. It discloses that results include title, handle, products count, sort order, and smart-collection rules, and that 'fields' reduces response size — useful. But it omits pagination/cursor behavior, default page size (only in schema), and whether it's read-only (only implied by 'Query').

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 purpose and scope, followed by the fields optimization and return shape. No filler; could be marginally tighter by merging the last two clauses.

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 and no annotations, the description covers the essentials: what's queried, the returned fields, and the token-saving fields option. The remaining gap is pagination and default-limit behavior, which are handled in the schema but not reinforced here.

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

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

Schema coverage is 100%, so the schema already fully documents first, query, and fields. The description echoes filtering and field selection without adding syntax, format, or edge-case meaning beyond what the schema provides; 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?

States the specific verb and resource ('Query collections') and adds scope detail distinguishing manual from smart collections with optional filtering. It's clear what the tool does, though it doesn't explicitly contrast with the sibling get-collection-by-id.

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?

Implies usage through 'optional filtering' and the field-selection advice, but never states when to use this vs get-collection-by-id or get-products, nor any prerequisites. Usage is inferable rather than guided.

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

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

No annotations are provided, so the description carries the burden. The verb 'Get' signals a read-only lookup and it notes that field selection reduces response size, but it says nothing about what happens when the ID is not found, permission requirements, or payload shape beyond size.

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 core action and followed by the one non-obvious capability. No wasted words.

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

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

For a simple two-parameter read tool with a fully documented schema and no output schema, the description covers what is needed to invoke it correctly. Error/not-found behavior is the only notable omission.

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

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

Schema description coverage is 100%, so the schema already documents both 'id' (with GID warning) and 'fields' (with enum list and rationale). The description's mention of field selection only restates what the schema says, which is the correct baseline-3 case.

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 clear verb and resource ('Get a single customer by ID'), and the singular framing implicitly contrasts with the sibling list tool get-customers. It does not name the alternative explicitly, 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?

Usage is only implied: the singular 'single customer by ID' suggests this is for looking up one record rather than browsing, but there is no explicit statement of when to use this versus get-customers or get-customer-orders, and no 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?

With no annotations, the description must carry the full behavioral burden, but it only notes that 'fields' reduces response size. It says nothing about pagination behavior, the default/max page size, sort ordering, or that this is a read-only operation — all of which matter for an 8-parameter listing 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 short sentences with the scope up front and the optimization tip second. Nothing is wasted, though it is arguably too terse given the tool's complexity.

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?

Eight parameters, no annotations, and no output schema — yet the description covers only customer scoping and field projection. Pagination, count-only mode, sorting, and the read-only nature are all left to the schema, which is thin compensation for a tool with this much surface area.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail, including the strongly emphasized 'fields' and 'countOnly'. The description's only parameter remark (field selection shrinks responses) merely restates the schema, so 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?

States a specific verb and resource ('Get orders') scoped to 'a specific customer', which partially separates it from siblings like get-orders. However, it never explicitly contrasts itself with get-orders or get-fulfillment-orders, so the differentiation is implied rather than stated.

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 when-to-use guidance against the many sibling order-listing tools, and no mention of the prerequisites or recommended workflow (e.g. countOnly before paginating) that the schema considers important. The agent must infer that this is the per-customer variant of get-orders.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it does not state that this is a read-only operation, how pagination behaves, or what search semantics apply. It repeats the fields and countOnly tips already present in the schema, adding little behavioral context beyond 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?

Two short sentences, front-loaded with the primary purpose, with no wasted wording. The secondary field-selection note is compact and immediately follows the main 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 an 8-parameter listing/search tool with no output schema, the description is only minimally complete. The schema documents parameters well, but the description does not explain return shape, pagination behavior, or read-only nature, leaving some contextual 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 100%, so the baseline is 3. The description mentions 'fields' and 'countOnly', but those explanations are already fully covered in the schema and it adds no additional parameter semantics.

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: get customers or search by name/email. It clearly separates a list/search operation from single-customer tools like get-customer-by-id, though it does not explicitly name that sibling as the alternative.

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 two modes, listing and searching, and notes that countOnly is for getting just the count. However, it gives no explicit when-to-use guidance against alternatives such as get-customer-by-id, get-customer-orders, or create-customer.

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

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

With no annotations, the description carries the burden of behavioral disclosure. 'Get' strongly implies a read operation and the description lists useful returned fields, but it does not state permission requirements, pagination behavior, or what happens when no fulfillment orders 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?

The definition is a single front-loaded sentence with no wasted text. It states the action, scope, and key returned information efficiently.

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

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

For a simple one-parameter read tool with no output schema, the description is largely complete: it identifies the operation and summarizes the returned data. It could be stronger with explicit read-only/permission notes or return-shape details, but those gaps are minor given the tool's low 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?

The input schema has 100% description coverage, including format guidance for orderId. The description adds no parameter-specific details beyond what the schema already provides, so the schema does the heavy lifting.

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

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

The description clearly states a specific verb and resource: get fulfillment orders for an order. It also names the key returned fields, which helps distinguish this read operation from order-mutating or fulfillment-creating siblings, though it does not explicitly call out sibling boundaries.

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 by 'get fulfillment orders for an order,' so an agent can infer this is for retrieving fulfillment details for a specific order. However, it does not explicitly say when to use this versus related tools such as get-orders, get-order-by-id, or create-fulfillment.

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

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

With no annotations, the description carries the full behavioral burden. It discloses scope by saying details are returned for all variants and lists fields, but it does not describe permissions, pagination, empty-result behavior, or other operational constraints.

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 definition is a single front-loaded sentence with no wasted text. The field list is useful and earns its place by clarifying the return payload.

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?

This is a simple one-parameter read tool with full schema coverage, and the description enumerates the returned fields despite no output schema. It is mostly complete, though it could mention how it relates to the inventory-levels sibling.

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 productId parameter is already well documented in the schema with examples. The description does not add parameter detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: get inventory item details for all variants of a product, and it enumerates the returned fields such as SKU, cost, tracked status, country of origin, and HS codes. It is clear what the tool does, but it does not explicitly distinguish itself from nearby siblings like get-inventory-levels or get-product-variants-detailed.

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 explicit when-to-use guidance, exclusions, or alternatives. A sibling such as get-inventory-levels likely handles inventory quantities, but this description does not route the agent between the two.

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

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

With no annotations, the description carries the full behavioral burden; it discloses the returned quantity categories (available, on_hand, committed, reserved, incoming, damaged), which is useful. However, it says nothing about whether all locations are returned, pagination, or permission requirements for a read 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?

One sentence, zero waste, with the resource and returned fields front-loaded. Nothing extraneous.

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 read tool with no output schema, the enumeration of returned quantity fields fills the gap that a missing output schema leaves. Only pagination and location-scope behavior remain unstated.

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 parameter is fully documented in the schema, including ID format and sourcing guidance. The description adds no parameter detail beyond what the schema provides, so 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?

States a specific verb and resource ('Get inventory quantities per location for an inventory item') and enumerates the quantity fields returned. It is clear what the tool does, though it does not explicitly distinguish itself from the sibling get-inventory-items.

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 versus get-inventory-items, inventory-set-quantities, or get-locations, and no stated prerequisites. The read-only nature is only implied by the verb 'Get'.

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

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

No annotations, so the description carries the full burden. It discloses what data comes back (addresses, capabilities, active status), which is helpful, but says nothing about pagination limits beyond the schema, whether inactive locations are excluded by default, or the read-only/non-destructive nature of the call.

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

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

A single front-loaded sentence with zero filler; every element (verb, resource type, returned fields) earns its place.

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

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

For a simple two-parameter read tool with no output schema, the description states the scope and payload fields sufficiently. The only gap is that pagination behavior and the default exclusion of inactive locations are left entirely to the 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 description coverage is 100%, with both 'first' (default 50, max 100) and 'includeInactive' fully documented in the schema. The description adds no meaning beyond those fields, so 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?

Specific verb+resource ('Get all inventory/fulfillment locations') and it names the returned fields (addresses, capabilities, active status). No sibling tool overlaps with locations, so distinguishing from siblings isn't really needed, but it also doesn't relate itself to nearby read tools like get-shop-info or get-inventory-levels.

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

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

The word 'all' plus the includeInactive parameter imply a full listing rather than a filtered lookup, which is enough to infer intended use. There is no explicit when-to-use/when-not-to-use statement and no pointer to alternatives, though no direct alternative for locations exists 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?

With no annotations, the description carries the full burden; it usefully names the returned facets (regions, currencies, status, web presence), which is real added context. However, saying 'Get all markets' while the schema defaults to 25 and caps at 50 is mildly misleading about whether the result is complete, and there is no note on pagination or auth.

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 front-loaded sentence with no filler; the returned fields are listed compactly. Slight cost is that the 'all' qualifier is the only place where the pagination nuance could have been clarified but wasn't.

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

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

For a simple read-only list with no output schema and full param documentation, describing the returned fields is the right level of detail. The remaining gap is that an agent cannot tell from the description whether a single call returns every market or only a page.

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 'first' parameter (default 25, max 50) is already fully documented. The description adds nothing beyond that, which meets the baseline for high-coverage schemas.

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

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

Clear verb+resource ('Get all markets') plus the concrete payload (regions, currencies, status, web presence configuration). No sibling tool covers markets, so no differentiation is needed, though the 'all' wording is at odds with the default-25 pagination.

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 read-only list nature is implied and no sibling competes for this purpose, but the description gives no explicit when-to-use framing or guidance on how many markets to request via 'first'.

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

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

No annotations are provided, so the description carries the burden. 'Discover' and 'Returns' clearly signal a read-only lookup and the description lists what comes back (namespace, key, name, type, validations), but it says nothing about pagination limits, auth/scope requirements, or what happens when no definitions 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, and the core purpose is front-loaded before the return-field list. Nothing redundant is included.

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 2-parameter read tool with no output schema, the description usefully enumerates return fields. The remaining gap is that `first` exists without any cursor argument, and the description never explains how to page beyond the max of 100 or whether results are truncated.

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 documents both `ownerType` (with the concatenated-name normalization note) and `first` (default 50, max 100). The description only restates example owner types that the enum already supplies, adding no meaning beyond the schema; 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?

States a specific verb and resource ('Discover custom metafield definitions') plus the scope ('for any resource type') and enumerates the returned fields. The 'definitions' framing implicitly separates it from get-metafields, but it never names that sibling explicitly, so an agent must infer the 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?

Usage is implied: call this to learn what metafield definitions exist for a resource type before reading or setting values. There is no explicit when-to-use/when-not guidance and no reference to get-metafields or set-metafields, which are the most likely confusable 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?

No annotations are provided, so the description carries the full disclosure burden, and it says essentially nothing behavioral. 'Get' implies read-only, but nothing is said about pagination limits, response size behavior, required permissions, or ordering — all relevant for a list operation over arbitrary resources.

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 front-loaded sentences with no filler: scope first, then the most impactful filtering capability. Nothing could be removed without losing 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 simple read tool with 100% schema coverage and no output schema, the description gives enough to call it correctly. It stops short of mentioning the required ownerId or pagination defaults, but those gaps are minor given the rich schema.

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

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

Schema coverage is 100%, so every parameter is already documented, including the detailed keys filter and its interaction with namespace. The description's mention of the keys filter by namespace.key restates the schema rather than adding new semantics, 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?

States a specific verb (Get) and resource (metafields) and explicitly enumerates supported owner types (products, orders, customers, variants, collections). It is clearly distinct from mutation siblings like set-metafields and delete-metafields, though it doesn't explicitly name get-metafield-definitions as the schema-level alternative.

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 hints at usage via the 'keys' filter note, implying this is a broad fetch that should be narrowed when possible. However, it never states when to prefer this over get-metafield-definitions or how it relates to set/delete siblings. 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?

With no annotations provided, the description carries the full burden and says almost nothing behavioral: it does not confirm this is a read-only lookup, does not mention what happens for an unknown ID, and does not describe the returned payload. The one behavioral point it does make—that field selection reduces response size—is already stated more forcefully 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, front-loaded with the core purpose and with zero filler. It is perhaps overly terse given the tool's role, but nothing is 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?

There is no output schema and no annotations, so the description is the only place to convey the return shape and safety profile—neither is covered. For a simple fetch tool the parameter schema compensates well, but the missing return/behavior detail leaves a real 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%; the schema already explains accepted orderId formats (number, numeric ID, GID) and enumerates the fields option. The description's note about 'fields' reducing response size adds little beyond that, so 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?

States a specific verb and resource ('Get a specific order by ID'), which implicitly separates it from the list-oriented sibling get-orders. It does not name any sibling explicitly, so the differentiation is inferred rather than stated.

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 prefer this over get-orders, get-order-transactions, or get-order-refund-details, and no prerequisites or error conditions mentioned. The only usage hint is that 'fields' should be supplied to trim the response.

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

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

No annotations exist, so the description carries the full burden: 'Get' signals a read operation and the enumeration of refunded items, amounts, restock status, and transactions usefully previews the response shape. However, it does not disclose what happens when an order has no refund, whether the call is permission-scoped, or whether the payload is paginated, which are exactly the gaps annotations would normally 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?

One front-loaded sentence with the verb and resource first and the returned fields trailing, no filler or repetition. It is appropriately sized for a single-parameter getter, though the trailing field list is a touch list-like rather than structured.

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

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

For a one-parameter getter with no output schema, the description does the main job of telling the agent what comes back (items, amounts, restock status, transactions). The remaining omission is the empty-refund case and any authorization requirement, which is a modest gap in an otherwise complete definition.

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?

There is a single required parameter at 100% schema description coverage, and the schema already documents both the GID and bare-numeric forms of orderId with an example. The description adds no further meaning about the identifier, so the baseline 3 is correct.

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 ('Get detailed refund info for an order') and enumerates the payload (refunded items, amounts, restock status, transactions), which clearly separates it from mutation siblings like refund-create or order-cancel. It stops short of naming the read siblings it is easily confused with (get-order-transactions, get-orders), so it lands at 4 rather than 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?

There is no explicit guidance on when to call this versus refund-create or get-order-transactions, nor any precondition such as 'use only after a refund exists on the order'. The only implied usage is that the agent must already have an orderId, which comes from the schema, not the description.

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

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

No annotations exist, so the description carries the full behavioral burden. It does disclose two real behavioral traits — field selection narrows the fetched payload, and countOnly returns just a count — but says nothing about read-only safety, pagination cursor semantics, defaults, or result shape.

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 verb and resource, with no filler. Minor redundancy with the schema's own fields/countOnly descriptions, but nothing wasteful.

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-annotation, no-output-schema tool, the description is thin: it never mentions the raw 'query' escape hatch, cursor pagination, the default/max limit, or any distinguishing context against ~50 siblings. The rich schema compensates partially, but the description itself is far from 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 89%, so the schema already explains after/before/limit/query/fields/countOnly in detail. The description only echoes status, fields, and countOnly, adding no syntax or interaction rules (e.g., how status interacts with the raw query string). Baseline 3 applies where the schema does the heavy lifting.

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 ("Get orders") plus the optional status filter and the two payload-shaping options. It does not distinguish itself from close siblings like get-order-by-id, get-customer-orders, or get-fulfillment-orders, so the 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?

Usage is implied by the verb and the mention of status filtering, and the description hints at a size-check workflow via countOnly. There is no explicit when-to-use vs. when-not-to-use, and no routing to the many sibling read tools.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose what a caller will see back — gateway, status, amounts, and the four transaction types — but says nothing about pagination, result limits, ordering, or permission requirements for payment data.

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

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

A single front-loaded sentence with the verb first and the returned content appended; every clause adds information and none repeats structured fields.

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 read tool with no output schema and no annotations, the description covers purpose and returned field categories well. Missing only pagination/result-volume behavior, which matters for order transactions that can be numerous.

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?

There is only one parameter, and the schema documents it at 100% coverage including the GID/plain-ID format example. The description only implies that the input identifies an order, so it neither compensates nor detracts; 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 and resource (get payment transactions for an order) and enumerates the transaction types covered (authorizations, captures, refunds, voids). This scope is broad enough to be distinguishable from the overlapping sibling get-order-refund-details, which covers only refunds.

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 phrasing 'all payment transactions for an order' implies the when-to-use case, and the mention of refunds implies it is the broader alternative to get-order-refund-details, but no sibling is named and no exclusion or prerequisite 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?

No annotations are provided, so the description carries the full burden, and it omits that this is a read-only, paginated operation. Worse, 'Get all price lists' is misleading given the schema's first parameter (default 25, max 50) means results are capped — an agent may assume it received the complete set.

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 front-loaded sentence with no filler; the returned-field enumeration is compact and useful. Slightly over-committed by the word 'all' relative to the paginated 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?

The listing of returned fields partially compensates for the missing output schema, which is helpful. However, for a read tool with zero annotations, the absence of pagination behavior, safety profile, and scope leaves 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 coverage is 100% and the single optional 'first' parameter is fully documented with default and bounds. The description adds nothing about the limit/cursor semantics, so 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?

States a specific verb and resource ('Get all price lists') and enumerates the returned facets (currency, fixed/relative adjustments, catalog context). No sibling tool covers price lists, so no differentiation is required, but it stops short of explaining scope (e.g. all markets vs. shop default).

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 call this versus other catalog-listing tools (get-products, get-markets, get-collections), nor any prerequisite or exclusion. The only usage signal is implied by the verb 'Get'.

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

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

No annotations are provided, so the description carries the full burden. It discloses only that field selection reduces response size; it says nothing about required access scopes, behavior when the product ID is not found, or what is returned when 'fields' is omitted.

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 zero waste, and the core action is front-loaded ahead of the optional field-selection note.

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

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

For a simple two-parameter read tool with no output schema this is minimally adequate, but an agent still cannot tell what the default response contains, whether the call can fail on a bad GID, or how it relates to the product-variant and product-media getters.

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 'fields' parameter already carries a long, prescriptive enum description. The description only echoes the token-saving rationale, adding no format or semantics beyond the schema. 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?

States a specific verb and resource ('Get a specific product by ID'), which distinguishes it from the list-style sibling get-products. It does not name or differentiate against near neighbors like get-product-variants-detailed or get-product-media, so it falls short of 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?

Usage is only implied: you need an ID, so you use this instead of the list tool. There is no explicit statement of when to prefer get-products, get-product-variants-detailed, or when this tool is inappropriate.

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

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

No annotations are provided, so the description carries the full burden. It discloses the status lifecycle (UPLOADED / PROCESSING / READY / FAILED) and that media items can be in flight, which tells the agent this is an asynchronous-polling read. It does not state read-only-ness, pagination, or behavior for an unknown productId, so it falls short of complete.

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-value summary is front-loaded and the usage hint follows, which is the right ordering for a read 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?

There is no output schema, so the description must describe returns — and it does (status enum, alt text, image URL). What is missing is whether results are paginated or how many items come back, which matters for a media list, but nothing an agent needs in order to invoke it 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?

Only one parameter (productId) and schema coverage is 100%, with a GID example already in the schema. The description adds no syntax, format, or alternate-input guidance beyond what the schema provides, 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?

States a specific verb and resource ("List a product's media") and enumerates the returned fields (processing status, alt text, image URL). That is enough for an agent to tell it apart from get-product-by-id or get-product-variants-detailed 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 says to call it after add-product-media to confirm processing finished, which is concrete timing guidance tied to a named sibling. It stops short of naming exclusions or alternatives (e.g. when to prefer get-product-by-id), but for a single-purpose read tool the context is clear.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the return semantics ('published true/false, with publishDate when published or scheduled'), which is genuine behavioral value. It does not state that the operation is non-destructive/read-only, nor anything about failure when the product ID is invalid or the product exists in no channel.

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

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

One sentence, front-loaded with the verb and resource, with the return shape packed into a parenthetical. Nothing could be removed without losing 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 single-parameter read with no output schema, the description usefully describes the return fields, filling the gap left by the absent output schema. It would be complete with a brief note on when a channel is omitted versus returned as false.

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 parameter already documents the Shopify GID format with an example. The description only refers to 'a product' and adds no format or validation detail beyond the schema, so the baseline 3 applies.

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

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

Specific verb ('Show') plus a precise resource ('whether a product is published on each sales channel'), including the shape of the answer (published true/false, publishDate). This clearly separates it from the mutating siblings publish-product/unpublish-product and from get-publications. It stops short of naming a sibling explicitly, which keeps it out of 5 territory.

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 says what the tool returns but never states when to call it versus publish-product, unpublish-product, or get-publications, nor any prerequisite (e.g. requiring a product GID from get-products). Usage is only inferable from the read-style 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?

With no annotations, the description carries the full behavioral burden, yet it discloses only that field selection and count-only mode exist — both already explained in the schema. It says nothing about read-only nature, pagination limits, cost of fetching variants/media, or default result size.

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 the capability statement front-loaded and no filler. It is efficient, though it leans on the schema for anything substantive.

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?

A 9-parameter list tool with no annotations and no output schema needs more: nothing explains the return shape, what countOnly returns versus normal results (only the schema hints), or how query/searchTitle/sortKey interact. An agent must read the entire schema to call this safely.

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

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

Schema description coverage is 100%, so the baseline applies: the schema documents pagination, query syntax, sort keys, and field enums in detail. The description's mention of 'fields' and 'countOnly' merely restates what the schema already says.

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 clear verb and resource (list products) plus the search-by-title mode, which distinguishes it from get-product-by-id. It doesn't explicitly name get-product-by-id or get-product-variants-detailed as alternatives, so sibling differentiation is only implied.

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?

'Search by title' implies when searchTitle applies, but the description never says when to use this list tool versus get-product-by-id, get-collection-by-id, or the variants tools, nor when to prefer 'query' over 'searchTitle' (that contrast lives only in the 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?

With no annotations, the description carries the full burden; it does establish this is a read-style fetch of an already-identified product and discloses that omitting 'fields' returns the full field set (larger payload). It says nothing about authentication requirements, pagination beyond the 'first' cap, rate limits, or error behavior when productId is invalid.

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 resource and followed by the one behavioral note that matters (payload reduction via 'fields'). 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, three-parameter tool with full schema coverage and no output schema, the description covers what is fetched and how to trim the payload. Minor gaps remain: no mention of whether results are paginated or what happens past the 100-variant cap, and 'weight'/'tax code' only reach the caller through the inventoryItem field, which is not stated.

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 three parameters are already documented, including the enum of selectable fields and the 1-100 range on 'first'. The description only restates that field selection shrinks the response, adding no syntax or semantics beyond the schema; 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 names a specific verb ('Get') and resource ('variant fields for a product') and enumerates the field categories returned (pricing, inventory, barcode, selected options, metafields, image). It does not explicitly differentiate itself from nearby read siblings like get-product-by-id or get-inventory-items, so an agent must infer that this is the variant-level detail fetch.

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 by 'Get all variant fields' plus a note that 'fields' reduces response size, but there is no explicit when-to-use versus get-product-by-id / get-inventory-levels, and no stated prerequisites or exclusions. The agent can infer the use case but is given no 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?

With no annotations, the description carries the burden; 'List' plus 'with their IDs' makes clear this is a non-mutating enumeration that returns name/ID pairs. For a zero-parameter lookup the risk surface is small, though pagination or whether the list is bounded is never stated.

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 what it returns, followed by the follow-up action. 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 trivial no-arg list tool with no output schema and no annotations, this covers the essentials: what is returned, in what form, and what to do with it. Only the relationship to get-product-publications is 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?

The schema declares zero properties, so there is nothing to document; baseline applies. The description usefully clarifies that the output contains both names and IDs, which matters for downstream calls.

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 ('List the store's sales channels (publications)') and even names example values, so an agent can tell this enumerates store-level channels rather than a product's channels. It does not explicitly distinguish itself from the sibling get-product-publications, leaving that boundary implicit.

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 a clear downstream use case: take the returned names/IDs and pass them to publish-product or unpublish-product. That is genuine routing guidance. It lacks an explicit 'do not use when...' or a named alternative like get-product-publications.

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

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

No annotations are provided, so the description carries full burden. 'Get' implies a read-only, non-destructive operation and the field list conveys roughly what comes back, but it says nothing about sensitivity of the returned data (payment settings, contact info), permission requirements, or whether currency/tax values are shop-default vs resolved.

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 well-formed sentence that front-loads the verb and resource and then enumerates the payload. No filler, 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?

With no output schema, the description's enumeration of return fields is doing the necessary work of telling the agent what it will receive. For a zero-parameter read tool this is largely sufficient; only the sensitivity/permission angle is 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?

The tool takes zero parameters, which is the baseline-4 case: there is nothing for the description to disambiguate, and the schema is trivially 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 ('Get') and resource ('shop configuration') and enumerates the contents: name, plan, currencies, features, payment settings, tax config, contact info. No sibling tool covers shop-level configuration, so it is effectively differentiated, though the description never explicitly contrasts itself with alternatives.

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 call this versus other read tools, and no stated prerequisites or exclusions. The zero-parameter shape and the uniqueness of the shop-config resource make usage somewhat self-evident, but the description itself offers no 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?

With no annotations provided, the description does useful work: it explains that quantities are absolute, describes the conditional changeFromQuantity behavior and resulting CHANGE_FROM_QUANTITY_STALE error, and explains idempotency retry semantics. It still omits permission requirements and whether the whole batch is atomic.

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, front-loaded with the core operation. Each sentence adds useful information about use cases, conditional safety, and return/retry behavior without waste.

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

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

The description covers the mutation's key behavior and compensates for the lack of an output schema by mentioning idempotencyKey and userErrors. It is still missing some operational context, such as permissions and batch atomicity, which matters for a mutation tool with no annotations.

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

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

Schema description coverage is 100%, so the schema already fully documents parameters such as changeFromQuantity and idempotencyKey. The description reinforces the conditional check and retry behavior, but adds little parameter meaning 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?

The description states a specific verb and resource: 'Set absolute inventory quantities for items at specific locations.' This is precise enough to distinguish it from sibling read tools such as get-inventory-levels and get-inventory-items.

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 usage context with 'Use for inventory corrections, cycle counts, etc.' However, it does not name when not to use it or explicitly compare it with alternatives, and 'etc.' leaves the scope somewhat open.

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

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

With no annotations, the description carries the full burden for a mutation tool that includes a delete. It does not say whether delete is permanent, what happens to the customer's default flag when the default address is removed, whether update is a full replacement (the nested address object sets additionalProperties=false), or what permissions are needed.

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, front-loaded sentences with no filler; the optional-default behavior is surfaced early rather than buried. It is efficient, if slightly thin for the scope of the operation.

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 five-parameter, nested-object, destructive-capable tool with zero annotation coverage and no output schema, the description leaves too much unsaid: side effects of delete, default-address semantics, and the update replacement model are all 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%, including the action enum, the GID formats, and the 'required for create and update' / 'required for update and delete' conditions, so the baseline is 3. The description only restates setAsDefault and adds nothing about action-dependent parameter requirements.

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

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

States specific verbs (create/update/delete) against a specific resource (a customer's mailing address), and the action enum in the schema corroborates the three modes. It is clearly distinct from the sibling create-customer/update-customer tools, though it never says so 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?

No guidance on when to reach for this versus update-customer or customer-merge, no prerequisites, and no mention that addressId is mandatory for update/delete or that a default address may need special handling. The only usage signal is the action enum, which is structured data, not description content.

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

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

No annotations are provided, so the description bears the full disclosure burden, and it does say 'delete' removes options. However, it never states side effects: whether deleting an option cascades to variants, what variantStrategy CREATE does to existing variants (left to the schema), or any permission/rate constraints. For a mixed read/write tool with a destructive delete path, that is a meaningful 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 sentences, front-loaded with purpose and then the action mapping, with zero filler. Every clause earns its place by either identifying the resource or disambiguating a mode.

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 annotations and no output schema, the description covers purpose and action modes but leaves the destructive scope of delete, the variant side effects, and any return information unstated. The detailed schema carries most of the parameter load, but the behavioral surface remains thin.

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 90%, so the baseline is 3, but the description adds real meaning beyond the schema: the 'action' enum has no per-value description in the schema, and the description explains what update actually does (rename or add/remove values) and what delete targets. The meaning of the mode switch is therefore clearer from the description than from the raw enum.

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

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

The first sentence gives a specific verb set and resource ('Create, update, or delete product options') with concrete examples (Size, Color), so the agent immediately knows what domain this touches. It does not explicitly distinguish itself from the nearby sibling manage-product-variants, which an agent could plausibly confuse with this tool.

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 maps each action value to an intent ('create' to add, 'update' to rename or add/remove values, 'delete' to remove), giving clear per-mode guidance. It stops short of stating when to prefer this tool over manage-product-variants or what prerequisites (e.g. option ownership) apply.

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

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

No annotations are provided, so the description carries the full behavioral burden and does not meet it. It never says whether updates are partial or full replacement (does omitting price on an update clear it?), whether the operation is atomic across the batch, whether it can fail on duplicate SKUs, or what permissions are needed.

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 action and followed by the key dispatch rule. No filler, though it is thin rather than efficient—there is room for one more sentence of behavioral detail.

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?

A mutation tool with no annotations, no output schema, and batch array input needs more than an id rule. Missing: partial-update semantics, failure/rollback behavior, interaction with the required 'variants' array, and what is returned after creation.

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

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

Schema description coverage is 100%, including detailed notes on strategy, mediaId, inventoryPolicy and optionValues, so the baseline is 3. The description's only added meaning is the id-omitted-vs-present rule, which the schema already states for the id field.

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 pair and resource ('Create or update product variants') and immediately clarifies the upsert discriminator. An agent can distinguish it from delete-product-variants and get-product-variants-detailed, though the description never explicitly contrasts with 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?

The id/no-id rule gives clear guidance on how to create vs update a single variant, but there is no guidance on when to use this instead of manage-product-options, add-product-media, or delete-product-variants, and no prerequisites (e.g., product must exist, options must exist first).

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

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

No annotations are present, so the description carries the full disclosure burden. It says nothing about whether the tag list replaces or appends to existing tags, whether removing a nonexistent tag errors, case sensitivity, required permissions, or what is returned — meaningful gaps 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?

A single front-loaded sentence with the operation and scope stated immediately and zero filler. Nothing is wasted or buried.

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 three fully described required parameters and no output schema, the parameter side is covered, but a mutation tool lacking annotations should still explain side effects and its relationship to the bulk sibling. Adequate but with notable 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 100%: id (GID format with examples), tags (non-empty array), and action (add/remove enum) are all documented in the schema. The description's 'add or remove' merely mirrors the enum, so 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?

States a specific verb pair (add/remove) and resource (tags) plus the set of supported resource types, so the agent knows exactly what it does. It does not, however, distinguish itself from the sibling 'manage-tags-bulk', which is the most likely source of misselection here.

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 taggable resource types implies the context in which it applies, but there is no explicit 'use this instead of manage-tags-bulk when...' guidance and no exclusions or prerequisites (e.g., permission or single-vs-many constraint).

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

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

With no annotations, the description does add real behavior: mutations run in parallel and results are returned per resource, which matters for partial-failure handling. However it does not state atomicity (are all-or-nothing semantics assumed?), required permissions, or whether tags are appended vs overwritten on add.

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 bulk scope is front-loaded and the usage directive follows 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?

No output schema exists, and the description compensates partially by noting per-resource results, but it doesn't sketch the result shape or say what a partial failure looks like. For a bulk mutation tool with fully documented params, this is nearly complete but stops short on outcome semantics.

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 all three parameters are documented there, including the 100-item cap and the add/remove enum, so the description adds no parameter detail beyond the schema. Baseline 3 applies since the schema carries the burden.

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 pair (add/remove), resource (tags), and scope (bulk, up to 100 resources in one call). It explicitly names the sibling manage-tags as the non-preferred alternative, so the agent can distinguish the two without opening either 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 an explicit directive: prefer this over repeated manage-tags calls, with the reason (parallel execution, per-resource results). The >100 case is handled by the schema's ids description (call multiple times), so coverage is effectively complete.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the single most important trait — irreversibility — but says nothing about the real side effects (money movement on refund, inventory mutations, outbound customer email/SMS) or permission requirements, all of which live only in the schema text.

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 zero waste; the destructive consequence is front-loaded in the second sentence where it is most likely to be read before invocation.

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, irreversible mutation with no annotations and no output schema, the description covers purpose and irreversibility but omits the confirm-with-user expectations and the financial/notification side effects that an agent needs before calling it unprompted.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of refunding, restocking, and notification maps loosely onto three optional parameters but adds no semantics beyond what the schema already documents in 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?

The description gives a specific verb and resource ('Cancel an order') plus the three main option categories (refund, restock, notification). It doesn't name a sibling it must be distinguished from, which the schema hints at ('use refund-create instead') but the description leaves out.

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 explicit statement of when to use this tool versus refund-create or order-close-open, both of which are in the sibling list and are relevant alternatives. 'Cancellation is irreversible' is a caution, not 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?

With no annotations at all, the description carries the full burden and does disclose the concrete side effects: closing marks all items fulfilled and finances complete, opening reverses a closed order. It stops short of permissions, restrictions on reopening (e.g. time windows), or idempotency of closing an already-closed order.

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, zero filler, with the tool's scope front-loaded before the per-action semantics. 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 two-parameter state-transition tool with no output schema and no annotations, the description covers purpose, both action semantics, and side effects adequately. It lacks error/precondition behavior (permissions, whether reopening is always allowed), which an agent would need before calling blindly.

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 enum is documented, so the schema already does the heavy lifting; the description's explanation of close vs. open adds some meaning to the 'action' values. It adds nothing about orderId format or edge cases such as acting on an already-closed order, so 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?

States a specific verb and resource ('Close or reopen an order') and immediately defines what each action does to the order's items and finances. It is distinguishable from state-changing siblings like order-cancel or order-mark-as-paid by implication, but never names them.

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

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

Usage is only implied: you call it when you want to close or reopen an order. There is no guidance on when to prefer this over order-cancel or complete-draft-order, and no preconditions (e.g. whether an order must be paid/fulfilled before closing).

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

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

With no annotations, the description carries the full behavioral burden for a mutation. It does not disclose side effects such as whether a transaction record is created, whether the customer is notified, whether the operation is reversible, or what permissions are required. It only implies a state change from the verb 'mark'.

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 zero waste, and the core action is front-loaded before the use-case hint.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose and use case adequately. However, as an unannotated mutation it omits side effects and reversibility, which leaves a meaningful completeness 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 100% and the single orderId parameter is documented with a concrete GID example, so the schema does the work. The description adds no extra meaning about the parameter, 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 (mark) and resource (order) plus the target state (paid), so an agent can tell this is a state transition rather than a generic update. It does not explicitly differentiate itself from siblings like order-close-open or update-order, which is the only gap.

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 gives a clear use-case context: manual/offline payments such as cash or bank deposit. That tells the agent when this tool is appropriate, though it names no alternatives or exclusions (e.g., versus refund-create or order-cancel).

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the tool returns the product's channel states and userErrors, which is valuable, but it does not mention permissions, whether it adds to or replaces existing publications, or idempotency on repeat calls, which matter for a mutation.

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

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

A single front-loaded sentence that covers purpose, targeting options, the reference tool, and return values without waste. 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 annotations and no output schema, the description supplies the important pieces: how to target channels, where to obtain IDs, and what comes back (channel states and userErrors). Minor gaps remain around preconditions and side effects on already-published channels.

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 parameter meaning is already fully documented, including the either/or requirement for publicationIds vs publicationNames. The description reinforces 'exact' names and cites get-publications as the source, but adds little else beyond what the schema already states.

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 (publish a product) plus the scope (one or more sales channels), and points the agent to get-publications for channel identifiers. It is clearly distinguishable from the sibling unpublish-product and from channel management 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?

Explains the two ways to target channels (publicationIds or exact publicationNames) and tells the agent to consult get-publications for the values. It does not explicitly say when to choose this over unpublish-product or when publication is not appropriate, but the context for use is clear.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it does not mention that this is an irreversible money-moving mutation, what permissions or payment state are required, or how errors behave. The important warning about the notify flag sending real email/SMS appears only in the schema, so an agent reading just the description would not learn about the customer-facing 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?

A single front-loaded sentence with no filler; the scope qualifiers (full/partial, restocking, shipping) arrive immediately. Nothing redundant is included.

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