Vesremont

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

Annotations already declare non-idempotent, non-destructive, non-open-world, but the description adds the operative consequence: the quantity is an increment, an uncertain call must be reconciled via get_cart rather than retried, the required OAuth scope cart:write, and that buyer/order state is mutated. That is real 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?

Four short sentences, front-loaded with the core action, then routing, then failure handling, then boundary. No filler, and the most error-prone constraint (increment, not final quantity) appears early.

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; the description instead covers auth scope, side effects, retry/reconciliation behavior, and the sibling alternative. Nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description reinforces the counter-intuitive increment semantics of quantity and adds provenance guidance for product_id ('selected with get_product'), which the schema only describes as 'catalog search or a product response.' It slightly exceeds the schema rather than merely restating it.

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) plus resource (cart item) and the exact semantics: 'quantity units of a product selected with get_product to the consenting buyer's basket.' It explicitly distinguishes itself from update_cart_item (increment vs absolute) and get_cart, so an agent can route correctly 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?

Gives explicit when-to-use routing ('use update_cart_item with an item_id from get_cart for an absolute final quantity'), a failure-mode rule ('Do not retry an uncertain add blindly; read get_cart to reconcile'), and a boundary ('Does not create an order'). Both the alternative tool and the condition selecting it are named.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: the required OAuth scope (favorites:write), the note that order/buyer state changes, and the public-product restriction. It does not explicitly restate idempotency, but that is already in annotations.

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

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

