teas.co.uk

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

Goes well beyond the annotations: additive quantity semantics, atomic failure on unknown ids, partial success with per-item messages for out-of-stock/20 kg limit, 'nothing is bought or charged'. These are the exact side-effect details an agent needs before mutating a basket.

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

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

Front-loaded with the trigger and side-effect profile; every sentence carries operational content. Slightly long at six sentences, but none is filler given the failure-mode and host-variation detail.

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

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

Output schema exists so return values need no explanation, and the description covers the remaining gaps: failure modes, partial application, host-dependent basket_id, and confirmation that no purchase occurs.

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 real meaning: quantities are cumulative rather than replacing, ids must originate from find_products, and basket_id is host-dependent. The idempotency_key dedup behavior is left to 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?

Specific verb+resource ('add teas.co.uk products to their basket') with a clear trigger condition ('when someone asks to add...'). It also distinguishes itself from siblings by naming update_basket and checkout_session as different operations.

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: use update_basket to change/remove a line, checkout_session to buy immediately. It also gives the condition for when to pass basket_id ('leave out on hosts that identify the customer; otherwise pass the basket_id from the first basket result').

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

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

Annotations cover safety (destructiveHint, idempotentHint), but the description adds state-dependent preconditions (pause needs active, resume needs paused, cancel works on either), irreversibility ('a cancelled subscription cannot be resumed here'), error semantics ('returns an error and changes nothing'), and the post-state return. That is substantial context beyond the structured fields.

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

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

Front-loads the when-to-use constraint and then the behavioral rules; every sentence carries a constraint or state rule. It is dense but not padded, though it runs long and could be slightly tightened.

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 detailed, and the description still notes the post-state ('returns the subscription as it is afterwards'). Preconditions, error behavior, and sibling routing are all present for a destructive mutation 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%, so the schema already documents action and subscription_id, but the description adds meaning: subscription_id must come from my_subscriptions and ids from other accounts are 'never found', plus the status precondition for each action value. This goes beyond the schema's enum gloss.

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 (pause/resume/cancel a teas.co.uk tea subscription) and explicitly scopes it against siblings by naming my_subscriptions for viewing. An agent can distinguish it from start_subscription or my_subscriptions without opening a schema.

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

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

Gives explicit when-to-use ('only when a signed in customer clearly asks'), a required precondition ('confirm which one and which change with them first'), and names the alternative tool to call first ('To see the subscriptions first use my_subscriptions'). Routing and exclusions are fully 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 only say readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description goes well beyond them: each call mints a new 7-day link usable on any device, the link reflects the basket state at open time, an empty basket returns an error, the assistant never sees payment details, and no order is placed until the customer pays on-site. That is exactly the behavioral context an agent needs before invoking a non-idempotent flow.

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?

Opens with the trigger, then the parameter rule, then the link lifecycle and on-site flow, closing with the sibling alternative. Every sentence carries distinct information (durability, error case, privacy boundary, order timing) with no 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 no explanation, and the description still covers the gaps that matter: error behavior on an empty basket, the hand-off point where the customer authenticates and pays, and the privacy boundary. Complete for a single-parameter checkout-entry 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 schema already documents basket_id, so the baseline is 3. The description earns above-baseline credit by explaining the decision rule behind the parameter (host-dependent identity) and by clarifying that the value comes from an earlier basket tool in the same conversation, adding rationale beyond the field 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?

Names a specific verb (go to checkout / make a link) and resource (the teas.co.uk basket) and states the trigger condition explicitly. It also distinguishes itself from the sibling checkout_session by naming it as the alternative for buying specific products without the basket.

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 ('customer is ready to buy what is in their basket'), an explicit conditional for the single parameter (omit on hosts that identify the customer, otherwise pass the earlier basket_id), and routes to checkout_session for the case where no basket exists. Nothing is left to inference.

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

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

