teas.co.uk

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses the crucial behavioral fact that 'Nothing is bought or charged; the customer pays later on teas.co.uk', and describes what comes back (basket, live subtotal, delivery estimate). It does not cover failure modes or whether repeated adds merge or duplicate quantities, 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?

Four sentences, each carrying distinct information: trigger, action/return, non-purchase guarantee, and state-chaining rule. The most important routing information is front-loaded and there is 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?

Although an output schema exists, the description still gives the agent the essential framing (products are added, not purchased, and a basket_id may need to be threaded through subsequent calls). Combined with 100% schema coverage and full annotations, nothing needed 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine cross-call semantics by explaining that a returned basket_id must be passed to every later basket tool in the conversation. That is meaning the schema cannot express on its own, lifting it 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?

The description states a specific verb and resource ('Adds the products ... to a basket kept on teas.co.uk') and scopes it to teas.co.uk products, which cleanly separates it from siblings like view_basket and update_basket. An agent can identify the operation 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?

It gives a clear trigger ('Use this when someone asks to add teas.co.uk products to their basket') and names the prerequisite source of ids ('ids from find_products'), plus the chaining rule for basket_id in later calls. It never states an explicit when-not or names an alternative tool, so it falls 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?

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the signed-in-customer requirement, the mandatory customer confirmation, and the post-state ('Returns the subscription as it is afterwards'). It does not, however, spell out irreversibility or failure behavior in its own text.

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 usage restriction and confirmation requirement before the return note and the sibling pointer. Each sentence carries a distinct piece of information with no filler.

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

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

With an output schema present, return-value detail is optional, yet the description still notes the post-state. Between the annotations (destructive, non-idempotent), the fully documented schema, and the description's preconditions and alternative-tool routing, an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100% and the enum for 'action' is richly documented, including that a cancelled subscription cannot be resumed. The description's only parameter-related contribution is the instruction to confirm the subscription and action with the customer, which is procedural rather than semantic, so the baseline 3 applies.

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

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

The description names a specific verb set (pause/resume/cancel) against a specific resource (teas.co.uk tea subscriptions) and scopes it to signed-in customers. It is clearly distinguishable from my_subscriptions, which it explicitly references as the discovery step.

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 an explicit precondition ('only when a signed in customer clearly asks'), a required confirmation step ('Check which subscription and which change with the customer first'), and names the alternative tool for seeing subscriptions first. Nothing about when to use it is left to inference.

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

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

Annotations already declare this is not read-only, not destructive, not idempotent, and closed-world. The description adds genuinely new behavioral context: the assistant never sees payment details, no order is placed until the customer pays on teas.co.uk, and the customer must sign in or create an account. It stops short of noting that repeated calls yield different links (consistent with idempotentHint=false) or any expiry behavior.

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

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

Three sentences, each earning its place: trigger, what is returned plus the safety boundary, and the sibling alternative. The action and the constraint are front-loaded 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?

An output schema exists, so return-value detail is unnecessary; the description still flags that the return is a link rather than an order. Combined with explicit safety boundaries and sibling routing, nothing needed to invoke this tool 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 basket_id parameter is fully documented in the schema, including the host-dependent condition for supplying it. The description adds no parameter-level detail, so baseline 3 applies.

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

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

States a specific action (produce a secure checkout link for the current teas.co.uk basket) and the exact resource it operates on. It explicitly distinguishes itself from the sibling checkout_session, so an agent can route without opening either schema.

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

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

Gives an explicit trigger condition ('when the customer is ready to buy what is in their basket') and names the alternative with its own condition ('to buy specific products without using the basket, use checkout_session instead'). Both the when and the when-not 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?

Goes well beyond the annotations: it discloses that a fresh basket is created, that live teas.co.uk prices are used, that the earlier basket is ignored, that a secure payment link is returned, and crucially that nothing is charged and no order is placed until payment. Annotations only say it is a non-read-only, non-idempotent, non-destructive write, so this description carries meaningful extra behavioral 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?

