Shoprocket MCP by usefulapi

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true; the description adds concrete meaning to the non-idempotency by explaining the duplicate-name failure mode, and names the underlying endpoint PUT /v1/categories. It stops short of stating auth requirements or the failure/return shape, so not a 5.

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

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

Two short sentences with the operation type front-loaded, then the risk caveat, then the endpoint. Every clause carries information an agent needs; nothing is redundant.

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

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

For a three-parameter mutation with full annotation coverage and no output schema, the description covers intent, optional behavior, and the key failure mode. It leaves out what the call returns (e.g. the new category id) and any permission prerequisites, which are minor residual 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 all three parameters (name, slug, products) are already documented in the schema. The description echoes the optional products assignment but adds no format or constraint detail beyond what the schema provides, 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 and resource ('create a product category') plus the optional scope of assigning existing products, and prefixes it with 'WRITE:' so the mutation intent is unmistakable. An agent can distinguish it from shoprocket_update_category or shoprocket_list_categories from the description alone.

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 duplicate-call caveat ('calling twice with the same name may create a duplicate or be refused') is genuinely useful operational guidance. However, it never says when to prefer this over shoprocket_update_category, nor what prerequisites (e.g. store context, auth) must hold, so usage is only implied.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the description's real value is the disclosure that the tool does NOT email the customer and the explicit consent constraint on marketing_subscribed. That is a genuine side-effect disclosure beyond what annotations provide. A note about what happens if the email already exists would push this higher.

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 with the operation type front-loaded as "WRITE:" and no filler. Every clause carries a distinct piece of 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?

Covers side effects and consent, but with no output schema the description never says what a successful call returns (e.g. a customer ID) or how duplicate emails are handled, which matters for a non-idempotent create. Adequate but leaves meaningful gaps for a 6-parameter write tool.

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

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

Schema description coverage is 100%, so every parameter already carries a description. The description's only parameter commentary repeats the schema's own wording for marketing_subscribed ("true only if the customer opted in"), adding no new meaning. 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 ("add a customer record") and labels it WRITE up front, so an agent can distinguish it from read siblings like shoprocket_get_customer or shoprocket_list_customers. It never names the sibling it supersedes or what to do on duplicate emails, which is where update_customer would come in.

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 via the WRITE marker and the consent caveat, but gives no explicit when-to-use guidance such as "use this instead of update_customer when the customer does not exist yet" or any prerequisite about duplicate emails. The agent has to infer the routing itself.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real-world meaning beyond them: the code is live at checkout, reduces revenue, and duplicate calls produce duplicate codes. Endpoint 'PUT /v1/discount-codes' is also disclosed.

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?

Five short sentences, the mutation warning front-loaded, no filler. Every clause (revenue impact, conditional value, non-idempotency, endpoint) earns its place.

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

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

For an 11-parameter destructive mutation with no output schema, the description covers the critical traps: non-idempotency, required coupon_value by type, and bounding via usage_limit/dates. It hints at verifying percentage responses ('check the reply') but gives no shape of the return.

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

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

Schema coverage is 100%, so the schema already documents every parameter including the conditional coupon_value rule and the coupon_value percent-vs-cents quirk. The description restates the fixed/percentage dependency but adds little syntax detail beyond 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?