Goes well beyond the annotations by disclosing that nothing is charged until payment on teas.co.uk, that the earlier basket is neither consumed nor modified, that live prices override supplied display fields, and that partial failures are reported in 'unavailable' while the rest proceed, with an error only if nothing is found.

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 trigger and the core behavior, then layers in failure modes and the sibling pointer. It is dense but largely earns its length; the sentence restating that display fields never change the charge partially duplicates schema text that already says 'for display only; not used.'

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 annotations (non-readonly, non-idempotent) and an output schema already present, the description supplies the missing operational context: partial-failure semantics, pricing behavior, and the no-charge guarantee. It stops short of noting session/link expiry or warning that retries create additional fresh sessions despite idempotentHint=false.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: id must come from find_products, offerId is a fallback when an id is not found, display fields never affect the charge, and the 20-item cap and 1–99 quantity range govern the request. Some of this (display-only fields) merely echoes 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 action and resource ('puts exactly these items in a fresh basket... returns a secure link to pay') and explicitly contrasts with the sibling that checks out a pre-built basket. An agent can distinguish it from checkout_link and add_to_basket 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?

Names the triggering situation (customer picked specific products and wants to buy straight away, e.g. from a product result) and routes the alternative case explicitly ('To check out the basket they built, use checkout_link'). When-to-use and the alternative are both spelled out.

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

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

Annotations already cover read-only, idempotent, non-destructive semantics, yet the description adds genuinely new behavior: duplicate ids are counted once, unrecognised ids are surfaced in not_found while the rest still compare, and under-two recognised products errors out. This partial-failure semantics is valuable context, though it stops short of describing the comparison payload itself.

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 and comparison axes are front-loaded, followed by id sourcing, edge-case handling, and sibling routing in short declarative sentences. Every sentence carries distinct information; nothing is redundant 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 annotations covering safety and an output schema covering return shape, the description only needs to explain invocation and edge cases — which it does fully: accepted id forms, dedup, not_found handling, and the error threshold.

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 enforces the 2-4 item bounds, so the baseline is 3. The description goes further by explaining the id source (find_products), that product links are also accepted, and that repeats collapse to one entry — meaning beyond the schema.

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

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

States a specific verb (compare) and resource (two to four teas.co.uk products side by side) with concrete comparison axes. It distinguishes itself from find_products and get_product by name, so an agent can route without opening a schema.

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

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

Gives explicit when-to-use rules and alternatives: search first if you only have names, and use get_product for everything about a single product. It also names the failure condition (fewer than two recognised products returns an error).

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: it is a static policy lookup with no per-caller input and no order access, meaning results are identical for every user and carry no personal data. It stops short of describing output shape, but an output schema exists.

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

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

Three sentences, front-loaded with the trigger condition, then the no-input rationale, then the sibling routing. No filler and no repetition of the title or of annotation-declared traits.

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

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

For a zero-parameter, read-only policy tool the description covers everything an agent needs to select and invoke it correctly, including boundaries against start_return and track_order. Return values are handled by the existing output schema, so the description is not obliged to describe them.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description goes slightly further by explaining why ('the answer is the same for everyone'), pre-empting an agent from hunting for a missing scope argument such as country or order ID.

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

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

States a specific resource and enumerates exactly what it covers: delivery prices, free-delivery thresholds, dispatch times, delivery countries, returns and refunds. It also explicitly says what it is not ('policy only: it never looks at an order'), which lets an agent separate it from order-scoped siblings 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 an explicit trigger condition ('when someone asks about...') plus concrete hand-offs for adjacent intents: start_return for a return and track_order for an order. Both when-to-use and when-to-delegate are stated, leaving nothing to inference.

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

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

Beyond the readOnly/idempotent annotations, it discloses substantial behavior: filters are ANDed, out-of-stock hidden unless include_out_of_stock, no paging with limit/total semantics, a specific fallback drop order for over-narrow queries, which fields are never dropped, and that prices are live and include VAT. This is unusually rich operational context.

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 and front-loaded: purpose, exclusions, then behavior and routing. Every sentence carries information, though the filter-fallback sentence is long and the passage overall is on the verbose side for a single 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?