Four sentences, front-loaded with the usage trigger, then behavior, then the sibling exclusion. The repeated 'on teas.co.uk' is deliberate scoping emphasis rather than filler; no sentence 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 single-parameter, nested-schema tool with an output schema present, the description covers the trigger, the effects, the money/safety semantics, and the routing to a sibling. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds a small amount of value by naming the item source ('product id (from find_products)'), the items-per-order bound (up to 20), and the fact that display fields are not used. It stops short of explaining the nested structure or the checkout_session wrapper, but the schema already documents those.

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 (put these items in a fresh basket and return a payment link) and explicitly separates itself from checkout_link for the pre-built basket case. An agent can distinguish it from add_to_basket and checkout_link 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 ('when the customer has picked specific products and wants to buy them straight away, for example from a product result') and an explicit alternative with its selecting condition ('To check out the basket they have already built, use checkout_link instead'). Both when-to-use and when-not are covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description's "Read only" largely restates that. What it does add beyond the structured data is the output shape (side-by-side single table) and the input-provenance rule that ids must come from find_products, which is genuine behavioral context 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 the trigger and sized well for the tool's complexity; every clause about ids, alternatives, and output carries information. Minor redundancy in the standalone "Read only" fragment, which duplicates the annotation, keeps it from a 5.

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 here. For a one-parameter read tool with full annotation coverage, the description supplies everything an agent needs: trigger condition, id provenance, cardinality limits, and sibling alternatives.

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 ids parameter is documented there, so the baseline is 3. The description adds real meaning on top: where the ids come from and the workflow "search for each product first if you only have names," which the schema does not 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?

Specific verb (compare) plus resource (two to four teas.co.uk products), with concrete comparison dimensions named (strength, caffeine, price per cup, pack size, brewing). It also distinguishes itself from the two nearest siblings by name, so an agent can route without opening any schema.

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

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

Explicit trigger ("whenever someone wants to compare two to four products") plus explicit alternatives: find_products to obtain ids, get_product "for everything about one product." The when-to-use and when-not-to-use are both 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely new context beyond them: it is 'policy information only' and 'does not look at any order', which tells the agent not to expect order-specific data. It stops short of describing the response shape, though 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 tight sentences: the trigger and topic list first, then the behavioral constraint, then the sibling routing. No filler, and the most decision-relevant content is front-loaded.

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

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

For a zero-parameter, read-only policy tool with an output schema and rich annotations, nothing an agent needs is missing. Scope, safety, and alternative tools are all accounted for.

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 and the baseline is 4. The schema is trivially complete with additionalProperties=false.

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 (teas.co.uk delivery and returns policy) and enumerates the exact question types it answers: prices, free delivery, dispatch times, destination countries, returns and refunds. An agent can distinguish this from every sibling 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?

It states the triggering condition ('when someone asks about...') and explicitly routes to the correct alternatives: start_return for requesting a return on an order and track_order for locating an order. When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare readOnlyHint/idempotentHint, and the description adds genuinely non-obvious behavior beyond them: the softer filters are relaxed when nothing matches and the result flags this in a note, plus the returned fields (live prices incl. VAT, stock, price per cup, links). The read-only sentence largely restates the annotation, so it falls just short of a 5.

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

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

Front-loads purpose and source, then return contents, safety, the fallback behavior, and finally routing and the exclusion. Every sentence carries distinct information with no filler.

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

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

For a 16-parameter filtered search with full schema coverage and an output schema, nothing an agent needs to call it correctly is missing: routing, safety, result shape and the filter-relaxation caveat are all 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?

Schema coverage is 100% with 16 well-documented parameters and six enums, so the schema does the heavy lifting. The description only gestures at 'words and filters' and adds no filter syntax, defaults or interaction semantics beyond what the schema already states.

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

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

States a specific verb (find/browse/choose) and resource (drinks to buy from teas.co.uk) with scope (live catalogue, UK shop) and explicitly differentiates from siblings get_product, compare_products and add_to_basket. An agent can route without opening any schema.

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

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