Two dense sentences with zero filler, front-loaded on what the tool does, followed by alternatives and auth requirements. Every clause carries routing or prerequisite 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 mutation with an output schema, the description covers purpose, alternatives, auth scope, and state effects, and hints at the public-product constraint. Return values need no explanation given the output schema; only minor gaps remain (e.g., what happens on an already-favorited product).

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 documented in the schema with a clear disambiguation (internal product ID, not SKU/article or basket item ID). The description adds nothing parameter-level, 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 ('Save a current public product in this buyer's favorites') and immediately contrasts it with the basket, which is the most likely confusion given the sibling add_cart_item. An agent can distinguish it from get_favorites/remove_favorite/add_cart_item 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?

Names three concrete alternatives and the condition that selects each: get_favorites to inspect the list, remove_favorite to undo, add_cart_item for a purchase basket. The 'without adding it to the basket' clause explicitly rules out the wrong sibling for this intent.

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 destructive/idempotent/not-readOnly, but the description goes well beyond them: cancels queued deliveries, in-flight HTTPS requests cannot be recalled, requires OAuth scope webhooks:write, and changes buyer or order state. Those are exactly the consequences an agent needs before an irreversible call.

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

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

Front-loads the core effect and the queued-delivery cancellation, then layers qualifications. Three sentences, all carrying weight, though the density makes it read as a packed clause chain rather than tightly prioritized prose.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. The description still supplies the auth scope, irreversibility caveat, and side effects on buyer/order state, leaving nothing an agent needs missing.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, including the pattern and the 'not a delivery ID or signing secret' warning. The description reinforces provenance (list_webhooks / create_webhook) but adds no new syntax or format detail, so the baseline of 3 applies.

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

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

Specific verb+resource ('Stop future events for an owned subscription', 'revokes it and cancels queued deliveries') and it names the sibling tools that surface the required ID (list_webhooks, create_webhook). An agent can distinguish it from create_webhook and from any pause-like operation without further reading.

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?

States an explicit when-not ('This is not a pause') and routes the agent to create_webhook if a subscription is wanted again, plus it names where to obtain the subscription ID. It stops short of laying out a full decision rule (e.g. when to revoke vs. simply stop consuming deliveries), so it is clear context rather than complete 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, idempotentHint and destructiveHint=false, so the safety profile is covered; the description still adds real context beyond them, namely the cart:read OAuth scope, the fact that prices and stock are re-verified on each call, and that the response carries item_id consumed by the mutation siblings. It does not cover rate limits or failure modes, but the disclosure is well above the annotation baseline.

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 action and purpose, then the downstream consumer, then the sibling exclusion, then the scope. Three compact clauses with no filler or repetition.

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

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

An output schema exists so return values need not be enumerated, and the description still flags the one field that matters for chaining (item_id) plus auth scope and freshness semantics. Nothing an agent needs in order to call this 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 schema-based baseline is 4; the description correctly adds nothing spurious about inputs and instead explains what the no-argument call yields.

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 (inspect the existing basket/cart) and adds the important qualifier that it rechecks live prices and stock rather than returning cached data. It also explicitly routes the agent away from the sibling get_checkout, so the tool is distinguishable 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?

Gives both when-to-use ('before changing its lines', and its output feeds update_cart_item / remove_cart_item) and when-not-to-use ('Use get_checkout for delivery, payment and contact choices, not this tool'). It names the concrete alternatives and the condition that selects them.

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, so the safety profile is covered. The description adds genuinely new context beyond them: "Public; no OAuth required" (auth requirement) and the constraint to reuse the returned characteristic IDs within the same catalog context. It stops short of pagination/rate-limit detail, but those are low-relevance for metadata lookup.

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

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

Four short sentences, front-loaded with the purpose and the workflow position, then prerequisites, then scope clarification, then access/safety. No sentence is redundant and nothing needs to be read twice to be actionable.

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 purpose, workflow placement, prerequisites, auth requirement and scope limit; an output schema exists so return-value documentation is not needed. For a 3-parameter read tool with full schema coverage and complete annotations, nothing an agent needs in order 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%, so the schema already documents section_id, brand_id and the nested filters object with strong inline descriptions. The description reinforces the anyOf constraint ("a real section_id or brand_id") but adds no new syntax or format meaning beyond what is already in the schema. Baseline 3 applies when 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?

States a specific verb+resource ("Read available filter groups, values and ranges") and explicitly distinguishes itself from the sibling action it feeds ("before a filtered search_products call"). The clause "This returns filter metadata, not product results" removes any ambiguity versus search_products/get_product without requiring the agent to open either schema.

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

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

Gives an explicit usage sequence (call this before a filtered search_products call), a prerequisite (supply a real section_id or brand_id, keep the same catalog context) and an anti-pattern (use returned characteristic IDs, never invented IDs). "Returns filter metadata, not product results" functions as the when-not, routing the agent elsewhere when products are actually wanted.

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?

Goes beyond the readOnly/idempotent/destructive annotations by disclosing field-level behavior (unquoted delivery and final totals return null), confirming no order creation or payment side effects, and naming the required OAuth scope checkout:read. The scope and null semantics are facts the annotations cannot express.

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

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

Four short sentences, each load-bearing: purpose, sibling routing, null/behavioral caveats, auth scope. The routing guidance is front-loaded before the caveats.

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 still covers purpose, alternatives, side-effect profile, scope requirements and null-field behavior. Nothing needed to call this 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 and the schema is empty with additionalProperties false, so there is nothing for the description to clarify. Baseline 4 applies; the description correctly implies a no-argument call.

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

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

States a specific verb (inspect) plus the resource (checkout) and enumerates the inspected dimensions: delivery, payment, contact, validation, store options. It explicitly contrasts with siblings update_checkout, prepare_order and get_cart, so an agent can route 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?

Gives explicit sequencing (use before update_checkout or prepare_order) and an exclusion rule with the alternative named (use get_cart for basket lines alone). Both when-to-use and when-not-to-use are covered.

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 by disclosing the required OAuth scope (favorites:read) and clarifying that only IDs are returned, implying a second call is needed for details.

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

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

Three compact clauses, front-loaded with the primary action, followed by next-step routing and a disambiguation warning. Every clause carries information; nothing is 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?

With an output schema present, return-value detail is unnecessary, and the description still notes the ID-only payload shape. Auth scope, mutation path, and sibling disambiguation are all covered, leaving no gap for an agent to call this correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a no-argument list operation scoped implicitly to the authenticated buyer.

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 consenting buyer's saved product IDs') and immediately delimits scope: this returns IDs, not full product details. It also explicitly distinguishes itself from the basket tools ('favorites are not basket contents'), which is the most likely confusion given sibling get_cart.

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?