With 16 params, an output schema, and full annotations, the description covers exactly what structured fields cannot: filter interaction, fallback behavior, stock visibility, result ordering, and routing to sibling tools. 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%, so the schema already documents each parameter, but the description still adds real meaning by clarifying units (max_price per pack in pounds vs max_price_per_cup_pence per cup in pence) and the AND semantics ('every filter given applies at once'). It stops short of explaining the filter-fallback behavior for each parameter, which is covered separately.

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 set (find/browse/choose) and resource (tea, coffee, hot chocolate bought from teas.co.uk) and explicitly excludes general tea knowledge. An agent can distinguish it from siblings like get_product or find_recipes 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?

Gives explicit when-to-use ('someone wants to find, browse or choose ... to buy'), a when-not ('Not for general tea knowledge'), guidance on browsing via filters alone, and named next steps (get_product, compare_products, add_to_basket). Nothing is left to inference.

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

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive); the description adds substantive behavior beyond them: no paging and best-match-first ordering, that an empty list means no match, that alcohol-based drinks are excluded, and that a parameterless call is rejected. These are exactly the traits an agent cannot infer from the annotations.

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

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

Front-loads purpose, then argument rules, then ranking/refusal behavior, then the sibling pointer. Every sentence carries a distinct fact; nothing is restated from the schema verbatim.

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 structure needn't be described, yet the description still clarifies the meaningful result cases (empty list, rank order). For a 3-param, zero-required search tool, 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 baseline is 3, but the description adds real semantics the schema lacks: how query and product_id interact for ranking, the limit range 1-10 with default 5, and the refusal condition. It does not explain query string syntax beyond examples, so it stops short of a 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?

States a specific verb and resource ('find drink and food recipes from the teas.co.uk recipe library') and even scopes the domain with examples (iced teas, lattes, chai, baking). It explicitly separates itself from the sibling find_products, 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 the exact argument combinations ('Give query, product_id or both'), the consequence of neither ('the call is refused'), and routes purchasing intent to find_products. When-to-use and when-not-to-use are both explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: results are in-stock first, closest match first, and grouped into cheaper vs premium buckets by price per cup. It stops short of explaining pagination or exact return shape, but the ranking/grouping disclosure is substantive.

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 zero filler: the trigger condition is front-loaded, the return behavior follows, and next steps close it out. 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?

An output schema exists, so return values need not be fully specified, yet the description still sketches result structure and ordering. Combined with full parameter coverage and a clear usage trigger, an agent has everything needed to select and call this tool 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 description coverage is 100%, so both parameters are already documented. The description reinforces this ('one product id from find_products or a teas.co.uk product link', 'limit sets how many of each come back'), but adds no syntax, format, or edge-case detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource (find substitutes) and immediately distinguishes itself from siblings by describing the returned set: same kind and caffeine, near same strength, split into cheaper and premium by price per cup. An agent can tell this apart from find_products and compare_products 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 names triggering conditions ('out of stock, too dear, or the person wants something similar to try') and routes the agent onward ('get_product for details, compare_products to compare, add_to_basket to buy'). Both when-to-use and follow-up alternatives 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?

Beyond the annotations (readOnly/idempotent/non-destructive), the description discloses non-obvious behaviour: only paid orders yield a result, the return is a link rather than the document, the customer must sign in to open it, and the invoice never passes through the assistant. These are exactly the operational facts an agent needs and cannot get from structured fields.

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

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

Three tight sentences, front-loaded with the usage condition followed by return behaviour and the key limitation. No filler and nothing restated from the schema.

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

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

An output schema exists, yet the description still clarifies the practical return (a PDF link requiring sign-in) and the assistant's non-involvement. Combined with the annotation safety profile and the single well-documented parameter, 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?

Schema coverage is 100% and the single order_number parameter is documented with a format example, so the schema carries the load. The description adds no syntax or constraint detail beyond what is already structured.

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

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