Names the alternatives and their selecting conditions (details, comparison, purchase), and adds an explicit negative case: 'Do not use it for general tea knowledge that does not involve choosing a product.' Both when-to-use and when-not are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the description's "Read only" line is redundant with structured data. It does add a genuine result-scope constraint (no alcohol-based drinks) and the product_id linking behavior, but the return format and pagination are not addressed; a 3 is appropriate given annotations carry the safety profile.

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: purpose first, scope exclusion second, parameter/alternative routing last. No filler and the most decision-relevant information is front-loaded.

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

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

An output schema exists, so return-value details are unnecessary here. For a read-only search tool with three fully documented optional parameters, the description covers purpose, scope limits, and sibling routing adequately.

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

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

Schema description coverage is 100%, so all three parameters (limit, query, product_id) are already documented in the schema. The description only restates the optional product_id linkage to find_products and adds nothing about limit or query, so it meets the baseline rather than exceeding it.

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

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

States a specific verb (find) and resource (drink and food recipes) with the source library and concrete examples (iced teas, lattes, chai, baking with tea). It also defines the content boundary (no alcohol) and distinguishes itself from find_products by naming that sibling.

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

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

Explicit about when to use it (finding recipes), one explicit exclusion (alcohol drinks are not included), and an explicit alternative routing (to find products to buy, use find_products). The optional product_id usage path is also spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered; the description reinforces 'Read only' without contradicting it. It adds behavioral context beyond the hints: the mandatory provenance of the id, the search-first workflow when only a name exists, and the rich field set returned.

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

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

Front-loaded with the trigger condition, then the id requirement, then the disambiguation to compare_products. It is a single dense sentence plus two short ones; the long enumeration of return fields is somewhat redundant given a full output schema exists, which keeps it from a perfect score.

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 one required parameter, an output schema, and full annotation coverage, the description supplies everything an agent needs: how to obtain the id, what triggers the call, and which sibling handles comparison. Nothing material is missing.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'Product id from find_products, or a teas.co.uk product link.' The description restates the same id-source rule and adds no syntax or format detail the schema lacks, so the baseline 3 applies.

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

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

States a specific verb and resource ('get product details') and enumerates exactly what is returned: summary, taste, brewing guide, caffeine, price per cup, allergy note, recipes. It explicitly names what it is not (search with find_products; use compare_products for side-by-side), so an agent can route correctly 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 explicit trigger conditions ('whenever someone asks how to brew... caffeine, taste, ingredients or allergy advice'), states the required input origin (an id from find_products or a link), and prescribes the fallback when only a name is known. It also names the sibling to use for comparison, so when-not is covered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description still adds meaningful context beyond that: the account id is opaque and stable across sign-ins, and it returns a display name and email suitable for showing to a customer — plus the linked-account prerequisite, which is a real failure mode.

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

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

Three short sentences, each carrying distinct information: usage trigger, safety/prerequisite, and return contents. The usage trigger is front-loaded and there is no filler.

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

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

With zero parameters, an output schema present, and full annotation coverage, the description supplies everything an agent needs: when to call it, that it is a safe read, the prerequisite, and the shape of the returned identity. 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly does not waste words inventing parameter semantics, and schema coverage is 100%.

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 — 'confirm which teas.co.uk account is linked' — and immediately differentiates itself from sibling account tools (my_orders, my_subscriptions, rewards_balance) by positioning itself as the prerequisite check. An agent can distinguish it from every other tool in the list 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 a concrete when-to-use condition ('before account tools such as my_orders, my_subscriptions or rewards_balance') and a prerequisite ('Needs a linked teas.co.uk account'). It stops short of stating when not to call it or what happens on failure, but the sequencing guidance is explicit and actionable.

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 'Read only' is largely redundant. However, the description adds the authentication prerequisite ('signed in customer') and the returned field set, which the annotations do not cover. No rate limits or ordering guarantees are mentioned, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with the trigger condition and followed by routing. Every clause earns its place with no repetition or 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 zero-required-param read tool with full annotations and an output schema, the description supplies everything an agent needs: when to call it, the auth precondition, and where to go for tracking or reordering. Return values are covered by the output schema, so they need no elaboration.

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 'limit' parameter already documents its default and bounds, so the description adds nothing about it. Baseline 3 applies when the schema carries the parameter 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+resource ('recent teas.co.uk orders') with a named caller context, and explicitly distinguishes itself from track_order and reorder. An agent can pick this over its 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 the triggering condition ('a signed in customer asks about their recent orders') and routes two adjacent needs to the correct alternatives with the condition that selects each. 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 already declare readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered; the description reinforces it with 'Read only' and adds the useful auth precondition (signed-in customer). It also scopes what information is surfaced. It does not mention pagination or limits, but for a zero-arg read this is minor.

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

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

