Vesremont

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

Annotations already declare readOnlyHint=false and idempotentHint=false, but the description adds two things they do not: the required OAuth scope (cart:write) and the state-change consequence ('Changes buyer or order state'). It reinforces the non-idempotent warning with 'do not retry blindly', though it does not say what exactly is mutated in the basket.

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 dense sentences with zero filler; the core action and increment rule come first, followed by the retry/order exclusion and then auth/state notes. 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?

An output schema exists, so return values need no explanation, and the input schema fully documents both parameters. The description covers the remaining agent-facing needs for a non-idempotent mutation: scope, state-change warning, and misuse exclusions.

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 fully documented in the schema, including the increment-vs-final-quantity distinction and the product ID vs SKU warning. The description's 'Quantity is an increment' merely repeats the schema, adding no new parameter meaning, 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?

States a specific verb (add), resource (product quantity), and target (existing basket), and the increment semantics ('Quantity is an increment') cleanly separates it from update_cart_item, which sets a final quantity. An agent can distinguish it from add_favorite and prepare_order without opening a schema.

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

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

Gives explicit when-not guidance: 'do not retry blindly or use this to create an order', which routes order creation to prepare_order/submit_order. It does not name those siblings directly or state prerequisites beyond the OAuth scope, so it stops just 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?

Beyond the annotations, it discloses the required OAuth scope (favorites:write) and confirms the operation mutates buyer/order state. Idempotency and non-destructiveness are already covered by annotations (idempotentHint=true, destructiveHint=false), so the description's added value is the auth requirement and the state-change note.

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, followed by auth scope and side effect. No filler or 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 single-parameter mutation with an output schema and full annotation coverage, the description supplies the key extras: scope, state change, and product eligibility. Only edge-case behavior (e.g., duplicate favorites, failure modes) is left implicit, which is minor given the idempotentHint annotation.

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 itself already explains the ID format (internal Vesremont numeric ID, not SKU/article or basket item ID). The description adds a validity constraint on the parameter by requiring the referenced product be a 'current public product,' which meaningfully narrows acceptable values.

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 current public product to this buyer's favorites'), which tells an agent exactly what effect to expect. The 'current public' qualifier narrows the operation meaningfully. It does not explicitly name remove_favorite/get_favorites as counterparts, but the action 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 precondition that the product must be public and current implies when the call is valid (i.e., not for unavailable or private products). However, there is no explicit guidance on when to prefer this over siblings or what to do if the item is already favorited. Usage is implied rather than stated.

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

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

Annotations already cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), and the description layers on real behavioral facts: the signing secret is returned ONCE, activation requires a signed challenge echo, no customer contact fields are transmitted, and OAuth scopes are required. None of this duplicates the annotations, and 'changes buyer or order state' reinforces the mutation semantics consistently.

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?

Purpose is front-loaded in the first sentence and every subsequent clause carries distinct operational value (secret handling, activation, privacy, scopes, state change). It is slightly telegraphic — 'Check expires_at and requires_active_grant' reads as a note fragment rather than a sentence — but there is no padding.

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

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

An output schema exists, yet the description still surfaces the two facts an agent most needs from the response (one-time secret, activation gating via expires_at/requires_active_grant) plus auth scope requirements and the privacy guarantee. For a mutation tool with side effects on buyer/order state, nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100% and both parameters are fully documented in-schema (HTTPS pattern, private-network rejection, event enum meanings). The description's 'public HTTPS receiver' phrasing reinforces callback_url but adds no format, constraint, or default information beyond what the schema already carries, 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 — 'Create a pending order event subscription to a public HTTPS receiver' — and immediately differentiates from the read-side siblings (list_webhooks, delete_webhook) by framing it as a pending/activation-gated creation. An agent knows exactly what object is being produced 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?