The description names a specific verb (retrieve the invoice) and resource (invoice for a teas.co.uk order), plus the actor precondition (signed-in customer). It is unambiguous among the siblings, though it does not explicitly contrast itself with near-neighbours like my_orders or track_order.

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

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

"Use this when a signed in customer wants the invoice for a teas.co.uk order" gives a clear triggering condition. There is no when-not guidance (e.g. unpaid orders) and no named alternative, but the intended context 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 declare readOnly/idempotent/no-destruct, so the bar is for added context, and the description delivers: price and stock are read live on every call, unknown or discontinued ids return an error instead of a guess, and accepted id forms/case-insensitivity are spelled out. These are traits 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?

Front-loaded with the usage condition, then the id contract, then failure behavior, then the sibling pointer. Every sentence carries distinct, actionable information with no restatement of the name or title.

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

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

For a single-parameter read tool with an output schema (which needn't be described), the definition covers trigger, accepted id formats, failure semantics, data freshness, and sibling routing. Nothing needed 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% (baseline 3), but the description goes well beyond the schema's 'id from find_products or a product link' by adding numeric product id, barcode, any letter case, and the crucial negative rule that a product name does not work. That materially changes how an agent constructs the argument.

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 ('get_product' -> full product details) and enumerates the conceptual fields it exposes (brewing, caffeine, taste, ingredients, allergy advice). It also names the sibling it is not by routing side-by-side viewing to compare_products, so an agent can distinguish it 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?

Explicit trigger ('when someone asks how to brew ... or wants its full details') plus concrete alternatives: find_products for name search and compare_products for comparison. It also states when it will fail (name does not work, unknown/retired id errors) rather than silently guessing.

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/non-destructive/closed-world, and the description adds substantive context beyond them: no input is taken, the id is opaque and stable across sign-ins and reconnections, an error with a sign-in prompt is returned when no account is linked. This is rich behavioral disclosure for a read tool.

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

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

Front-loaded with purpose and tightly written, with each sentence carrying distinct information (purpose, input model, return semantics, error behavior, non-usage). Slightly long for a zero-param tool but nothing is padded.

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, input source, return shape and stability, error/sign-in behavior, and the scope where it is not needed. Output schema exists so return values needn't be enumerated; everything an agent needs to call and route correctly is present.

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 the baseline is 4, but the description goes further by explaining that the account identity comes from the sign-in session rather than any argument. That meaningfully clarifies the input model beyond the empty 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 (confirm) and resource (which teas.co.uk account is linked), and positions itself precisely against siblings like my_orders, my_subscriptions and rewards_balance. An agent can tell it apart from account-scoped tools 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 when to call it (before my_orders/my_subscriptions/rewards_balance, or when the customer asks which account they are signed in with) and when not to (searching, basket and checkout work without an account). Both the affirmative and exclusionary conditions are given.

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, idempotentHint, destructiveHint=false), yet the description adds substantive behavior beyond them: results are sorted biggest-saving-first, restricted to in-stock items, non-public codes are never surfaced, and checkout applies the final price. These constraints materially affect how an agent should interpret and present the output.

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

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

Three sentences, front-loaded with the selection criterion, then output contents and caveats, then next actions. Every clause carries distinct information (trigger, contents, sorting, exclusions, pricing authority, routing) with no filler.

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

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

For a read-only, single-optional-param tool with an output schema that already defines the return shape, the description covers trigger, contents, ordering, caveats, and next steps. Nothing an agent needs to select or 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 there is a single optional 'limit' parameter fully documented with range and default, so the schema carries the weight. The description adds ordering/stock behavior but nothing about the limit argument itself, making 3 the appropriate baseline.

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

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

States a specific verb and resource (lists products on sale) plus the three things it returns: discounted products with usual price and end date, public offer codes, and the free UK delivery threshold. This is clearly distinguishable from siblings like find_products or get_product, which cover non-sale catalog data.

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?