The description opens with a specific verb and resource ('WRITE: create a live discount code') plus the concrete consequence ('shoppers can use at checkout and that reduces the store's revenue'), which cleanly separates it from get_discount_code and list_discount_codes.

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 invocation guidance ('Type fixed or percentage needs coupon_value; free_shipping does not', 'Use usage_limit and dates to bound it') and warns that 'Calling twice creates two codes'. It stops short of naming a sibling alternative for read/list use cases, which keeps it from a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds real consequences beyond them — the product is shopper-visible unless status is 0, and duplicate calls silently create two records. It stops short of disclosing auth/permission requirements or the shape of the reply.

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

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

Front-loaded write marker, then preconditions, then behavioral caveats, then endpoint. Four short clauses, no filler, every sentence carries information an agent needs before calling.

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 11 fully documented params and rich annotations, the description covers the essentials; the notable gap is the return value — no output schema exists and the description never says what comes back (e.g. the new product id), which an agent would need to chain into a follow-up update.

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 required fields are already enumerated in the schema, so the description mainly restates requirements. The one added nuance is that categories may be given by 'name or slug', which sits on top of the schema's comma-separated string note — marginal but useful.

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 ('create a product in the store') with a 'WRITE:' prefix that immediately distinguishes it from the get_/list_/update_ siblings. It also scopes the tool by stating what it does NOT create ('Variants and add-ons are not set by this tool'), which sharpens the boundary against other product-related tools.

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

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

Gives the precondition (a name and at least one category, by name or slug) and the key caution that calling twice creates duplicates. However, it never names the alternative to reach for variants/add-ons or for editing an existing product (e.g. shoprocket_update_product), so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint, openWorldHint, and non-destructive, so safety is covered. The description adds the underlying GET endpoint and the conditional return behavior of expand_products, but says nothing about errors for unknown ids or the response 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 compact clauses with zero filler, and the primary behavior (single category by id) is front-loaded before the optional expansion. Fragment style but appropriately terse for a simple getter.

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 two-parameter tool with full schema coverage and no output schema, the description covers purpose and the expand_products conditional. Only minor gaps remain (error cases, return shape), which are acceptable at this complexity.

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

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

Schema coverage is 100%, so both parameters are already documented with examples and patterns. The description restates the id format and the expand_products effect but adds no syntax or edge-case detail 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/resource: retrieves one category by id, with the id prefix format (cat_...) and the optional product expansion. It distinguishes itself from list_categories by explicitly saying 'One category by id', though it doesn't name that sibling.

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

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

Usage is implied: use this for a single known-id lookup rather than listing. There's no explicit when-to-use/when-not, no mention of choosing list_categories when the id is unknown, and no prerequisite notes.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying HTTP endpoint (GET /v1/customers/{id}), which is useful for mapping to the API but says nothing about error/not-found behavior or whether the call has side effects.

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

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

Two short sentences with no filler, and the resource-and-scope statement comes first. It is efficient, though it borders on under-specification rather than being genuinely concise.

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

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

For a one-parameter read-by-id tool with no output schema, the agent still lacks any hint of the returned customer shape or failure modes. The description is minimally adequate but does not close that 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 single parameter is documented with pattern, length bounds, and a concrete 'cus_...' example. The description merely echoes the id format already in 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 resource and scope: 'One customer by id (cus_...)' — singular retrieval, not a list. The 'one' vs the sibling shoprocket_list_customers is discernible, though the description never names the sibling explicitly.

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

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

Usage is only implied by the name/verb: fetch a single customer when you have an id. There is no explicit statement of when to prefer this over shoprocket_list_customers or shoprocket_update_customer, and no note about what happens if the id does not exist.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the raw endpoint (GET /v1/discount-codes/{id}) and the id prefix format, with no note on not-found behavior or what is returned.

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 terse sentences, front-loaded with the resource and scope, with zero filler. 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 one-parameter read tool with full annotation coverage this is close to adequate, but with no output schema the description never indicates that a full discount code object is returned or how a missing id is signalled.

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 already documents the ofr_... id format and example. The description merely repeats the id prefix, adding nothing 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+resource: retrieve 'one discount code by id'. The singular 'one ... by id' implicitly distinguishes it from shoprocket_list_discount_codes, though no sibling is named explicitly.

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

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

Usage is only implied: the id parameter and the singular framing suggest 'use when you already have a code id'. No explicit when-to-use, when-not, or named alternative (e.g. list_discount_codes for enumeration).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value by enumerating what the single response contains (totals, addresses, payment/fulfillment status, discounts, line items, tracking) and pinning the underlying endpoint, which matters since there is no output schema.

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

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

One dense, front-loaded sentence that packs the resource, the identifier caveat and the returned fields, followed by a short endpoint reference. Slightly over-packed but no sentence 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?

With a single required parameter, read-only annotations and no output schema, the description covers what is returned and how to identify the record. Only the routing to shoprocket_list_orders for obtaining an id is left implicit (it appears in the schema, not the description).

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by disambiguating the id format — explicitly warning against the dashboard #number, a distinction the schema description does not make.

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 (one order by id) and immediately scopes it against the sibling list tool by specifying the ord_... identifier rather than the dashboard number. An agent can tell this apart from shoprocket_list_orders 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?

Usage is implied by the id format caveat ('ord_..., not the #number shown in the dashboard'), which guards against a common mistake. However, it never explicitly names shoprocket_list_orders as the way to obtain an id or shoprocket_update_order_status as the mutation alternative; the when-to-use routing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by naming the underlying endpoint (GET /v1/products/{id}) and enumerating exactly which fields come back, which is meaningful since there is no output schema. It does not say what happens on a missing/invalid id, keeping it below a 5.

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

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

One compact sentence plus an endpoint token; the resource and scope are front-loaded and nothing is redundant.

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 enumerated return fields do the job of telling the agent what to expect, and annotations cover safety. For a one-parameter read tool, nothing needed for correct invocation is missing.

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

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

There is a single parameter with 100% schema description coverage, including the id example format, so the schema carries the burden. The description's '(prod_...)' hint merely echoes the schema pattern; 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 precisely that it retrieves a single product by id, gives the id format (prod_...), and enumerates the payload (description, price, SKU, stock, dimensions, categories, media, variants, add-ons). This clearly separates it from shoprocket_list_products (many) and shoprocket_update_product (mutation) without the agent needing to open a schema.

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

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

Usage is only implied: an agent can infer this is for fetching one known product id rather than browsing. There is no explicit 'use this when you have an id, use list_products when you don't' routing, and no mention of alternatives or prerequisites.

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

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

Annotations already cover the read-only, non-destructive, open-world safety profile, and the description adds two useful facts beyond them: the result is key-scoped ('this key belongs to') and API keys are never returned. It also cites the underlying endpoint, GET /v1/store/details, but says nothing about error behavior or caching.

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 lists the returned fields, followed by the negative guarantee about API keys and the endpoint. No filler sentences and nothing 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?

There is no output schema, so the description carries the burden of describing the return shape and does so by enumerating the fields. Combined with the endpoint and the key-scoping note, an agent has everything needed to call it correctly.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; baseline is 4. The description appropriately spends its space on the return payload instead.

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 resource (the store the API key belongs to) and enumerates the returned fields: name, address, environment, paused state, currencies, languages, setup status. It is clearly distinct from shoprocket_get_store_stats and the per-entity get_* 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?

Usage is only implied: an agent can infer this is the call for store-level configuration rather than stats. There is no explicit statement about when to prefer this over shoprocket_get_store_stats, nor any prerequisite or exclusion.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value by disclosing that results are compared against the previous period and enumerating the metric set, which the annotations do not convey. It omits nothing critical for an aggregate read endpoint.

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: scope first, then the metric enumeration, then the endpoint. Every clause carries information, and the length is justified because no output schema exists to describe the returned 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?

With no output schema, the description compensates by naming the returned metrics and the comparison behavior, which is what an agent needs to know before calling. Minor gap: it does not state whether the date range is inclusive or how the previous period is derived.

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 both from/to are documented with the yyyy-mm-dd pattern in the schema. The description only restates 'date range' without adding format, inclusivity, or default guidance, so it adds little 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 (get sales statistics) and resource (store stats over a date range, compared with the previous period). The enumeration of returned metrics plus the endpoint path make it unambiguously distinct from siblings like list_sales or list_orders.

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

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

Usage is only implied: an agent can infer this is the aggregate analytics tool versus the listing tools, but the description never says when to prefer it over shoprocket_list_sales or shoprocket_list_orders. No exclusions or prerequisites are stated.

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

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

The annotations already establish that this is a safe read-only, non-destructive operation. The description adds useful context beyond annotations by explaining that these discounts apply at checkout without a code and by listing the fields returned in the response.

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 compact and front-loaded: one sentence states purpose and fields, and the endpoint follows immediately. Every element contributes useful information without repetition.

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

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

For a read-only list tool with fully specified pagination parameters and no output schema, the description is complete enough. It names the resource, clarifies the automatic-discount concept, and summarizes returned fields.

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 page and limit are already fully documented in the schema. The description does not add parameter-specific guidance, so the baseline 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: list automatic discounts. It clarifies what automatic discounts are (applied at checkout without a code) and summarizes returned fields, which distinguishes it from discount-code tools without naming a sibling explicitly.

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

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

Usage is implied by the list operation and the automatic-discount clarification, but there is no explicit when-to-use guidance, no exclusions, and no named alternative such as shoprocket_list_discount_codes.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the GET endpoint and the shape of returned items, but says nothing about pagination limits or total counts, so the added value is modest.

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 resource and returned fields come first, followed by the endpoint. 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?

There is no output schema, and the description compensates by enumerating the returned fields (id, name, slug). Pagination is handled by the schema's documented parameters, leaving only minor gaps such as whether results are ordered.

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% — page and limit are fully documented in the schema, including the next_page hint. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("List product categories") and even names the returned fields (id, name, slug) plus the endpoint. It is clearly distinguishable from shoprocket_get_category (single item) and shoprocket_create_category, though it 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?

Usage is only implied by the verb "List" and the read-only annotations; there is no statement of when to use this versus get_category or how to page through results. Adequate for a simple list endpoint, but nothing explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the set of returned customer fields, which is useful for a list tool with no output schema, but says nothing about pagination iteration, result ordering, or the total-count/next_page envelope implied by the page parameter.

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 purpose and the field list. The trailing "GET /v1/customers" is reference detail rather than agent-actionable content, but it costs little.

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 zero-required-parameter list tool with full schema coverage and annotations carrying the safety profile, the description is adequate: it names the resource and the fields returned, partly compensating for the absent output schema. The remaining gap is that the paginated response shape (next_page) is only implied indirectly via the schema's page parameter.

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

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

Schema description coverage is 100% — page and limit are both documented in-schema (ranges, defaults, and the "pass the previous reply's next_page" hint). The description adds nothing beyond that, 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?

Uses a specific verb+resource ("List customers") and enumerates the fields surfaced (name, email, phone, company, tax number, country, marketing opt-in), which clearly separates it from create_customer/update_customer. It does not explicitly state how it differs from shoprocket_get_customer (single-record lookup), so sibling 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?

There is no guidance on when to use this versus shoprocket_get_customer or the other list_* tools, and no prerequisites or exclusions. The only usage-adjacent content is the endpoint reference "GET /v1/customers", which is not a usage instruction.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds the returned field set and the underlying endpoint (GET /v1/discount-codes), but says nothing about pagination behavior or rate limits beyond what the schema implies.

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 returned field inventory first, the endpoint reference second. No filler, and the most useful information is front-loaded.

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

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

For a read-only list tool with complete annotations and a fully described 2-param schema, the description is nearly complete, and the field enumeration usefully compensates for the absent output schema. Missing only explicit sibling routing.

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

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

Schema coverage is 100%, with both page and limit fully documented in the schema (defaults, ranges, next_page chaining). The description adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List discount codes') and enumerates the fields returned, so the agent knows exactly what data comes back. It does not explicitly differentiate itself from siblings like get_discount_code or list_automatic_discounts, which keeps it just below a 5.

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

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

The description gives no guidance on when to use this tool versus get_discount_code or list_automatic_discounts, nor any prerequisites or filtering context. Usage is only implied by the verb 'List'.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description only needs to add behavioral context. It adds the HTTP endpoint (GET /v1/orders) and enumerates returned fields, but says nothing about pagination semantics, default ordering, or result caps beyond what the page/limit schema entries already state.

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

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

Two sentences, front-loaded with the resource and returned fields, followed by the filter surface and the endpoint. The middle enumeration is long but every clause names a genuinely distinct filter, so it earns its space; only the trailing endpoint token is arguably 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?

With 12 optional parameters, no output schema, and no nested objects, the description does the right work: it enumerates the response fields, which is exactly the gap left by the absent output schema. The remaining gaps (pagination metadata, sort order) are minor for a read-only list endpoint.

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 every filter named in the description (status, payment method, customer ids, amount range, has_sale, discount code, free text) maps one-to-one onto a documented parameter, so the description mainly restates the schema. It adds no format details, defaults, or combination semantics 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?

Opens with a specific verb+resource ('List or search orders') and immediately enumerates the payload shape (totals, customer, addresses, payment/fulfillment status, discounts, line items, shipping), so an agent knows exactly what comes back. It does not name the natural sibling get_order for single-record retrieval, so the list-vs-get boundary must be inferred from the name alone.

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 filter enumeration ('Filter by payment status, fulfillment status, payment method, customer ids, amount range, sale/discount use or free text') implies when the tool applies, but there is no explicit when-to-use framing, no when-not-to-use, and no pointer to shoprocket_get_order or shoprocket_get_store_stats for the adjacent tasks.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful context beyond them: gateway credentials are never returned, and the response indicates enabled state, plus the underlying endpoint.

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 plus the endpoint reference, front-loaded with what is listed and what is returned. No filler; every clause carries information.

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

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

For a simple read-only listing with no output schema, the description conveys enough: what entities are listed, that enabled state is included, and that credentials are excluded. A brief note on pagination or response shape would make it fully complete, but nothing essential is missing.

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

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

The tool takes zero parameters, so parameter semantics are moot and the baseline of 4 applies; the description correctly implies no inputs are needed.

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 (list) and resource (store's payment gateways), and gives concrete examples (Stripe, PayPal, manual) plus the enabled/disabled dimension. It is clearly distinguishable from siblings like list_shipping_methods and list_taxes.

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 find out which payment gateways exist and whether they're active. There is no explicit when-to-use/when-not guidance or reference to an alternative tool, but for a zero-arg list endpoint the context is reasonably self-evident.

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

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

Annotations already declare readOnly, non-destructive and openWorld, so the safety profile is covered. The description adds real value beyond that by enumerating the response payload fields and naming the underlying endpoint, which helps the agent anticipate results.

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

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

Two dense sentences plus an endpoint reference, with the returned-field list and query capabilities front-loaded and 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?

With no output schema, the description compensates by listing the returned fields, and pagination/sort mechanics are fully covered by the schema. It omits total-count or response-envelope shape, but that's a minor gap for a list tool.

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

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

Schema coverage is 100% and each parameter is well documented, including sort enum semantics and pagination limits. The description only restates the filter axes at a high level, adding no syntax or format detail beyond 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?

Starts with a specific verb+resource ('List products') and enumerates the fields returned (price, SKU, stock, categories, images, variants, status) plus the supported filter axes. It's clearly distinguished from shoprocket_get_product by being a filtered collection read, though it doesn't name that sibling explicitly.

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

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

Describes how to query (search by text, filter by category slugs, ids, slugs, and sort) but gives no explicit when-to-use vs when-not guidance or pointers to alternatives like shoprocket_get_product for a single item.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that by enumerating the returned attributes (type, value, applicability, dates, status) and the REST path, telling the agent what a call will yield without opening 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 with no filler; the resource definition and returned fields come first and the endpoint trails as supporting detail. Nothing redundant.

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, no-required-param listing tool with full schema coverage and clear safety annotations, the definition covers what an agent needs to invoke it. The only real omission is the lack of routing guidance relative to the discount-code and automatic-discount listing siblings.

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

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

Schema coverage is 100%: both page and limit are documented in the schema, including defaults, bounds, and the instruction to pass the previous reply's next_page. The description adds nothing about pagination, 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?

Names a specific verb and resource ('List sale promotions') and parenthetically defines the resource as 'price reductions on products', which disambiguates it from a generic list. It also gives the backing endpoint. It stops short of distinguishing itself from the near-neighbours list_discount_codes and list_automatic_discounts, which an agent could easily confuse with sale promotions.

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 contains no when-to-use or when-not-to-use guidance. With three similarly named listing siblings (discount codes, automatic discounts, sale promotions) the agent is left to infer from the parenthetical definition which one applies to a given request.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is carried by structured data. The description adds only the HTTP endpoint mapping; it says nothing about result ordering, page sizes beyond the schema, or whether disabled methods are included.

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 its scope. The endpoint reference is compact and useful for agents mapping to the API surface; nothing is padded or redundant.

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-param read tool with full annotation coverage this is close to sufficient, but there is no output schema, so a brief note on what a shipping method record contains (name, rate, zones) would have made the definition self-contained.

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 both params (page, limit) are fully documented in the schema, including ranges, defaults and the next_page chaining hint. The description contributes no additional parameter meaning, which is the expected baseline when the schema does the work.

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 shipping methods and rates') plus the underlying endpoint (GET /v1/shippings), so the agent knows exactly what data comes back. It does not explicitly contrast with near-neighbours like list_payment_methods or list_zones, but the resource is unambiguous enough that confusion is unlikely.

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: it is evidently the read path for shipping configuration, and the readOnly annotation reinforces that. There is no explicit when-to-use, no mention of alternatives (list_zones, list_payment_methods) and no note on when pagination is needed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured fields. The description adds only the HTTP endpoint, revealing nothing extra about pagination behavior, ordering, or what a tax rule record contains.

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 purpose, with zero filler. It is arguably too sparse rather than verbose, but nothing present 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?

For a simple two-optional-parameter read tool with annotations covering safety, this is close to sufficient. However, with no output schema, the description could have stated what a tax rule looks like or that results are paged, leaving a small gap for an agent building a call.

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% – both page and limit are documented in the schema with defaults, ranges, and the next_page chaining hint. The description adds no parameter semantics of its own, so baseline 3 is appropriate.

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

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

The description names a specific verb and resource ('List the store's tax rules') and adds the underlying endpoint (GET /v1/taxes), so an agent can tell it apart from product/order/customer list siblings. It stops short of differentiating when several listing tools could apply, but the resource 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?

There is no guidance on when to use this versus other list tools, nor any prerequisites such as needing a store context or tax configuration to exist. The agent must infer that this is the only way to read tax rules.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured fields. The description contributes only the raw endpoint path and no additional behavioral context (pagination flow, empty-store behavior, ordering).

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 tight sentence, front-loaded with the verb and resource, with a useful gloss for 'zones'. 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 simple, annotation-covered, fully documented two-parameter list tool with no output schema, the definition is nearly sufficient. The only shortfall is the absence of any note on pagination behavior or relation to shipping methods.

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 page and limit documented including defaults and the next_page chaining hint. The description adds nothing beyond 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+resource (list shipping zones) and clarifies the domain concept in a parenthetical, mapping cleanly to GET /v1/zones. It doesn't differentiate itself from siblings explicitly, but the resource name is unambiguous among the list_* family.

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 resource name — an agent would call this when it needs shipping regions — but there is no explicit when-to-use, prerequisite, or alternative (e.g., list_shipping_methods is a nearby sibling that an agent could confuse with zones).

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds useful PATCH-style semantics ('only the fields you pass are sent') and names the endpoint, but does not disclose the key destructive consequence — that supplying 'products' likely replaces the whole assignment list, unassigning existing products.

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 WRITE marker and the endpoint last. Every clause carries information, though the endpoint could be considered optional 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?

Parameters are fully documented and annotations cover the mutation safety profile, so the basics are in place. The gap is the destructive semantics of the 'products' field and what the response/state looks like after the write, which the description leaves implicit.

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

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

Schema description coverage is 100% and each field is documented (name, slug, products, category_id), so the schema does the heavy lifting. The description adds little beyond restating the fields, which is the correct baseline of 3.

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?

Opens with an explicit 'WRITE:' marker and a concrete verb+resource, then enumerates exactly the three mutable fields (name, slug, products). An agent can distinguish this from shoprocket_create_category and shoprocket_get_category without opening any schema.

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

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

'Only the fields you pass are sent' implies partial-update usage, and the write framing distinguishes it from the get/list siblings by inference. However, it never explicitly says when to use this versus create_category or update_product, and offers no exclusions or prerequisites.

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

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

Annotations already flag readOnlyHint=false, destructiveHint=true and idempotentHint=true; the description adds the non-obvious patch behavior (unsent fields are untouched) and a consent-integrity rule. It does not spell out what destructiveHint means here (overwriting existing field values) or the failure mode for a bad id, so it stops short of full disclosure.

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 WRITE marker and the field list, ending with the endpoint. Every clause carries information (mutation type, patch semantics, consent rule, route) with no filler.

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

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

For a 7-parameter mutation with no output schema, the description covers what changes, what is preserved, the consent guardrail, and the route. Missing are the response shape and error behavior for an invalid customer_id, which matters somewhat given destructiveHint=true and openWorldHint=true.

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 baseline is 3, but the description maps plain-language field names onto the schema's keys — notably "phone" to contact and "newsletter consent" to marketing_subscribed — which resolves a real naming mismatch an agent would otherwise guess at.

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?

Opens with an explicit WRITE verb and resource ("change a customer's ..."), then enumerates the mutable fields and names the endpoint POST /v1/customers/{id}. That is enough for an agent to separate it from shoprocket_create_customer and shoprocket_get_customer without opening any schema.

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

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

"Only the fields you pass are sent" establishes partial-update semantics, which is the key calling convention, and the marketing_subscribed caveat tells the agent not to blanket-set consent. It stops short of naming when to prefer create vs update or what happens on an unknown customer id, so no explicit alternatives/exclusions.

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

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

Annotations only declare destructive/not-idempotent/write; the description adds genuinely new behavior: a partial update where omitted statuses are read from the order and preserved, a customer-facing email side effect that is off by default, and that cancelling can restock items. Those are exactly the non-obvious consequences an agent needs before invoking a destructive write.

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

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

Front-loads the nature of the operation ('WRITE:') and packs the important caveats (email default, stock release) into a compact block. Dense and slightly acronym-heavy, but every clause carries actionable 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 destructive 6-parameter mutation, the description covers side effects, partial-update behavior, and conditional parameters. Since there is no output schema, the only gap is that it never indicates what the call returns (e.g., the updated order object).

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 already documents omitting statuses, custom_text being tied to send_email, and release_stock requiring cancellation. The description restates the partial-update rule ('both values needed... value you leave out is read from the order first') in a way that clarifies the atomic pair semantics, adding some value beyond the per-field text.

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?

Opens with an explicit 'WRITE:' marker and a specific verb+resource: 'change an order's payment status and/or fulfillment status', with concrete examples (shipped, paid). This clearly separates it from the read-only siblings like shoprocket_get_order and shoprocket_list_orders.

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

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

Usage context is clear: it names the endpoint (POST /v1/orders/{id}) and the two conditional paths (cancelling with release_stock, emailing with send_email). It does not explicitly say when to prefer another tool or list any prerequisites/limitations, so it stops short of the top band.

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

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

Annotations already declare destructiveHint/idempotentHint/openWorldHint, so the safety profile is covered; the description still adds real substance by revealing partial-update semantics ('only the fields you pass are sent') and the Shoprocket-specific requirement that name must be resent on every update or the current value is lost. It also discloses the concrete endpoint, though it says nothing about the response or error 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?

Three short sentences, zero waste, with the write classification and field scope front-loaded before the operational gotcha. Every sentence carries information an agent would otherwise have to infer.

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 twelve-parameter mutation with no output schema, the description covers the critical failure mode (dropping name) and the partial-update contract, which is enough for a correct call. It stops short of describing the response shape or failure handling, which is the only remaining gap given the rich schema and 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 all twelve parameters including the name requirement and cents-based price are already documented in the schema. The description echoes the name-required gotcha but adds no formatting, unit, or interaction detail beyond the structured fields, 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 plus resource and enumerates the changeable fields (price, stock quantity, description, status), which separates it cleanly from create_product, get_product, and the update_* siblings on other resources. The 'WRITE:' prefix makes the operation class unmistakable at a glance.

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 — you use it to change an existing product — and there is useful operational guidance (pass the current name, only passed fields are sent), but no explicit when-not-to-use or named alternative such as 'use shoprocket_create_product to create' or 'use shoprocket_get_product to read first'.

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