Names the follow-up tools for detail retrieval (get_product, get_products_batch) and the mutation tools for changing the list (add_favorite, remove_favorite), plus an explicit exclusion against basket contents. An agent knows both what to call next and what this tool is not for.

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/non-destructive, so the bar is lower; the description still adds real context beyond them: the required OAuth scope (orders:read), and the semantic that 'saved' means submitted but not store-confirmed, with unavailable history or confirmation fields returning null. It does not discuss rate limits or error behavior, but the null-field disclosure is the kind of nuance annotations cannot express.

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

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

Four tight sentences, each doing distinct work: purpose/provenance, alternative routing, the submitted-vs-confirmed semantics, and auth scope. Front-loaded with the verb and resource, zero filler.

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

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

For a single-parameter read with an output schema present, the description covers everything an agent needs: what it reads, which ID is valid, when to prefer get_checkout, what null means, and the scope required. Return-value structure is correctly left to the output schema.

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

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

Schema coverage is 100% and the schema description already defines order_id as an ID returned by this application's submission for the same buyer session, so the description largely restates the schema. It adds no format or boundary detail (e.g. the 1..2147483647 range) beyond what the structured field 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 (Read) and resource (a saved order) and pins the identifier's provenance: the order_id returned by this application's submit_order for the same buyer session. It explicitly contrasts with get_checkout, so an agent can distinguish it from the sibling without opening either schema.

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

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

Gives an explicit routing rule: use this for a submitted/saved order, use get_checkout for one not yet submitted. It also states the reauthorization case still works, which is exactly the ambiguous situation an agent would hesitate on.

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 closed-world, so the safety profile is covered structurally. The description still adds real context beyond that: null semantics for unknown values, the caveat that stock does not imply same-day pickup, and the no-auth requirement. It stops short of error behavior or rate limits, so it lands at 4 rather than 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?

Front-loaded with the core action and return payload, then routing and caveats in short clauses; no padding and every sentence carries information. It is slightly telegraphic and the SKU warning duplicates the schema, costing it the top mark.

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 description is not required, and the definition still covers provenance of the ID, the batch alternative, stock interpretation limits, and auth. Nothing an agent needs to invoke this single-parameter read correctly is missing.

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

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

Schema coverage is 100% and the schema description already states the ID is the internal numeric Vesremont ID, not the SKU/article or basket item ID. The description's 'Use its internal product_id, not the SKU' repeats that constraint rather than extending it with format, range, or lookup guidance, 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?

Specifies a concrete verb and resource ('Inspect one product') and enumerates what comes back: current price, aggregate warehouse stock, public characteristics. It also names the sibling that produces the input (search_products) and the sibling it differs from (get_products_batch), so an agent can place it precisely 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?

Explicit routing: the ID must come from search_products and must be the internal product_id rather than the SKU, with get_products_batch flagged as the alternative when several known IDs are involved. It also states the scope is public with no OAuth, which sets the context for when this call is 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?

Beyond the safety annotations, it discloses access requirements ("Public; no OAuth required"), scope limits (only moderated, published reviews; no pending reviews), and result interpretation ("an empty list means no published reviews, not a zero-star rating"). These are exactly the behavioral facts an agent needs that annotations alone do not provide.

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

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

Four tight sentences, each carrying distinct information (scope, return content, pagination rule, auth), with the resource statement front-loaded. No filler or repetition.

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

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

For a read-only, filterable list tool with an output schema present, the description covers scope, return contents, pagination constraints, auth requirements, and empty-result semantics. 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 coverage is 100% so the schema already documents each parameter, but the description adds interpretive value by stating page/cursor mutual exclusion and, more usefully, that an empty result reflects no published reviews rather than a missing rating. That goes slightly beyond the raw field docs.

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 customer feedback for a product") and explicitly contrasts it with the sibling get_product by denying the specification use case. An agent can immediately tell this fetches reviews, not product details.

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?