Opens with an explicit trigger ('Use this when the person asks about offers, discounts, codes or what is on sale at teas.co.uk') and closes with concrete routing to the next tools (get_product, quote_cart, add_to_basket) mapped to the follow-up intent. Both when-to-use and what-to-do-next are stated, not 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, and closed-world, so the safety profile is covered. The description still adds real context: the auth prerequisite ('signed in customer'), what the records contain (reference, status, items, dates), and the important semantic caveat that a request is not a refund until approved.

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 usage trigger, then scope, then the refund caveat, then the alternative — four sentences with no repetition or filler. Every clause carries routing or semantic information.

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

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

With an output schema present, the description need not explain return values, and it still summarizes the returned fields. Auth requirement, scope, count semantics, and the sibling route are all covered for a single-optional-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?

Only one parameter and schema coverage is 100%, so the schema fully documents order_number. The description echoes the filtering behavior ('or the ones for one order') but adds no syntax, format, or edge-case meaning beyond the schema text, making baseline 3 correct.

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

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

States a precise verb (lists) and resource (return requests) plus the scope variants (all returns vs. one order). It explicitly names the sibling start_return as the different tool, so an agent can route without inspecting 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?

Gives an explicit trigger ('when a signed in customer asks about a return they started') and an explicit boundary with the alternative ('To start a new return, use start_return'). Nothing about when-not-to-use is left to inference.

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

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

Annotations declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is already covered. The description adds important behavioral context beyond annotations: nothing is typed into the chat; the user signs in or signs up on teas.co.uk in an assistant-opened window. This is useful operational detail for an agent. It stops short of describing the return format or what happens on failure.

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 three sentences and front-loads the trigger condition, but it is somewhat repetitive: the first and second sentences both cover what an account gives and how to link or create one. It could be tightened without losing meaning. Still, it is not bloated and remains readable.

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

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

Given zero parameters, rich annotations, and an output schema, the description need not explain return values. It covers the trigger, the account-linking behavior, the out-of-band sign-in flow, and the fact that shopping works without an account. It is nearly complete, though it does not state what the output schema returns or what happens if the window is closed.

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 baseline is 4. The schema is empty and fully covered, and the description correctly implies no input is collected from the chat. No parameter-related gaps exist.

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

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

The description states a specific resource and the question it answers: whether a teas.co.uk account is linked, what it adds, and how to create or link one. It is clear what the tool does, though it does not distinguish itself from siblings by name (e.g., login/account tools) beyond the account-linking scope. No sibling appears to overlap directly with this onboarding/account-explanation purpose.

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

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

The description provides clear usage context: use it when someone asks about account benefits, creation, or linking, and it explicitly notes that searching, basket, and checkout work without an account. This helps the agent avoid calling it for shopping operations. It does not name specific alternative tools, but the when-to-use condition is well stated.

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

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

Annotations already declare read-only, idempotent, non-destructive and closed-world, and the description adds real behavior beyond them: empty list means no linked account, missing linked account raises a sign-in error, results are newest-first, no paging exists. For a read tool this is unusually rich.

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?

Every sentence earns its place: usage trigger, parameter semantics, edge cases, then sibling routing. Front-loaded with the when-to-use clause and 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?

Output schema exists so return values need no explanation, yet the description still calls out the can_return field. Combined with error and empty-list behavior, an agent has everything needed to invoke and interpret this 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% so the baseline is 3, but the description adds meaning the schema lacks: newest-first ordering, the 1-20 bounds restated, and the rationale for raising limit. It does not add format or edge-case detail beyond that, so it sits just above baseline.

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

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

States a specific verb and resource ('asks about their recent teas.co.uk orders') and scopes it to a signed-in customer. The niche is immediately distinguishable from siblings like my_subscriptions or view_basket.

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 to alternatives with conditions: track_order for one order, reorder to buy again, start_return to return items. It also states when to raise limit ('only when the customer asks about older orders') and that there is no paging.

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 beyond them: no input required, an empty list means there are none, an unlinked account returns an error prompting sign-in, and these schedules never take automatic card payments. It also explains that the returned id is what change_subscription consumes, which is genuine cross-tool behavioral information.

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 trigger condition and the primary payload, then the edge cases and the hand-off to change_subscription. It is denser than strictly necessary, but each sentence carries distinct operational 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?