Prerequisites are explicit: public HTTPS receiver, must echo the signed challenge before activation, and required OAuth scopes (webhooks:write, orders:read) are named. It also tells the agent to inspect expires_at and requires_active_grant. It stops short of naming when NOT to use this vs. an alternative create path, so it falls just below 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=true and idempotentHint=true, but the description adds value beyond them: the required OAuth scope (webhooks:write), the fact that a queued delivery can be canceled but an in-flight HTTPS request cannot be recalled, and that buyer/order state changes. This is meaningful context, though it does not explain response behavior for idempotent re-calls.

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, front-loaded sentences with no filler; the primary effect comes first, followed by caveats and auth requirements. Every sentence 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 one-parameter destructive tool, the description covers authorization scope, irreversible/in-flight limitations, and state side effects, and an output schema exists so return values need not be explained. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the single subscription_id parameter is already fully documented, including its format, source, and explicit non-equivalences (not a delivery ID or signing secret). The description adds nothing parameter-specific, 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 ('Revoke an owned order event subscription') plus the secondary effect (canceling queued deliveries). This clearly distinguishes it from sibling tools like create_webhook, list_webhooks, and list_webhook_deliveries.

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 rather than stated: the word 'owned' plus the note that this affects 'buyer or order state' suggests the appropriate context. However, there is no explicit when-to-use/when-not guidance or direct routing to alternatives (e.g. use list_webhooks to find the ID, use this only to permanently revoke).

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, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new context: the required OAuth scope (cart:read) and the fact that the call revalidates current prices and stock rather than returning cached cart 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?

Three short sentences, front-loaded with the core action, followed by the auth scope and safety restatement. No filler or redundancy.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. The description supplies the missing pieces an agent needs: the operation's purpose, its auth scope, and its revalidation behavior.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-param operation.

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 (Read) and resource (the consenting buyer's existing basket), and the added clause about rechecking prices and stock narrows the meaning further. 'Basket' cleanly distinguishes it from siblings like get_checkout, get_order, and get_favorites.

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: reading the cart before checkout/order flows. The description never says when to prefer this over get_checkout or prepare_order, nor states any preconditions or exclusions. Adequate but leaves routing 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 cover readOnly, idempotent, and non-destructive, so 'Read-only' adds nothing new. What does earn credit is the auth disclosure 'Public; no OAuth required,' which is not derivable from any structured field, plus the hard constraint against fabricating IDs. Rate limits or pagination behavior remain undisclosed.

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 purpose, then constraints, then safety. Minimal waste, though 'Read-only' is redundant with the annotation block and could be dropped to tighten it further.

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?

An output schema exists, so return values need no explanation, and the description covers purpose, auth, and ID-provenance constraints for a simple read tool. It is adequate; only the lack of guidance on where this fits relative to search_products keeps it from being fully complete.

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

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

Schema description coverage is 100%, so the schema already documents section_id, brand_id, and every nested filter field in detail. The description only adds the cross-cutting rule about not inventing characteristic IDs, which is a mild semantic gain over the schema's own warnings.

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 ('Read real contextual catalog filters for a section or brand'), which is unambiguous and clearly distinct from every sibling (none of the other 20 tools deal with catalog filter metadata). It stops short of naming an alternative such as search_products, but no sibling is close enough to be confused with it.

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?

'Use returned IDs when searching; do not invent characteristic IDs' gives a downstream-usage constraint, implying this tool is called before a search to harvest valid IDs. However, it never explicitly states when to call this versus search_products, nor any prerequisite workflow step; usage 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?

Beyond the readOnly/idempotent annotations, it discloses the auth requirement (checkout:read scope), that no payment is made, and that unquoted delivery and final totals remain null. That null-state semantics and scope disclosure is real added value, though no rate limits or error behavior are mentioned.

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, front-loaded sentences with no filler: purpose first, then the null/payment caveat, then scope and read-only confirmation. 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 zero-parameter read tool with a full output schema and complete safety annotations, the description covers what it returns, what stays null, the auth scope, and the absence of side effects. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a 0-param tool is 4. The schema is empty and fully specified, leaving no semantic 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?

Specific verb (read) plus resource (checkout) with scope spelled out: checkout details, validation, and available store options. An agent can distinguish it from get_cart/get_order by resource, 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 implied by the read-only framing and by the contrast with update_checkout/prepare_order in the sibling set, but the description never states when to call this versus get_cart or get_order, nor any prerequisites beyond the OAuth scope.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), but the description adds genuine non-annotation context: the required OAuth scope 'favorites:read' and the 'consenting buyer' ownership constraint. That is real behavioral value beyond the structured hints.

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, front-loaded fragments: purpose first, then auth scope, then safety. Every clause earns its place with zero redundancy.

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

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