Tells the agent the product must first be obtained via get_product and gives concrete invocation rules ("Use page or cursor, never both"). It clarifies when-not (no specifications, no review submission) but stops short of naming other review-related alternatives, of which there appear to be none.

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/destructive/openWorld, and the description adds genuinely non-redundant behavior: quota accounting ('each ID consumes one normal catalog quota unit', charged even for missing products), partial-failure semantics via missing_ids for unpublished or absent products, and ordering guarantees. Those are exactly the operational details annotations cannot express.

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

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

Four tight sentences, front-loaded with the core action and count limits, then return semantics, then cost, then access constraints. No filler and no repetition of the tool name as an explanation.

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 documented, yet the description still communicates ordering and missing_ids. Combined with the quota cost model, authentication posture, and input restrictions, an agent has everything needed to batch-call this correctly.

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

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

Schema coverage is 100% and the single parameter is fully documented, including the ID-vs-SKU distinction and the quota note. The description restates the same facts ('unique', '1 to 10', 'internal ID', quota per ID) rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb and resource with batch scope ('Read 1 to 10 unique products by internal ID') and also discloses the return shape (requested order, missing_ids). The batch/ID-based framing implicitly separates it from get_product and search_products, but no sibling is named explicitly, so it falls just short of the top band.

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

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

Gives clear operating context: public, no OAuth required, and explicit exclusions ('no URLs, buyer actions or writes are accepted'), which tells the agent what inputs will fail. It stops short of naming the alternative path (e.g., use search_products to obtain IDs), leaving that inference to the reader.

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 (readOnly, idempotent, non-destructive, closed-world), it discloses concrete behavioral traits: a 100-attempt result cap, omission of event payloads and secrets, no manual resend side effect, and the required OAuth scope webhooks:read. This is meaningful context the annotations cannot convey.

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

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

Four tight clauses, front-loaded with what the tool returns and its scope, followed by alternative routing, auth scope, and safety. No sentence is redundant with the schema or 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?

Output schema exists so return structure need not be explained, yet the description still clarifies the boundaries of the return (latest 100, no payloads/secrets). With one required, fully documented parameter and annotated read-only safety, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents the ID pattern and warns it is not a delivery ID or signing secret. The description reinforces the provenance of the ID but adds no syntax, format, or filtering semantics beyond what the schema states, 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 gives a specific verb ('Inspect') and resource ('delivery failures or retries') scoped to a webhook subscription, and explicitly differentiates itself from the sibling 'list_webhooks for subscription status'. An agent can distinguish it from list_webhooks and create_webhook 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 states the diagnostic context (failures/retries), the source of the required subscription_id (create_webhook or list_webhooks), and names the alternative tool for a related task (list_webhooks for subscription status). Routing is explicit rather than inferred.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the closing 'Read-only' is redundant. The description nonetheless adds real value beyond them: the required OAuth scope (webhooks:read) and the guarantee that signing secrets are never returned again, which is a non-obvious security behavior for a listing 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?

Front-loaded with the resource and scope, and every sentence carries distinct information (alternatives, downstream use, auth, secret handling). It is somewhat telegraphic and the 'never returned again' phrasing is slightly awkward, but nothing is wasted.

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

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

An output schema exists, so return values need no explanation, and the description covers scope, auth, alternatives and secret behavior. The remaining gap is how large result sets are handled (pagination or ordering) for a no-parameter listing tool.

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

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

Zero parameters, so per the rubric the baseline is 4. The description adds no parameter detail, and notably no pagination/filtering control is mentioned anywhere, though the schema is empty.

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) plus the ownership scope ('owned by this application and buyer session'). It explicitly distinguishes itself from the sibling list_webhook_deliveries, so an agent can route correctly 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 an explicit when-not: 'Use list_webhook_deliveries for delivery attempts, not this listing.' It also names delete_webhook as a downstream consumer of the returned IDs, which tells the agent why to call this first.

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

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