An output schema exists, so return-format detail is unnecessary; the description instead supplies the things the schema cannot: the sign-in prerequisite, empty-list semantics, payment-model caveat, and the id contract with change_subscription. Nothing an agent needs to invoke 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?

There are zero parameters and the schema is fully self-describing, so the baseline is 4. The description confirms the no-argument nature ('It takes no input'), which is accurate but adds little the empty schema did not already convey.

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 (lists every subscription on the linked account) plus exactly what each entry conveys: what it sends, frequency, next delivery, price, active/paused status. It is immediately distinguishable from change_subscription, which it names as the mutation counterpart.

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 scopes the trigger ('when a signed in customer asks about their ... subscriptions') and routes the pause/resume/cancel cases to change_subscription by name. It also covers the no-linked-account failure path, so the agent knows the expected outcome in that condition.

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

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

Annotations already establish readOnly, idempotent, non-destructive, so the bar is lower; the description still adds real context (live prices incl. VAT, delivery options per country/parcel, free-delivery gap, basket link) and explicitly states nothing is stored. The 'no basket changes' line partially restates the annotations, but the read-behavior specifics go beyond 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?

Front-loads the purpose and the pre-basket constraint, then packs return contents and sibling routing into two further sentences with no filler. Every sentence earns its place.

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

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

For a read-only pricing tool with full schema coverage and an output schema, the description supplies the routing guidance, the side-effect profile, and the shape of the result. Nothing an agent needs to select or 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 id, quantity, and country semantics. The description only restates the item shape and the 20-item cap, adding no format or edge-case detail beyond structured data; 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 ('price products') plus the scope ('before anything goes in a basket'), and explicitly distinguishes itself from add_to_basket and checkout_link. An agent can identify the right tool 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 an explicit when ('price for the person before anything goes in a basket'), names the two alternative siblings, and states the condition that selects each ('for a basket the person keeps' vs 'to hand over checkout'). Nothing is left to inference.

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

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

The description discloses rich behavior beyond the annotations: today's prices, stacking on the existing basket, skipping unbuyable items (discontinued, out of stock, over 20 kg) into messages, error when nothing is found, repeat-call accumulation, and that nothing is charged until payment. This is exactly the mutation context the sparse annotations (destructiveHint=false, idempotentHint=false) 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?

It is long but dense and front-loaded with the use case, and nearly every clause carries behavioral or routing information. Minor repetition of 'added' wording keeps it just short of maximally tight.

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 basket-mutating tool with an output schema, it covers the failure modes, skip-and-report behavior, pricing semantics, and no-charge guarantee. 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: order_number originates from my_orders and only linked-account orders resolve, while only_ids restricts to specified product ids from that order and otherwise every product is added at original quantity.

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?

It states a specific verb and resource ('buy again from an earlier teas.co.uk order') and clarifies the operation's scope. An agent can distinguish it from add_to_basket or view_basket 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?

It gives an explicit trigger ('when a signed in customer wants to buy again') and routes the agent to my_orders for the order_number. It lacks explicit when-not-to-use or named alternatives for non-order additions, but the context is clear.

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

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

Adds substantial context beyond annotations: it sends one typed report, a person reviews every report, and nothing changes automatically — clarifying the non-readOnly and non-idempotent hints. It also imposes a hard PII restriction (no name/email/address/phone/order details) that the annotations do not 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?