With an output schema present, return values need not be described, and the read-only, parameterless nature plus the stated OAuth scope make the definition callable as-is. Only a brief pointer to sibling tools for mutating favorites 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, and the rule sets the baseline at 4 for parameterless tools. There is nothing further for the description to disambiguate.

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 ('Read ... favorites') and scopes ownership to 'the consenting buyer's existing favorites'. It is clearly distinguishable from add_favorite/remove_favorite by the read semantics, though it never names those siblings 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?

'Read ... existing favorites' implies the retrieval use case, and 'Read-only' confirms it is not a mutation. However, there is no explicit when-to-use vs. alternative guidance (e.g. pointing to add_favorite/remove_favorite for changes), so usage is only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new context: the required OAuth scope (orders:read) and the semantic caveat that 'saving means submitted, not confirmed by the store' and that unavailable history/confirmation data stay null. That null-handling disclosure is real behavioral value beyond the annotations.

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

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

Front-loaded with the core action and scope, followed by the data-semantics caveat and then the auth requirement. Dense but each clause carries information; only the final 'Read-only.' is redundant with the annotations.

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 an output schema present, return structure need not be described, and the description still covers auth scope, session scoping, and null semantics for missing data. Complete enough for an agent to call it correctly; only an explicit alternative-tool pointer is missing.

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

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

Schema description coverage is 100%, and the schema itself explains that order_id is 'not an arbitrary store order' — so the description correctly defers to the schema. The description adds no additional parameter meaning, which is the expected baseline when the schema is 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 (Read) and resource (an order) with a precise scope qualifier: orders 'created by this application for the same buyer session.' This distinguishes it from sibling reads like get_product or get_checkout, though it does not name an alternative 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?

It supplies a usage condition — the order must have been created by this application for the same buyer session, and remains readable after reauthorization — but never states when to reach for this tool versus get_checkout or submit_order. Usage is implied by scope rather than directed.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond them: unknown values stay null, stock is an aggregate warehouse figure that does not promise same-day pickup, and the endpoint is public with no auth. It stops short of noting rate limits or the aggregate's freshness, hence 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?

Three short sentences, front-loaded with what is read and what it returns, then the two caveats (null semantics, stock interpretation), then access notes. No filler and 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?

With an output schema present, the description need not explain return values; it still covers the access model, null behavior, and a meaningful interpretation caveat for stock. For a one-parameter read tool with full annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the single product_id parameter is richly documented in the schema (including the 'not the SKU or basket item ID' disambiguation). The description adds nothing further about the parameter, so 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?

States a specific verb (Read) plus the resource (a current product) and enumerates exactly what is returned: price, aggregate warehouse stock, and public characteristics. An agent can distinguish this from search_products (multi-result discovery) and get_product_reviews (reviews) 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?

The description gives usage-relevant context (public, no OAuth required) and a caveat about stock interpretation, but never states when to use this tool versus search_products or when not to call it. Usage is implied rather than explicit, so it lands at minimum-viable.

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, destructiveHint=false, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful context that only moderated/published reviews are returned (i.e., unmoderated or pending reviews are filtered out) and that access is public. No rate limits or return-shape detail beyond that.

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

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