Two sentences, no waste, front-loaded with the trigger condition and followed immediately by the routing alternative. Every clause earns its place.

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

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

With an output schema present, the description need not document return values, yet it still previews the shape of the data for routing purposes. Auth requirement, scope and the sibling escape hatch are all present, so 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?

Zero parameters, so the schema carries no semantic burden and the description needs to add nothing; the baseline is 4. The description correctly focuses on the returned subscription attributes rather than inventing parameter syntax.

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 ('asks about their teas.co.uk tea subscriptions (repeat deliveries)') and enumerates the content returned: what each sends, how often, next delivery, active/paused status. This clearly separates it from the sibling change_subscription without needing to open any schema.

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

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

Explicitly names the triggering condition ('when a signed in customer asks about their subscriptions') and the exclusion plus alternative ('To pause, resume or cancel one use change_subscription'). Both the when and the when-not are stated.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so mutation and repeatability are partially covered. The description adds real value beyond them: it warns that calling again adds items again, that nothing is bought or charged until payment on teas.co.uk, and that items are priced at today's prices.

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, each earning its place: the trigger condition first, then behavior, then the alternative tool. No filler 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?

Covers the auth prerequisite, the mutation and repeat-call behavior, and the deferred payment model; an output schema exists so return values need not be described. 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?

Schema coverage is 100%, so the baseline is 3. The description nonetheless explains only_ids semantically ('that order's products, or only the ones named'), which is more useful than the schema's bare 'only these product ids from that order.'

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: adds products from an earlier teas.co.uk order into the customer's basket. It clearly separates itself from add_to_basket (single-item adds) and my_orders (order history lookup) without the agent needing to open either schema.

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

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

Explicitly scopes usage to a signed-in customer re-buying from a prior order, and names the alternative: 'To see earlier orders first use my_orders.' The only_ids variant is also described as a usage option, 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful context beyond that: it states the caller must be signed in and that redemption happens at checkout rather than via this tool, which prevents misuse.

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

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

Two short sentences, front-loaded with the usage trigger and followed by the read-only scope caveat. No filler and every clause carries information an agent needs.

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

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

With an output schema present, return values need not be described, and with zero parameters there are no input details to document. The description covers the trigger, the authentication precondition, and the scope limitation, leaving nothing essential for a correct invocation.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline for zero-parameter tools applies. Schema and annotations fully cover the (empty) input contract.

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 resource (teas.co.uk reward points) and the exact questions it answers (how many points and what they are worth). This is clearly distinguishable from siblings like view_basket, my_orders, or checkout_link, which deal with different resources.

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: use when a signed-in customer asks about their points balance or value. It also implies a when-not by clarifying that points are spent at checkout, not through this tool. It does not name sibling alternatives, but the triggering context 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 declare the write/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), and the description adds genuinely useful context beyond them: the request goes to a human team 'for review' and 'does not refund or change anything by itself', plus the signed-in auth requirement. It does not explain what happens after review or how duplicate submissions are handled (relevant given idempotentHint), which keeps this from a 5.

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

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

Three sentences, no filler, with the eligibility constraint front-loaded before the side-effect disclaimer and the sibling pointer. Every sentence carries distinct information.

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

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