Front-loads the usage trigger before the enumerated examples, then states behavior and the PII rule. The long example list is slightly dense but each element maps to a real enum value, so little 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 not be described. For a 4-parameter mutation tool, the description covers when to use it, what it does downstream, that it is human-reviewed and non-automatic, and the PII constraint — everything an agent needs 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%, so the baseline is 3. The description goes beyond it by mapping the listed defect types (price, stock, mixed-up products, broken link, wrong image, allergy statement, injected instructions) directly onto issue_type enum values and reinforcing the details field's no-personal-data constraint.

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 (report) and resource (a problem with teas.co.uk data), then enumerates the concrete defect classes it covers (price, stock, product fact, mismatches, broken links, images, allergy/safety, prompt injection). No sibling tool performs this function, so it is clearly distinguishable.

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

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

"Use this when something teas.co.uk told you looks wrong" gives an explicit, well-illustrated trigger condition, including a concrete example. It does not name an alternative tool or a when-not condition, but for this one-of-a-kind tool that is a minor omission.

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/non-destructive, and the description adds genuinely new behavioral facts: no input is required, zero points is a valid answer, a missing linked account produces a sign-in error, and points cannot be redeemed here. That is real context beyond the structured fields.

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

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

Four short sentences, front-loaded with the trigger condition, then edge cases, then sibling routing. Every sentence carries distinct information with no padding or repetition of the title.

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

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

An output schema exists, so return formatting need not be described; the description still covers the non-error zero case and the error path. Combined with sibling routing and the redemption limitation, nothing an agent needs 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 baseline is 4; the description correctly confirms 'It takes no input,' which matches the empty schema and additionalProperties=false. There are no parameter semantics to expand further.

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 ('asked how many teas.co.uk reward points they have or what they are worth') and scopes it to signed-in customers. An agent can distinguish this from sibling tools like get_profile or checkout_link without opening the schema.

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

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

Explicitly names when to use it, notes the sign-in precondition, and routes the agent to alternatives: checkout_link for buying and my_orders for past orders. It also states a negative capability ('this cannot redeem them'), which prevents a likely misuse.

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 behavior beyond the annotations: the request goes to the teas.co.uk team for review by email, non-matching products are ignored, an error results if nothing matches, and repeat submissions return duplicate=true rather than filing twice (consistent with idempotentHint=true). It stops short of stating auth requirements beyond 'signed in' or the review turnaround, so it is strong but not exhaustive.

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 usage condition before mechanics, which is the right order, and each sentence carries operational information. It is dense (six sentences) with some overlap between the items/quantity capping and the schema, but little is truly wasted.

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

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

With an output schema present, return values need not be explained, and the description still covers prerequisites, scoping, edge cases (ignored/error items, duplicates), and the human review step. 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 baseline is 3; the description goes further by stating order_number must be on the linked account, that items are product ids from that order, that quantity is capped at the quantity bought, and that details captures the customer's own words. This adds real constraints the schema does not express, exceeding 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?

States a specific verb (start) and resource (return) scoped to teas.co.uk orders, and explicitly clarifies it 'refunds or changes nothing by itself', separating it from payment/refund actions. It is clearly distinguishable from siblings like my_orders and track_order, which it names as prerequisite sources.

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 gating condition ('only when a signed in customer clearly asks to return items'), prerequisite steps (confirm order/items/reason, check can_return), and routes policy questions to delivery_and_returns. When-to-use, when-not, and alternatives are all 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?

Goes far beyond annotations: explains that it orders and charges nothing, later deliveries are new orders with the same discount, emails five days before, no automatic card payments, and pause/resume/cancel is possible. Also notes the 'eligible' false case with a reason. This is rich behavioral context that annotations alone do not cover.

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

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

Well-structured and front-loaded, but somewhat long and dense. Every sentence adds value, though it could be trimmed slightly without losing 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?

Complete: purpose, usage, return values (subscriber price, frequency, link), what it does not do, ongoing behavior, and eligibility failure are all covered. With an output schema present, no further return value explanation is needed.

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 baseline is 3, but the description adds meaning by explaining that the id can be a product id from find_products or a teas.co.uk product link, and the limit 'one product id' reinforces the single-parameter constraint.

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: starts a repeat delivery subscription for a teas.co.uk product. It clearly distinguishes from siblings like add_to_basket or checkout_session by describing the subscribe-and-save 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?