Three short, front-loaded sentences with no filler. Minor redundancy: 'Read only' opens the description and 'Read-only.' closes it, restating the same trait already carried by annotations.

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 paginated read-only listing tool with an output schema present, the description covers the essentials: what is returned (moderated/published reviews with ratings), access model (public, no OAuth), and pagination via the schema. Missing only edge context such as rate limits or whether review bodies/replies are included.

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 (product_id, page, per_page, sort, cursor) is already documented in the schema, including the cursor/page mutual-exclusion rule. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read ... product reviews') and scopes it ('moderated, published ... with real rating data and pagination'). It does not explicitly differentiate from the sibling get_product, which might also surface reviews, but the purpose is unambiguous.

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

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

No when-to-use guidance, no when-not-to-use, and no named alternatives. 'Public; no OAuth required' is context about access, not about tool selection. An agent must infer when this beats get_product or search_products.

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/idempotent/non-destructive, so the safety profile is covered. The description still adds real behavioral context: a hard cap of the latest 100 records, exclusion of event payloads and secrets from the response, and the required webhooks:read OAuth scope.

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

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

Two compact sentences, front-loaded with the core action and scope, then auth and safety qualifiers. 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?

With an output schema present, return-value shape needn't be explained, and the description still flags the 100-record cap and payload/secret omission. Only a note on pagination/ordering beyond 'latest' would make it fully complete.

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

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

Schema coverage is 100% and the schema description already explains the subscription_id (returned by create_webhook/list_webhooks, not a delivery ID or signing secret). The description adds no parameter-level 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 ('Read') plus precise resource ('latest 100 delivery attempts for an owned subscription'), with scope bounded to 100 records. It is clearly distinguishable from the sibling list_webhooks, which enumerates subscriptions rather than delivery attempts.

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

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

The description implies usage by requiring 'an owned subscription', but never states when to reach for this tool versus list_webhooks or create_webhook, and offers no exclusions or alternatives. Usage is inferable but not explicit.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the required OAuth scope (webhooks:read) and the important fact that signing secrets are never returned again after creation.

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

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

Three short sentences, each earning its place: what is listed, a key behavioral caveat about secrets, and the auth scope. The purpose is front-loaded with 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 an output schema present, return values need no explanation, and the zero-param schema needs no elaboration. The description covers scope and the secret-visibility caveat; only explicit sibling differentiation 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 no parameters and the schema is empty, so there are no parameter semantics to document; the baseline for a zero-parameter tool is 4.

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

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

States a specific verb ('List') and resource ('order event subscriptions'), scoped to the application and buyer session. It is clearly distinguishable from create_webhook, delete_webhook, and list_webhook_deliveries, though it does not name those siblings 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 read-only listing nature and the webhooks:read scope, but there is no explicit when-to-use guidance and no routing away from the sibling list_webhook_deliveries, which an agent could plausibly confuse with this tool.

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

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

Annotations declare a non-readonly, non-idempotent, non-destructive mutation, and the description adds real context beyond them: the required OAuth scope (order:prepare), that buyer/order state changes, and that the confirmation link is short-lived. The explicit 'does not submit it' also prevents the agent from mistaking this for a terminal action.

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

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

Three tight sentences, front-loaded with the action and its output, then the critical user-approval constraint, then auth and state effects. Every sentence carries distinct information.

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

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

With an output schema present, return-value detail is unnecessary, and the description covers purpose, approval requirement, auth scope, and state mutation. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the 4 baseline applies. The description offers no parameter detail because there is none to give; it correctly focuses on side effects 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?

States a specific verb ('prepare') and resource ('exact current order summary and a short-lived browser confirmation link'), and explicitly bounds the scope against the obvious sibling by saying 'this does not submit it.' An agent can distinguish this from submit_order 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?

It conveys clear context for use – the buyer must personally approve the summary before submission – which implies this is the pre-submission step. However, it never names the alternative (submit_order) or states explicit when-not conditions, leaving the routing 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false. The description adds two things beyond that structured data: the required OAuth scope (cart:write) and the state effect ('Changes buyer or order state'), which is genuinely useful context 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?

Three short sentences, each earning its place: the purpose, the auth scope, and the state effect. The primary action is front-loaded before the operational details.

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?