For a mutation tool with an output schema and full annotation coverage, the description supplies the missing human-facing context: eligibility, prerequisite confirmation with the customer, that the outcome is a reviewed request rather than an instant refund, and where to send policy questions. Nothing an agent needs before invoking it is absent.

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%: order_number, reason enum, items and details are all documented in the schema, including cross-references (find_products, my_orders). The description only reinforces the review step ('Check the order, items and reason with the customer first') and adds no format or syntax detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('sends a return request to the teas.co.uk team for review') and immediately differentiates itself from the similarly-named sibling delivery_and_returns. An agent can tell what this tool does and what it does not do 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 gating condition ('only when a signed in customer clearly asks to return items from a teas.co.uk order'), a pre-call checklist ('Check the order, items and reason with the customer first'), and a named alternative for the adjacent need ('For the returns policy itself use delivery_and_returns'). When-to-use, preconditions and routing 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint and openWorldHint, so the safety profile is covered; the description's 'Read only' is largely redundant. It does add genuinely useful context beyond the annotations by stating the auth prerequisite ('signed in customer') and describing the returned payload (status, items, courier tracking links).

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

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

Three short sentences, front-loaded with the triggering scenario, then the return value, then the sibling redirect. No filler or restated boilerplate.

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, the description covers the trigger, the auth prerequisite, the sibling boundary, and a brief sense of the result. 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?

There is a single parameter at 100% schema description coverage, with an example value ('123456') already documented in the schema. The description adds no format, sourcing, or edge-case guidance about order_number, so the schema does all the work — the expected 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 states a specific verb and resource ('track... where their teas.co.uk order is') and enumerates what comes back (status, items, courier tracking numbers and links). It also explicitly distinguishes itself from the sibling 'my_orders', so an agent can route between the two without opening either schema.

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

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

It gives a concrete triggering condition ('when a signed in customer asks where their order is') and names the alternative plus the condition that selects it ('For a list of recent orders use my_orders'). Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare destructiveHint=true and non-readOnly, but the description adds the concrete destructive condition ('a quantity of 0 removes it') and reassures that 'Nothing is bought or charged'. That materially clarifies the mutation semantics beyond the annotation flags; only idempotency is left to the 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?

Three sentences, each load-bearing: purpose and removal semantics first, then the return/charging reassurance, then sibling routing. 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?

An output schema exists, so the brief return mention suffices, and the description still previews the updated basket with subtotal and delivery estimate. Combined with full schema coverage and destructive annotations, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, including the 0-removes rule and the basket_id host caveat. The description restates the quantity semantics without adding syntax or constraints the schema does not already provide, so baseline 3 applies.

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

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

States a specific verb and resource ('change the quantity of a product... in the teas.co.uk basket') and adds the scope edge case that 0 removes the line. It is immediately distinguishable from add_to_basket and view_basket, which it names directly.

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 add_to_basket to add a new product, view_basket to inspect first. The precondition that the product must already be a line in the basket is stated up front.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: an empty basket returns no lines, and the output includes a live subtotal and delivery estimate. It does not discuss auth or rate limits, but the schema covers the basket_id 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?

The description is front-loaded with the primary purpose, then adds read-only behavior and empty-basket behavior, then routes to the three most relevant sibling tools. Every sentence earns its place and there is no wasted text.

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 the description need not explain return values. With rich annotations, full schema description coverage, and explicit sibling routing, the definition contains everything an agent needs to 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 the single parameter basket_id is fully documented in the schema, including when to omit it. The description does not add parameter-level meaning beyond that, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('show what is in') and resource ('customer's teas.co.uk basket'), plus what is returned: live subtotal and delivery estimate. It also names sibling tools for adjacent actions, so an agent can distinguish it from add_to_basket, update_basket, and checkout_link without inspecting their 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?

It explicitly tells the agent when to use this tool and provides direct alternatives for adding products, changing quantities, and paying. The routing guidance is complete enough that an agent can select the correct sibling without inference.

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