Explicitly states when to use it ('when someone wants a teas.co.uk product delivered again and again'), what to pass (one product id from find_products or a link), and what it does not do ('orders and charges nothing'). It also names related tools for managing the subscription (my_subscriptions, change_subscription).

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 goes well beyond them: account-scoped lookup that returns a not-found error for other numbers, courier tracking links once shipped vs a dispatch-time note before shipping, and the meaning of can_return as a downstream gate for start_return. This is exactly the behavioral context 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, front-loaded with the usage trigger and closing with the alternative tool. Every sentence carries non-redundant information (format, scope, shipped/unshipped behavior, can_return), and none restates the title or name.

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

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

Despite an output schema existing, the description adds the differential response behavior (tracking links vs dispatch note) and the cross-tool can_return signal, so nothing an agent needs to call and interpret 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema lacks: the number can come from my_orders or the confirmation email and may carry a leading '#'. It stops short of covering the 1-40 length bound, which the schema already handles.

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 ('track' a single teas.co.uk order) and immediately scopes it to one order for a signed-in customer, which cleanly separates it from the sibling my_orders that handles lists. An agent can distinguish it from start_return and my_orders 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?

'Use this when a signed in customer asks where one teas.co.uk order is' gives the trigger condition, and 'For a list of recent orders use my_orders' names the alternative and the condition that selects it. The can_return mention also routes to start_return, covering the third closely-related sibling.

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, and the description reinforces and extends them: 0 removes the line, re-sending the same quantity is a no-op, nothing is bought or charged, and over-limit/unknown-id attempts leave the basket unchanged while reporting in messages. This is unusually rich disclosure beyond the annotations.

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

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

Dense but front-loaded: the core action and the critical 'total not additive' distinction come first, followed by edge cases. Every sentence carries meaning, though the run of short clauses is slightly denser than ideal.

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 failure modes (unknown id, parcel limit, no basket, no-op), side effects (nothing bought/charged), and the id source. Complete for this mutation 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%, so baseline is 3, but the description adds genuine semantic meaning the schema lacks: 'quantity is the new total from 0 to 99, not an amount to add; 0 removes the line' and where id comes from. It does not clarify the optional basket_id parameter, keeping it 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?

States a specific verb+resource ('change the quantity of a product in the teas.co.uk basket') and explicitly distinguishes itself from the sibling add_to_basket at the end. An agent can pick it apart from view_basket and add_to_basket 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 (change quantity, add a not-yet-present product via quantity>0) and when-not-to-use ('To add new products use add_to_basket'), plus edge-case routing for unknown ids and the 20 kg limit. Nothing is left to inference.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing that prices and stock are re-read on every call, that a basket is retained 35 days after its last change, and that an unknown or never-filled basket returns an empty result rather than an error. These are exactly the freshness and edge-case behaviors an agent needs and cannot get from annotations.

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

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

Front-loads what the tool returns, then layers behavior (refetch, retention, empty-result semantics), then closes with sibling routing. Each sentence carries distinct information with 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?

With an output schema present, return values need not be explained, and everything else an agent needs — freshness, retention window, empty-result behavior, and alternative tools — is covered. 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 coverage is 100% with a single optional parameter, and the description's guidance on basket_id ('only for hosts that do not identify the customer, pass the one an earlier basket tool returned') largely restates the schema's own parameter description. Baseline 3 applies since the schema already carries the semantics.

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

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

States a specific verb (view/show) and resource (the customer's teas.co.uk basket), and names the concrete contents returned: live subtotal and delivery estimate. It is immediately distinguishable from add_to_basket, update_basket and checkout_link, which are named as the mutating 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?

Explicitly says when to use it (to show basket contents) and routes each adjacent action to its own tool: add_to_basket for adding, update_basket for quantities, checkout_link for paying. It also states the condition under which basket_id must be supplied versus omitted.

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