Return values need not be described since an output schema exists, and the annotation set covers safety and idempotency. The description closes the remaining gaps (scope requirement, mutation effect) but says nothing about error behavior or whether removal is reversible, leaving a minor gap for a destructive operation.

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 field description already spells out the ownership constraint ('not product_id or another buyer's item'). The description only restates ownership at a high level, adding no syntax or sourcing detail beyond what the schema carries, 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 ('Remove') and resource ('an item ... from their existing basket'), with the ownership scope ('owned by this buyer') distinguishing it from generic cart operations. It does not name sibling alternatives like update_cart_item or remove_favorite, so the agent must infer the boundary rather than being told it.

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

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

The description implies when to use it (deleting a line item the buyer already has), and 'Changes buyer or order state' hints at the consequence. However, it gives no explicit exclusions or direction toward update_cart_item or remove_favorite, leaving usage contextual rather than stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds meaningful context beyond that by specifying the required OAuth scope (favorites:write) and noting that it changes buyer or order 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 action and resource, followed by auth and state-change context. Every sentence carries useful information 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?

Given a simple one-parameter tool with rich schema descriptions, existing annotations, and an output schema, the description provides the core purpose, auth requirement, and mutation context. It could still benefit from a brief usage cue, but an agent has enough to invoke 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 input schema has 100% description coverage and already explains that product_id is an internal numeric Vesremont product ID, not a SKU or basket item ID. The description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

States a specific verb and resource — removing a product from this buyer's favorites — with enough precision to distinguish it from add_favorite and get_favorites. An agent can identify the operation without consulting sibling schemas.

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

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

The description does not state when to use this tool versus alternatives, nor does it give prerequisites beyond the OAuth scope. The operation is self-evident from the name, but no explicit usage guidance or exclusion is provided.

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

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

Annotations already establish read-only, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description still adds real context beyond them: typo-suggestion behavior in matching, paginated public links, and the absence of an OAuth requirement, which materially affects how an agent invokes it.

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

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

Four short, front-loaded sentences with the core action first and behavioral qualifiers after. Mostly waste-free, though the trailing "Read-only" sentence largely restates the readOnlyHint annotation already supplied.

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 an output schema present, return values need no explanation, and the description covers the essentials an agent needs: public/unauthenticated access, pagination, and fuzzy matching. It omits the pagination mechanism (page vs. cursor), but that is fully specified in the schema, so the gap is small.

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 q, page, cursor, and per_page in detail, including cursor expiry and page/cursor mutual exclusion. The description only glances at q semantics via "typo suggestions" and adds no format or syntax detail beyond the schema, fitting the baseline 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?

States a specific verb and resource ("Find brands through the storefront brand search") and clarifies the scope is public brand links, which distinguishes it from search_products. It stops short of naming the sibling tool explicitly, so an agent must infer the boundary from the resource noun 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?

Implies two usage modes (search vs. browse when q is omitted) and states no authentication is needed, which is useful context. However, it never states when to prefer this over search_products or any other sibling, and carries no exclusions; the load-bearing usage guidance lives in the q parameter description rather than here.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the bar is lower, yet the description still adds real value: public/no-OAuth auth requirement, bounded paging with an exact total, and an instruction to avoid overly broad queries. It does not cover cursor expiry or window semantics, but those live 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?

Four compact sentences, front-loaded with purpose, and every sentence earns its place by adding a distinct fact (return shape, query narrowness guidance, auth, safety). No repetition of schema content.

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

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

With an output schema present and rich annotations, the description does not need to explain return values, and it still supplies auth posture and paging behavior. For an 8-parameter search tool with nested filters, it is close to complete, though nothing tells the agent how this composes with get_catalog_filters or search_brands when building filter inputs.

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% across all 8 parameters including the nested filters object, so the schema fully documents q, page, cursor, sort, brand_id, section_id, per_page and the filter sub-fields. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

Specific verb (Find) plus resource (current catalog products) with a scope qualifier: it mirrors storefront search and filters, which cleanly separates it from get_product (single item) and get_catalog_filters (filter metadata). It never names a sibling explicitly, so differentiation is inferable 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?

"Narrow overly broad queries" is actionable guidance on how to shape a call, and the schema carries the omit-to-browse fallback. But there is no statement of when to reach for this tool versus alternatives, nor any exclusion conditions, so usage is implied rather than spelled out.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: the required OAuth scope (order:submit), the fact that it mutates buyer or order state, and the retry semantics that make idempotency safe. Only failure/error behavior is left unstated, which keeps this just short of 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?

Four tightly-packed sentences with zero filler; the gating precondition and 'never bypass confirmation' warning are front-loaded, and the trailing scope/state note is short. 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?

With an output schema present, the description needn't cover return values, and it does cover precondition, authorization, and retry behavior. Only failure/partial-failure handling is absent, a minor gap for a destructive, idempotent mutation.

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 both parameters are already documented in detail (pattern, origin, REST header). The description restates that the token and idempotency_key are required and adds the retry-the-same-key rule, but contributes little 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 (submit an order) plus its hard precondition (already approved by the buyer on the confirmation page). This clearly separates it from the sibling prepare_order, which precedes approval, so an agent can route correctly 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 explicit when-to-use ('only an order already approved'), an explicit when-not ('Never bypass confirmation'), and retry guidance ('retry the same key after uncertainty'). The conditions that select this tool versus prepare_order are fully spelled out.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context: the required OAuth scope and that the call mutates buyer/order state, plus the concrete destructive behavior of quantity=0. It stops short of 5 only because it doesn't quantify side effects beyond the removed line.

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 core action and edge case, then scope and state impact. No filler, no restating of the title.

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 an output schema present, return values need no explanation, and annotations cover safety semantics. The description fills the remaining gaps an agent needs — auth scope, absolute-set semantics, and the zero-removal behavior — so nothing material is missing for a two-parameter 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% and both parameters already spell out 'ABSOLUTE quantity... not an increment' and the item_id sourcing rule, so the description largely restates what the schema says. Baseline 3 applies since the schema carries the parameter 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?

The description gives a specific verb+resource ('Set the absolute quantity of an item in this buyer's basket') and the word 'absolute' implicitly separates it from the incrementing add_cart_item sibling. 'Quantity zero removes it' further demarcates it from remove_cart_item. An agent can route to this tool 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?

It supplies clear operating context — the required OAuth scope (cart:write) and the zero-quantity edge case that effectively substitutes for remove_cart_item. It does not, however, explicitly name alternatives or state when to prefer add_cart_item over this tool, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the mutation profile is covered. The description adds genuinely new context: the required OAuth scope (checkout:write), the fact that no order is sent and no payment is made, and that buyer or order state changes. It does not explain the destructive dimension implied by clearing fields, which lives only 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?

Three short sentences, front-loaded with the action and scope, followed by the negative constraint and the auth/state note. Every sentence carries distinct information and nothing is repeated from the 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?

An output schema exists and the input schema is exhaustive, so return values and per-field semantics need no duplication here. Combined with the annotations, the description covers action, scope, side-effect limits and auth; only a note that at least one property must be supplied (schema's minProperties) is absent, which is a minor gap.

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

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

Schema description coverage is 100%, so each parameter's keep/clear semantics, max lengths and enums are already fully documented in the schema. The description only summarises the field families (delivery, payment, contact), adding no syntax or format detail 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 a specific verb (Update) and resource (the buyer's delivery, payment or contact choices in the existing checkout), and explicitly scopes it to an existing checkout rather than order creation. The clarifying clause 'Does not send an order or make a payment' cleanly separates it from submit_order and prepare_order among the siblings.

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

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

Gives a clear when-not: it does not send an order or make a payment, implicitly routing order submission to submit_order. It also implicitly depends on choices from get_checkout (the enum descriptions reference get_checkout options). It never names the alternative tools outright, so it falls short of an explicit routing rule.

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