shop

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the crucial scope of that destruction — only the open attempt is stopped, settled payments are untouched and reported back as 'paid or still processing'. It also discloses the authentication requirement (Bearer mo1_…) and the state change that results (cart reopens).

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

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

The core action is front-loaded and every sentence carries operational content — scope, exclusions, shopper confirmation, auth, follow-on tool. It is a dense single paragraph, though, and the parenthetical about bank transfer could be trimmed without losing much.

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

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

For a destructive single-parameter tool with no output schema, the description covers everything an agent needs: what it affects, what it refuses to affect, what the response signals, required credentials, and how to recover the flow afterward. No meaningful gap remains.

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

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

Schema coverage is 100%, so the schema already documents the single 'ref' parameter, and the description adds the meaningful fallback rule: the reference is only needed when the client cannot send it as an Authorization: Bearer header. It does not add format detail beyond the schema's mo1_… prefix, so it stays just above the baseline.

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

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

The description opens with a specific verb and resource — 'Stops the open payment attempt of the order' — and immediately scopes it to attempts that are still open, which cleanly separates it from check_payment (read status) and place_order (start a new payment). An agent can identify the correct tool without inspecting the schema.

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

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

It gives concrete when-to-use triggers ('a bank or card page the shopper closed or wants to replace'), an explicit when-not rule ('A payment that already went through is never cancelled'), and names the follow-on alternative ('place_order can start another method'). It also imposes a procedural gate: 'Ask the shopper before cancelling.'

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 needs no repetition. The description adds real behavioral context beyond that: results come in menu order, the payload includes product counts and ids, and querying a category via search includes subcategories (a hierarchy behavior an agent could otherwise get wrong).

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

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

Two tight sentences, front-loaded with what the tool returns and followed by the usage handoff. The parenthetical '(subcategories included)' is the only slightly embedded aside, but it earns its place by preventing a misinterpretation of the search call.

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

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

With no output schema and no parameters, the description carries the burden of explaining the return shape, and it does: ids, product counts, menu ordering. It could go further on whether empty categories appear or how nesting is represented, but for a zero-parameter read-only listing tool it is close to 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?

The tool takes zero parameters, so there is no input schema semantics to add and the baseline is 4. The mention of `category: [id]` and sort options describes a downstream call to `search`, not parameters of this tool, which is correctly framed as guidance rather than schema restatement.

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

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