Annotations already cover readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is known. The description adds meaningful extra context: required OAuth scope ('order:prepare'), the fact that it changes buyer or order state, the short-lived nature of the confirmation link, and the explicit exclusion of submission/payment.

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 trigger condition and core action, then the approval requirement, then the scope and state-change note. No wasted words.

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

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

For a state-changing order preparation step, the description covers the prerequisite, the effect, the required OAuth scope, the non-submission boundary, and the human approval flow. Output schema exists, so return values need not be explained.

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

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

The tool has zero input parameters, so there are no parameter semantics to document. Per calibration, a zero-parameter tool starts at baseline 4; the description cannot add param-level meaning beyond that.

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 ('prepare') and resource ('exact order summary and a short-lived browser confirmation link'), with clear scope that it does not submit or pay. Distinguishes itself from siblings like submit_order and get_checkout by naming the prerequisite and the follow-up action.

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

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

Explicitly states when to call it ('After get_checkout validation succeeds'), what must happen next ('buyer must personally approve that summary before submit_order'), and what it does not do (does not submit or pay). Names the alternative/subsequent tool, leaving no ambiguity.

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, but the description adds real context beyond them: required OAuth scope (cart:write), the return payload (refreshed basket), and the explicit boundary that no order or payment occurs. That is meaningful behavioral disclosure for a destructive mutation.

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

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

Tight, front-loaded, and every clause carries information: target, alternative, return value, scope, side effect. The telegraphic style ('no order or payment') is efficient though slightly clipped for readability.

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 shape need not be explained; the description still notes the refreshed basket is returned. With 100% param coverage, full annotations, and the auth scope supplied, an agent has everything needed to call this destructive delete correctly.

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

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

Schema coverage is 100% and the parameter description already says the value must come from this buyer's get_cart response and is not product_id or another buyer's item. The description's guidance restates that same disambiguation, adding emphasis rather than new meaning, 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+resource (delete the complete basket line) and immediately scopes it to the get_cart item_id, explicitly excluding product_id and favorites entries. That exclusion routes the agent away from remove_favorite and makes the target 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?

Names the sibling alternative and the condition that selects it: 'Use update_cart_item to retain the line with a smaller quantity.' Combined with the item_id/product_id/favorites disambiguation, both when-to-use and when-not-to-use are 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description still adds real value by disclosing the required OAuth scope (favorites:write) and that buyer/order state changes. It does not elaborate on reversibility or rate limits, but it goes beyond the annotations rather than repeating them.

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

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

Four short sentences, zero filler, with the core action and the sibling disambiguation front-loaded ahead of the scope/auth details. 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?

For a single-param mutation with an output schema, the description covers the identifier source, the boundary against basket removal, the auth scope, and the state-change side effect. 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?

Schema coverage is 100% and the schema description already explains the product_id provenance and warns against SKU/article or basket item IDs, so the description's restatement adds little new meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Remove a saved product from this buyer's favorites') and immediately disambiguates the identifier ('product_id from get_favorites, not a basket item_id'). An agent can distinguish it from remove_cart_item and add_favorite 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?

Explicitly names the alternative ('use remove_cart_item for that') and the condition that selects it, and clarifies that this does not touch the basket. The routing decision is fully specified rather than inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by noting 'Public; no OAuth required' (auth requirement) and that results are paginated public links and IDs. It doesn't discuss rate limits or cursor expiry, which the schema covers anyway.

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

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

Three tight sentences with the core action front-loaded, followed immediately by the disambiguation and the public/read-only facts. No filler or 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, return-value explanation is unnecessary, and the description covers the pieces an agent needs: what it searches, why it differs from search_products, auth posture, and pagination. Nothing material 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 schema already documents q, page, cursor, and per_page including their mutual-exclusion rules and defaults. The description only alludes to pagination generally and adds no format or syntax detail beyond the schema, 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 (find/browse) and resource (brands) plus its distinctive capability (typo suggestions), and explicitly distinguishes itself from the sibling search_products: 'this finds brands, not products.' 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 clear usage context and an exclusion ('this finds brands, not products'), plus a downstream chaining hint that returned IDs feed search_products.brand_id. It stops short of a full when-to-use/when-not statement against every alternative, but the differentiation is 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 cover readOnly, idempotent, non-destructive, and closed-world. The description adds useful context beyond them: public access with no OAuth required, and that results come as a bounded page with an exact total. It does not add much on failure modes or rate limits, but the annotation bar is already met.

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

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