States a specific resource (the store's product categories) and what it returns (ids, product counts, menu order) in the first sentence. It also names the sibling tool `search` for the follow-up action, so the agent can distinguish this listing tool from the search tool 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?

Explicitly tells the agent how to act on the results: browse one category with `search` and `category: [id]`, with concrete examples (sort newest or bestseller). It gives clear positive guidance but doesn't state when this tool should be avoided (e.g. vs store_info for general metadata).

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, closed-world behavior, so the bar is lower; the description still adds real context by explaining the auth path (Bearer mo1_… or the ref argument) and the state-machine consequence that a failed/cancelled payment reopens the cart. It does not state whether polling is rate-limited or how stale the state can be, but the meaningful behavioral additions are there.

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

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

Two tight sentences with no filler, and the core payload (payment state) is front-loaded before the retry flow. The opening sentence is a verbless fragment, which makes it slightly telegraphic, but nothing is redundant.

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

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

For a one-optional-parameter read tool with no output schema, the description covers what comes back (state, last attempt, next step), how to authenticate, and what the outcome implies for place_order. Missing only edge details such as behavior when the reference is unknown or invalid.

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

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

There is only one optional parameter and schema coverage is 100%, so the schema already documents ref fully (format, source, fallback condition). The description restates the same auth-or-ref choice rather than adding new meaning, which is the expected baseline-3 outcome for a fully documented single parameter.

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

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

The description names the resource (the order's payment) and enumerates what it reports: state (unpaid, pending, paid), last attempt, and next step. That is concrete enough to separate it from cancel_payment or order_history. It is phrased as a noun fragment rather than a verb ('check/retrieve'), which costs it the top score.

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

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

Usage is only implied: the reader can infer this is the status probe used after a payment attempt, and that place_order is the follow-up when the payment failed or was cancelled. There is no explicit 'use this when…' clause and no mention of when to prefer cancel_payment or order_history instead.

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 well beyond the annotations: the cart freezes while a payment is open and after placement, quantities are clamped to stock with the response saying so, tier prices and discounts apply automatically, and op_id gives 10-minute deduplication. The conditional idempotency via op_id is an addition to idempotentHint=false rather than a contradiction, since it is scoped to a repeated id.

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

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

Front-loads purpose and op semantics before moving to response shape, freeze rules, auth, and idempotency. It is dense and slightly run-on in places (the packages/pieces example, the hint sentence), but nearly every clause carries operational 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?

Despite no output schema, the description explains the meaningful return fields (minimum, lines[].hints, also, lines[].replacements) and their use. Auth (Bearer mo1_… or ref), the start_order prerequisite, and the frozen-cart states are all covered, which is thorough for a destructive multi-op tool.

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

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

Schema coverage is already 100%, yet the description still adds meaning: the packages-vs-pieces unit rule (100 pieces of a 6-piece package is 17 packages), the link between search quantity.pieces and for_quantity, the op_id format and 10-minute replay window, and when ref is needed. This is real semantic value on top of the schema.

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

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

States a specific verb and resource ('Change or read the order's cart') and enumerates the three op types (add/set/remove) keyed by product id, plus the read case when ops is omitted. An agent can tell exactly what the tool mutates or returns without opening the schema.

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

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

Gives concrete when-to guidance: offer products/hints when it helps the shopper, ask before changing their order, and tag the accepted hint on the op. It also names cancel_payment as the way to unfreeze a cart during an open payment. It does not contrast with view_checkout/set_checkout siblings, which would be the finishing touch.

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 the description adds real context on top: cursor paging, the 20-order cap for the detail view, that 'payable' marks a placed-but-unpaid order, that unpaid orders carry pay_link, and that the answer self-reports coverage and how to fetch the remainder. Authentication mechanics (Bearer mo1_… or the ref argument) fill the gap left by the absent auth annotation.

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 resource and scope, then separates the two views with a semicolon-delimited structure that maps onto the view enum. It is dense and slightly run-on, but every clause (status list, date filter, cursor, 20-order cap, pay_link) carries information rather than filler.

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

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

With no output schema, the description carries the return-shape burden and does so: field-level expectations for the list view (status, dates, totals) and the detail view (lines with live price and stock, totals, shipping, payment, tracking, addresses). Limits, paging, auth, and partial-result behavior are all covered, which is complete for an 8-parameter read tool.

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

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

Schema coverage is 88% so the baseline is 3, but the description goes further by explaining the otherwise-undocumented 'view' enum (what 'orders' returns vs. what 'order' returns) and by restating status values and filtering semantics in prose. It adds genuine meaning beyond the per-property descriptions rather than duplicating them.

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

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

Opens with a specific verb+resource ('The shopper's earlier orders with this store') and then splits the two modes precisely: 'orders' as a filtered, cursor-paged list and 'order' as up to 20 full orders by id. An agent can tell this apart from start_order, place_order, or check_payment without inspecting the schema.

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

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

Gives concrete usage intent ('Use it to reorder or answer questions about earlier orders') and states the prerequisite (the order reference from start_order via Bearer or ref). It does not name which sibling to use instead for adjacent needs such as payment status (check_payment) or cart changes (edit_cart), so routing guidance is clear but not exhaustive.

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

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

Beyond the annotations, the description discloses the payment-step output shape (payment.url, bank-transfer instructions, voucher, pay_link validity), the cart-freeze behavior in path B, account creation on payment success, and the stock_changed recovery flow. It also explains auth and the op_id dedupe window, which usefully qualifies the idempotentHint=false annotation without directly contradicting 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?

The description front-loads the core action and organizes the workflow into path A, path B, stock_changed recovery, auth, and op_id idempotency blocks with little filler. It is dense and repeats some parameter rules already present in the schema, which keeps it from being maximally concise.

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

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

For a complex multi-step order/payment mutation with no output schema, the description supplies the important return signals (payment.url, pay_link, stock_changed/ready) and the sequencing constraints needed to call it safely. Auth and retry semantics are also covered, so nothing critical 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 already 100%, so the baseline is 3. The description still adds workflow meaning to accept_terms, op_id, add, and the agreed total, linking them to explicit consent, dedupe, stock replacement, and confirmation. It does not add much independent meaning for payment_method or accept_stock_changes beyond the schema, so 4 rather than 5.

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

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

The description opens with a specific verb and resource: 'Place the order and start its payment.' It also distinguishes the two placement paths (confirmed email vs. pre-confirmation) and ties the tool to the order reference from start_order, so an agent can separate it from cart and payment-check 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?

It gives explicit when-to-use guidance: confirm total and terms first, send accept_terms only after explicit consent, and use the reference from start_order. It also names alternatives/related tools such as start_order and check_payment, and states the stock_changed retry condition after shopper agreement.

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 the safety profile is covered. The description adds real value beyond them: the 10-id ceiling, a detailed inventory of what the response contains (tiered prices in EUR and storefront currency, stock in packages, photos), and the notable caveat that 'Photo facts are observations, not guarantees' — a data-reliability warning no annotation carries.

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

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

The essential facts — verb, limit, id source — are front-loaded, and the long field enumeration earns its space because there is no output schema to describe the return payload. It is a dense single sentence rather than a run-on of redundant claims.

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

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

With no output schema, the description correctly compensates by enumerating returned fields, and it discloses the id source, the batch limit and a data-quality caveat. The main remaining gap is undefined edge behavior — whether more than 10 ids errors, truncates, or how unknown ids are reported.

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

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

Schema description coverage is 100% and there is only one parameter, whose description already says 'Product ids, at most 10'. The prose merely restates the batch limit, so it adds no syntax or format meaning beyond the schema; 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?

Opens with a specific verb and resource ('Full details of up to 10 products by id') plus a hard batch limit, and names where the ids come from ('from search or a category'), which cleanly separates it from the search and categories siblings. An agent can tell it apart from those tools without opening the schema.

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

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

The parenthetical 'from search or a category' establishes the prerequisite workflow that produces the ids, so the agent knows this is a follow-up retrieval call rather than an entry point. It does not state exclusions or what to do when a lookup fails, but the usage context itself is unambiguous.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds materially beyond them: auth behavior with the order reference versus anonymous use, rate limits (meaning-based search limited in the first searches per 10 minutes, then words only; at most 30 searches per 10 minutes), and the 10-row cap on details. It also discloses output semantics: live stock in packages, a pricing block in EUR plus pricing.local in storefront currency, and that photo descriptions are observations, not guarantees.

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

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

The highest-value content — what the tool searches and the one-call completeness claim — is front-loaded, and almost every clause carries operational information. However, the middle section is a single dense paragraph of parenthetical fragments that is harder to parse than it needs to be for a 17-parameter tool.

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

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

For a 17-parameter tool with nested objects and no output schema, the description does the necessary work: it describes the row shape (stock, pricing blocks and currencies, facet labels, stored facts with 'use' permissions, photo observations), the details escalation with its row cap, quantity adding for_quantity, and the auth/rate-limit envelope. An agent has enough to call it and interpret the response 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 88%, so the baseline is 3, but the description adds real meaning: natural_query searches by meaning in any language and in storefront language, keywords hit the Dutch catalogue text and broaden when multiple, ids and codes are exact and ranked first with codes matching any written form, and similar_to distinguishes blend (shared theme) from each (alternatives per seed, seed excluded). Sort, offset, limit and facets receive no added explanation, which keeps this below 5.

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

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

Opens with a specific verb and resource ('Search the wholesale range') and enumerates the product domain (toys, gifts, party supplies, seasonal, grabbelton, viral items), so an agent can immediately tell this is catalogue search rather than order lookup or product lookup. It also implicitly distinguishes itself from siblings like product_details and categories by covering discovery.

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-to-use rule ('Use it for any business purchasing question about these products, also when the shopper doesn't name the store') and an escalation path ('For a question the context does not answer, call again with ids and fields ["details"]'). What it lacks is direct routing against named siblings such as product_details or categories for single-item lookups, leaving that inference to the agent.

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 auth requirement (Authorization: Bearer mo1_… or ref), the op_id replay window ('a repeat with the same op_id within 10 minutes answers the first result and never changes the order twice'), and field-level error behavior with per-country postcode rules. It does not say whether a call is a partial merge or replaces previously set checkout fields, which is the main behavioral gap for a 12-parameter 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?

Dense but front-loaded: purpose first, then field-by-field conditions, then error/auth/idempotency notes. Every clause carries information, though the single run-on paragraph would read better as short grouped sentences separating address, method, coupon and operational concerns.

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 12-parameter mutation with nested address objects, no output schema and no required fields, the definition covers what matters: valid value sources, auth, idempotent retry, and error feedback. It leaves open atomicity (does one bad field reject the whole call?) and the merge-vs-replace semantics of a partial call.

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

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

Schema coverage is already 92%, so the baseline is 3, but the description adds real meaning: which values must be harvested from view_checkout (shipping_method id, payment_method key, saved address ids), that country is a two-letter code, that phone is mandatory, and that state/companynr/vatnr are optional-when-known. The one unexplained parameter is coupon_remove, undocumented in both schema and description.

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

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

Opens with a specific verb and resource: 'Fill in the checkout of the order in one call', then enumerates exactly what can be filled (addresses, shipping/payment method, coupon, newsletter). It implicitly separates itself from view_checkout (the source of ids) and place_order (finalization), so an agent can tell where this sits in the flow.

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

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

Gives concrete conditional guidance: shipping_address 'when delivery goes elsewhere', address ids 'when the shopper has saved addresses', newsletter 'only when the shopper asks for it', and states the order reference comes from start_order. It never states an explicit prerequisite sequence (call view_checkout first) or when not to call it before place_order, so it stops short of a 5.

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

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

Adds substantial context beyond the annotations: it lists every method with EUR/storefront currency, VAT inclusion, weight band, cheapest method, and cost-reduction options. It also discloses Authorization Bearer/ref handling, anonymous access, and search rate limits.

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

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

It front-loads the purpose, but then runs long with semicolon-heavy asides about Apeldoorn pickup, forwarders, freight marketplaces, and the store chat. Those details may be useful business context, but they dilute the invocation-critical 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 read-only quote tool with no output schema, it explains return contents, currency and VAT treatment, auth modes, anonymous use, and rate limits. An agent has enough information to call it correctly and interpret the response.

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 all four parameters are already documented with defaults and package-quantity meaning. The description reinforces mutual exclusivity among ref, products, and weight_kg, but adds little new syntax or constraint detail beyond the schema.

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

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

States that the tool returns shipping costs and transport options and explains that it prices an order's cart or supplied products/weight. The core purpose is clear, though the broad phrase 'transport options' and the custom-transport advice stretch beyond the quote 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?

Gives concrete selection rules: use the order reference for cart pricing, otherwise supply weight_kg or products; country defaults to the cart or storefront country. It also routes pickup to set_checkout and notes anonymous use, though it does not explicitly exclude other quote-related siblings.

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

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

Goes well beyond the annotations (which only say it is a non-idempotent, non-destructive, open-world write) by disclosing the side effect of one confirmation email to the shopper and the requirement to ask them first. It also explains the lifetime and scoping of the returned reference: endpoint-specific, expiring 30 days after last use, or 7 days while unconfirmed.

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, then credentials, then the returned reference and its lifetime — a logical order with no filler sentences. It is dense, with long parenthetical clauses, but every clause carries operational meaning.

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

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

With no output schema, the description correctly carries the return contract (order reference mo1_…), how to present it on later calls, and its expiration semantics. For a two-parameter entry-point tool, an agent has everything needed to invoke it and reuse its result.

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 already 100%, so the baseline is 3; the description earns above that by explaining the consequence of each choice — the email path triggers a confirmation email to the shopper, while the key is an alternative they created on their account. It does not add format or validation detail for either value.

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?

"Start an order for the shopper on this storefront" names a specific verb and resource, and the credential/return-value details make the entry-point nature unambiguous. It stops short of naming the sibling it differs from (place_order, set_checkout), so an agent must infer that this opens rather than completes a checkout.

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 caller learns it needs an email or connection key and that consent should be obtained first, which is useful prerequisite guidance. However, there is no explicit when-to-use versus place_order, view_checkout, or order_history, and no statement that this must precede those calls.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the auth prerequisite (Authorization: Bearer mo1_… or the ref argument) and notes the pending-until-email-confirmed lifecycle, which is useful beyond annotations. It does not describe rate limits, error behavior, or what happens with an invalid/expired reference.

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

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

The first sentence front-loads the return payload and the second gives usage and auth prerequisites, so the structure is logical. The parenthetical lifecycle list is dense but informative; the auth parenthetical slightly duplicates 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?

For a single-optional-parameter read tool with no output schema, the description covers the return payload, lifecycle states, auth requirement, and triggering situations. Missing only minor details such as behavior on an invalid reference or pagination (unlikely needed here).

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

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

Schema coverage is 100%, and the schema already explains that ref is the mo1_… reference used only when the client cannot send the Bearer header. The description repeats the auth alternative without adding format or precedence detail beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific resource (the order reference) and enumerates exactly what it returns: order state, email confirmation, cart lines and totals, remaining checkout needs, and next step. It is clearly a read/status tool distinct from siblings like view_checkout or check_payment, though it does not explicitly contrast itself with those siblings.

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

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

It states concrete triggers: 'Use it to resume an order and after the shopper says they confirmed the email.' That gives clear when-to-use context. It does not name which alternative to use instead when the shopper has not yet started an order, and there are no explicit exclusions versus view_checkout or order_history.

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 the safety profile is covered. The description adds modest context: it returns static reference data with no inputs required, and the shortlinks are stated to work on the website, which is a real behavioral detail. It does not describe freshness, caching, or whether contact/opening-time data can be stale.

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

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

The description is markedly overlong for a zero-parameter info tool, with a sprawling nested parenthetical listing product categories and a closing sentence ('The store sells to businesses and organisations') that merely restates 'selling wholesale to businesses' from the opening. The returned fields are also enumerated twice in different words. It is front-loaded in spirit but poorly structured.

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

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

With no input schema and no output schema, the description carries the full burden of explaining what comes back, and it does enumerate the returned fields and links. It is complete enough to call correctly and set expectations, though it spends words on marketing taxonomy instead of confirming the shape of the response.

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 conveys that the call needs no arguments and returns a fixed set of store attributes.

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

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

The description clearly identifies the resource returned: the store's profile, contact details, opening times, currency, product count, and links to terms/privacy/shipping/contact/about/route pages. It is distinguishable from siblings like product_details or search because it is about the seller, not the catalog. It loses a point because the core statement is buried in a long parenthetical rather than stated as a crisp verb+resource sentence.

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 line 'Show the shopper who sells and on which terms before ordering' implies a pre-purchase context, which is a useful timing hint. However, it names no alternatives and gives no explicit when-not guidance, so an agent must infer that this is the right tool for seller/terms questions rather than order or product questions.

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 the safety profile is covered. The description adds behavior annotations do not: payment method availability differs between a confirmed email (path A, bank transfer included) and pre-confirmation (path B, card/iDEAL/Bancontact, pay first), and the order is locked while a payment is open. Auth via Authorization: Bearer mo1_… or the ref argument is also disclosed.

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

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

The content is dense but the opening sentence is a long list that trails off into 'and next', which reads as broken or truncated and forces the agent to infer the verb. Later sentences are well-formed and the payment-lock warning is front-loaded appropriately, but the lead sentence should have started with what the tool does.

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

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

There is no output schema, so the field enumeration (lines, totals, addresses, shipping, payment methods) does real work in telling the agent what comes back. Authentication and the reference source are both covered. Error or empty-checkout behavior is not described, which is a minor gap for a read-only tool.

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

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

Schema coverage is 100% and the single ref parameter is already documented as the start_order reference for clients that cannot send the header. The description reinforces this by naming the Bearer mo1_… header as the primary mechanism and ref as the fallback, clarifying precedence rather than duplicating 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?

The description enumerates exactly what the call returns (lines, totals in storefront currency, address snapshot, shipping methods with prices, allowed payment methods), so an agent knows this is a read of the order's checkout state. It also names check_payment, cancel_payment and start_order, which separates it from those siblings. It never states the retrieving verb explicitly, relying on the tool name to carry that.

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

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

It gives real routing context: while a payment is open the order is not editable and the agent should look at check_payment or cancel_payment instead. It also says the order reference comes from start_order. What is missing is a direct statement of when view_checkout itself is the right call versus set_checkout or place_order.

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