Three tightly packed sentences, front-loaded with purpose and then the cross-tool workflow. Every clause carries actionable 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?

With a rich schema, full annotations, and an output schema present, the description covers the remaining gap: cross-tool ID sourcing, browse-vs-search behavior, and auth profile. 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 each parameter (q, page, sort, cursor, filters, brand_id, per_page, section_id) is thoroughly documented in the schema itself. The description reinforces the 'do not guess IDs' workflow but adds little parameter-level meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

States specific verbs (find/browse), the resource (current catalog products), and the search keys (name, model, SKU). It also names the sibling tools it works with (get_catalog_filters, search_brands, get_product), so an agent can distinguish it from other retrieval tools without opening schemas.

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

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

Explicitly routes the agent: get filter IDs from get_catalog_filters, brand IDs from search_brands, do not guess IDs, read a selected result with get_product, and narrow overly broad queries. This is clear when-to-use plus named alternatives, which is the top bar.

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?

Goes beyond the annotations (destructiveHint=true, idempotentHint=true) by disclosing the destructive edge case (zero deletes the line), the required OAuth scope cart:write, the return value ('refreshed basket'), and the absence of order/payment side effects. This is exactly the extra context annotations cannot carry.

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

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

Four short sentences, zero filler, and the core semantics (absolute set, item_id source) are front-loaded before the caveats and scope note. 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?

Covers the mutation semantics, the destructive zero case, the auth scope, and confirms no downstream order/payment effects, while an output schema already documents the refresh response. Nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds discriminative meaning the schema states less forcefully: item_id must come from this buyer's get_cart and is 'not product_id', and quantity is absolute rather than an increment. Marginal but genuine added value over 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 precise verb+resource+semantics: 'Set the absolute quantity of a basket line'. It immediately distinguishes the operation from add_cart_item (increment) and remove_cart_item (removal), so an agent can route correctly 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?

Explicit when-to-use and when-not-to-use: zero removes the line, and 'use add_cart_item to increment instead' names the alternative and the condition that selects it. It also tells the agent where item_id comes from (get_cart), closing the main misuse path.

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 destructiveHint=true and idempotentHint=true, but the description adds the concrete mechanism behind that: omitted fields keep their values, empty strings clear them and may invalidate checkout, and clearing phone makes validation fail. It also discloses the OAuth scope (checkout:write) and that buyer/order state changes, which annotations cannot express.

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

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

Five short sentences, each carrying distinct load: mutation semantics, clearing/validation consequences, workflow ordering, scope + non-submission guarantee, and state impact. The most consequential constraint (state changes, does not pay or submit) is stated up front rather than 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?

For a 7-parameter mutation tool with an output schema, this covers everything an agent needs: input sourcing, clearing behavior, validation dependency, required auth scope, and the fact that it neither pays nor submits. Return values are correctly left to the output schema.

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

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

Schema coverage is 100%, so per-field meaning is already documented, including the omission/clearing rules. The description still adds a cross-reference the schema does not contain — that payment and delivery values must come from get_checkout options — which is real value for the two enum parameters.

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 ('Change one or more checkout fields') and immediately distinguishes itself from siblings by naming get_checkout as the source of valid choices and by excluding prepare_order and submit_order. An agent can pick this tool over the four other checkout-adjacent tools 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 ordering ('Read validation before prepare_order'), explicit exclusions ('neither submits an order nor makes a payment'), and names the sibling that supplies enum values ('choices from get_checkout'). This is a full when/when-not/alternative specification.

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