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

Annotations cover the safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds genuinely new behavior: re-adding the same print/product/size grows the existing line up to 99, an unfinished print yields 'print is not ready' and adds nothing, and the tool returns the updated cart. These are non-obvious semantics an agent could not 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?

The precondition and the sibling exclusion are front-loaded, and every subsequent sentence adds a distinct fact (default product, size error, duplicate-line behavior, readiness failure, downstream chain). Dense but zero filler.

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

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

For a 4-parameter mutation tool with an output schema present, the description covers preconditions, failure modes, duplicate handling, and the follow-on workflow. Nothing an agent needs in order to call it correctly and interpret the result 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 value: the product default and its origin in get_studio_options, and the fact that an invalid size produces an error listing valid sizes. Qty semantics are conveyed indirectly via the line-growth/99 cap rather than stated as a parameter, which keeps it 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?

The description opens with a specific verb and resource ('Put a finished custom print ... into the cart as a garment') and immediately names the boundary against its closest sibling ('for catalog designs use add_to_cart instead'). An agent can distinguish this from add_to_cart and generate_custom_print without opening any schema.

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

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

It states the exact precondition ('once get_studio_status reports done and the human has chosen product and size') and explicitly routes the alternative case to add_to_cart. It also names where the product value comes from (get_studio_options) and gives the downstream workflow chain (set_shipping_address → get_order_preview → prepare_order).

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 declare readOnly=false, idempotent=false, destructive=false; the description adds real behavioral detail beyond that: merge semantics (same product/size/fabric grows the existing line, capped at 99), default resolution from saved prefs, and failure behavior (unknown good_id or unavailable size errors with the available sizes list and leaves the cart unchanged). This is exactly the context annotations can't carry.

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

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

Front-loaded with the core action and return, then sources for each field, then the merge rule, then error behavior, then exclusions. Dense but every sentence carries actionable information with no filler.

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

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

Output schema and annotations cover return shape and safety; the description fills in the remaining operational gaps (default resolution, merge/cap behavior, error outcomes, sibling routing). 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 baseline is 3. The description adds meaning the schema lacks: size omitted resolves to the shopper's saved default from get_user_prefs, and fabric omitted takes the first option offered in the chosen size, plus the qty merge/cap interaction.

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

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

States a specific verb and resource ('add a catalog product to the user's cart') plus the return effect ('return the updated cart'). It explicitly distinguishes itself from add_custom_to_cart and update_cart_item, so the agent can route correctly 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 prerequisites for each value (good_id from search_products/get_product, size from get_product's sizes) and names the two alternatives by the condition that selects them: add_custom_to_cart for AI-generated prints, update_cart_item for changing an existing line.

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 a non-read-only, idempotent, non-destructive closed-world operation. The description adds substantial behavioral context beyond that: applied=true/false outcomes, new totals, rejection reasons including bundle pricing conflicts, case-insensitivity, one-code-per-cart replacement semantics, and re-validation in later steps. There is no contradiction with 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?

The description is front-loaded with the primary action and return behavior, and every sentence provides useful operational context. It is dense with semicolon-separated clauses, but the density is justified by the number of behaviors an agent needs to know for correct use.

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 and the description need not explain return values, it still covers the meaningful result states and failure reasons. It also includes preconditions, replacement behavior, alternatives, and downstream re-validation, making the definition complete for 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?

Schema description coverage is 100%, and the single parameter is already documented as the promo code exactly as provided by the human, case-insensitive. The description reinforces that the code must come from the human and should not be guessed, but it does not add new syntax or format details 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?

The description gives a specific verb and resource: validate a promo code and attach it to the cart. It also distinguishes the tool from remove_promo and clarifies that the code is re-checked later in get_order_preview and prepare_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?

It states the precondition (at least one item in the cart), the source constraint (only codes the human gave, never guess), and the alternative for removal (remove_promo). It also explains when a code will be rejected versus when a valid code replaces the existing one.

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 non-readonly/openWorld/non-idempotent; the description goes far beyond by disclosing the credit cost model, how credits are earned (20 on signup, 20 per tee), the requirement to report balance and get a yes, and the free preserve=true exception. It also gives expected duration and the async follow-up (poll get_studio_status). No contradiction with 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 the two highest-stakes facts (cost and consent) before mechanics, and the args block is scannable. It is long, and the inline enum lists are verbose, but nearly every sentence carries decision-relevant content, 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?

For a costly, slow, non-idempotent generation tool, the description covers prerequisites, consent, cost, duration, parameter choices, and the return/polling loop (print_id -> get_studio_status). With an output schema present, 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?

Although schema coverage is 100%, the schema provides no enum values (0 enums) yet the description enumerates all product, background, and placement values, states the model trade-off (both 1 credit, different styles), and clarifies the image_url/preserve dependency. This is meaningful information the schema does not carry.

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 — 'Generate a CUSTOM t-shirt print from a text prompt' — and immediately flags the AI engine and 2-10 min latency. It is clearly distinct from siblings like add_custom_to_cart or get_studio_options, which are referenced as downstream/preparatory steps rather than competitors.

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 prerequisite sequence ('first call get_studio_options and ask the human to pick placement + product... do NOT silently use defaults') plus a mandatory consent gate before spending credits. It also names the alternative path (preserve=true, free) and when that applies — kids' drawings, own art.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is structured data. The description still earns credit for non-obvious behavior: prices come from the live catalog rather than the cart, promo and bundle discounts don't stack, ready_to_prepare stays false on missing address or unavailable lines, and an empty cart errors out. Those additions are real value beyond the annotations, though return shape and pagination are left to the output schema.

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

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

The core 'what you get' is front-loaded, then invocation timing, then failure conditions — a sensible order. Nearly every clause carries distinct information (non-stacking discounts, catalog pricing, gate flag, empty-cart error), but it is a dense run-on paragraph that could be broken into shorter units for scanability.

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

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

An output schema exists, so return values need not be enumerated, yet the description still highlights the fields that matter for the agent's decision (total currency, ready_to_prepare). Both the happy path and the two blocking conditions plus the error case are covered, so the 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 baseline is 4; there is nothing for the schema to document. The description goes slightly beyond by explaining that the grand total is expressed in the order currency, which can be destination-local (e.g. UZS for Uzbekistan).

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?

Starts with a specific verb+resource ('Show the full order before checkout') and enumerates exactly what the preview contains: re-priced lines, discount resolution, shipping, address, grand total. It is clearly distinguishable from siblings view_cart (raw cart) and prepare_order (the committing 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?

Explicit sequencing: call once the address is set, show the human, then prepare_order. It also names remedies for the blocked state (update_cart_item, set_shipping_address) rather than leaving the agent to guess. Usage boundaries relative to siblings are fully specified.

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

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

Beyond the annotations it discloses read-only intent in user terms ('can't cancel or change an order'), default ordering (newest first), the limit default of 5 and max of 20, the enumerated status lifecycle, and the edge case of an account with no email returning an empty list with a note. That is substantive behavior an agent can't derive from readOnlyHint/idempotentHint alone.

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 key routing information (what it does, the alternative, read-only) is front-loaded and every sentence carries content. The opening sentence is long and comma-heavy, costing some skimmability, but nothing is 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 values needn't be explained in depth, but the description still names the core fields and covers status lifecycle, empty-result behavior, and scoping to the signed-in account. Complete for a two-parameter read tool.

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

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

Schema coverage is 100%, so both parameters are already documented. The description restates the number format and limit default/max and adds that omitting number returns newest-first, which is already in the schema's own wording — marginal added value.

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

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

States a specific verb (look up) and resource (orders for the signed-in account), plus what it returns (status, total, tracking url). It explicitly contrasts with get_order_preview, so an agent can distinguish it from the nearest sibling without reading 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 phrase ('where is my order') and names the alternative (get_order_preview) with the condition that selects it ('for an order not placed yet'). 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 annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description correctly reinforces 'Read-only' without needing to restate safety. It adds meaningful behavior beyond the annotations by disclosing the unknown-code failure mode ('product not found') and by noting that the result returns the numeric good_id needed for add_to_cart.

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 what the tool returns, followed by when to use it and how the code maps to other tools. Every sentence carries actionable information 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 single-parameter read tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what is returned, when to call it, where the code comes from, how the result feeds add_to_cart, and the error case. Little 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 meaning: the code is the `code` field of a search_products card and specifically the end of its /p/<code> URL. It also clarifies the distinction from the numeric good_id consumed by add_to_cart, which the schema alone does not explain.

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, then enumerates exactly what the result contains: sizes, fabrics, per-variant prices, and the design's 'about' text. It is clearly distinguishable from search_products, which returns only cards, and from add_to_cart, which is the downstream action.

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

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

Explicitly says to call it before add_to_cart when the human hasn't picked a size yet or may want another fabric, and explains why a search card is insufficient. It also names search_products as the source of the code and explains how add_to_cart uses the returned good_id.

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 beyond that: the hard cap of 5, deduplication, newest-first ordering, the empty-list meaning, and the explicit warning that it selects nothing. It does not cover auth/permission nuances, but nothing suggests those are in play.

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 what is returned and in what order, followed by usage and the failure case. Every sentence carries information; nothing is redundant with 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, so return-shape details are unnecessary, yet the description still supplies the ordering and cap that shape agent expectations. For a zero-param read tool with strong annotations, nothing an agent needs before calling 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, so there is nothing to mis-specify, and the baseline is 4. The description adds useful semantics by explaining that matching happens implicitly via the account email, which tells the agent no identifier argument is needed.

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 plus precise scope: up to 5 distinct shipping addresses from past orders, matched by account email, newest first. This clearly separates it from get_shipping_options (available methods) and set_shipping_address (the write 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?

Gives an explicit when: for a returning buyer, call before asking for an address. It also names the downstream step (pass the pick to set_shipping_address) and the when-not/alternative path for an empty list (ask the human).

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 real value beyond the annotations: results are cart-scoped, prices are USD for the cart as-is, the final destination-currency amount lives in get_order_preview, and the call is safe on an empty cart. It stops short of clarifying whether results shift after set_shipping_address, despite set_shipping_address and set_shipping_method being siblings — a meaningful gap for a shipping-quote 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 purpose, then usage conditions, then the sibling hand-off — good ordering with no filler. The embedded snapshot of the single current method ("worldwide tracked shipping, 7–14 business days") is illustrative but will go stale and is the one sentence that does not earn unconditional space.

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

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

An output schema exists, so return-shape explanation is unnecessary and the description rightly focuses on semantics instead: currency, cart scope, empty-cart behavior, and where the billed amount appears. Only the address-dependency question is left unaddressed for a tool sitting next to set_shipping_address.

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 the baseline is 4. The description correctly implies the cart context is implicit rather than passed in.

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 ("List the shipping methods for the current cart") along with the exact data returned: price, ETA, free-shipping threshold. It is clearly distinguished from get_order_preview, which the description names as the source of the authoritative converted amount.

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 user questions this answers ("how much / how long is shipping", "how much more gets free shipping") and routes the agent elsewhere for the final charged amount (get_order_preview). It also states a boundary condition — works on an empty cart — that would otherwise cause an agent to skip the call.

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

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

Beyond the annotations, the description discloses that reading spends nothing, that a missing Studio account returns balance 0 with studio_account=false, that first generation creates the account with 20 welcome credits, and how credits accrue from tee purchases. These are rich behavioral details not inferable from the annotations alone.

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 core balance-check purpose and the fact that reading is free. It remains efficient overall, though the final sentence about buying more credits at allover.art/studio is slightly more promotional than strictly necessary for invoking the 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?

An output schema exists, so return values need not be explained in detail. The annotations cover the safety profile, and the description adds the key account-state and cost context an agent needs to call the 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?

This tool has zero parameters, so there are no parameter semantics to document. The baseline score for a zero-parameter tool is 4, and there is nothing in the description that needs to compensate for an input-schema gap.

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

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

The description states a specific verb and resource: return the account owner's Studio credit balance. It also clearly distinguishes this read-only balance check from the generation action it supports, so an agent can identify the tool's job immediately.

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 says to check this before generate_custom_print so the human can be told the cost and remaining balance. It also explains the no-account case and the free preserve=true case, giving clear conditions for when and how to use the 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 already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds behavior not in the annotations: output must be surfaced to a human and a choice collected before proceeding — a workflow constraint an agent would otherwise miss. It stops short of describing the return shape, but an output schema exists to cover that.

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

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

Two sentences, front-loaded with the highest-value token ('START HERE'), then the content inventory, then the required next action. Every clause carries operational information; nothing is padding.

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

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

Zero params, full annotation coverage, and an output schema that carries the return structure — so the description only needs routing and workflow guidance, which it delivers. 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 there is no parameter semantics to explain; baseline 4 applies. The description correctly implies no inputs are needed before fetching the menu.

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

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

States a specific resource (the menu of generation choices) and enumerates its contents — placements, products, backgrounds, engines+costs — plus its role as the entry point. The contrast with generate_custom_print makes it distinguishable from the sibling that actually produces the print.

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 'START HERE' trigger, an explicit next step (present to the human, ask at minimum for PLACEMENT and PRODUCT), and an explicit named successor tool (generate_custom_print). Nothing about when to call this versus alternatives 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 cover safety (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: expected generation duration (2–10 min), the one-generation-per-account constraint, automatic credit refund on failure, and the fact that polling is free. This is exactly the kind of operational context annotations can't 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 core action and status semantics, and every sentence carries real value (cadence, constraint, return handling, refund behavior). It is dense and somewhat run-on — a couple of clauses could be split for scannability — so not quite 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?

Given a single required param, full annotation coverage, and an output schema, the description still goes beyond necessity by explaining preview_url vs design_url handling and the failed-state refund. Nothing an agent needs to poll correctly or act on the result 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?

Only one parameter, and the schema documents it at 100% coverage including that the same id goes to add_custom_to_cart. The description reinforces the print_id linkage but adds no syntax, format, or lookup semantics beyond the schema, so the baseline 3 for full coverage 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?

States a specific verb and resource ('Poll a custom print started by generate_custom_print') and explicitly ties itself to the sibling that creates the resource. An agent immediately understands it is the check-status counterpart to generation.

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

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

Explicit when-to-use and next-step guidance: poll roughly every 30s, don't start another generation while one is running (account runs one at a time), and once done offer add_custom_to_cart with the same print_id. Terminal vs non-terminal statuses are enumerated, so no inference is required.

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 this as a safe read-only, idempotent lookup, and the description adds meaningful behavioral context beyond that. It discloses how the saved preference is applied automatically, how add_to_cart uses it when size is omitted, and how fit affects product search 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?

The description is compact and front-loads the core action and the key instruction to call it before asking for size. The second sentence is dense and combines automatic application, add_to_cart behavior, and search style mappings, but every element is useful and there is little waste.

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

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

Given a zero-parameter read-only tool with rich annotations and an output schema, the description provides everything needed to call it correctly. It covers purpose, timing, fallback behavior when a default exists, and how the result feeds into sibling tools.

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

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

The tool has zero input parameters, so there is no parameter semantics to explain in the description. A baseline of 4 is appropriate because the schema requires no compensation and the description correctly avoids inventing parameter details.

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: return the shopper's saved default size and fit. It clearly distinguishes this read-only preference lookup from related mutation tools such as set_user_prefs through the get/set naming and saved-data framing.

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

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

It gives explicit timing: call this before asking the user for a size, and apply the default automatically if one exists. It also names concrete downstream alternatives, explaining how add_to_cart can consume the saved size and how search_products should use the saved fit with specific style values.

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 safety is covered; the description nonetheless adds the ordering guarantee ("trending first") and the fact that only "active" collections appear, which the annotations do not convey. The trailing "Read-only" largely restates the annotation rather than adding new behavior, and pagination/truncation behavior beyond the cap is not described.

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

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

Four compact sentences, front-loaded with the resource definition, then intended use, then the exclusion routing, then the parameter note. No padding; even the short tail sentences carry routing or constraint 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?

Output schema exists so return values need not be explained, yet the description still names the key fields. With one optional parameter fully documented and annotations covering safety, 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 description coverage is 100% and the single `limit` parameter is already documented as "default 50, max 100" in the schema; the description repeats that verbatim without adding format or semantics beyond it. With the schema doing the work, this sits at 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 and resource ("List active curated collections") and immediately defines what a collection is ("themed landing pages on allover.art") plus the ordering ("trending first") and returned fields (title, slug, url). An agent can distinguish this from search_products or get_product 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 ("when the human wants ideas or a themed page to browse; send them the url") and an explicit negative case naming the alternative tool ("Collections are not a search filter: to find products in a theme, call search_products with theme or query"). Both when-to-use and when-not-to-use are covered with the sibling named.

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

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

Goes well beyond the annotations: each call creates a new non-idempotent draft, the cart is not emptied, drafts expire in 48 hours, prices are re-checked, and empty cart / missing address / no orderable items produce an error with issues and create nothing. The new-draft-each-call note reinforces the non-idempotent hint rather than contradicting it.

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

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

Front-loaded with the action and return shape, then the human-handoff, then preconditions, then side effects and failure modes. Every clause carries distinct operational information 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?

Even though an output schema exists, the description still names the key return fields and adds the failure and expiry semantics an agent needs. For a zero-parameter, state-driven checkout step, 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?

Zero parameters, so there is nothing for the schema to document; the description compensates by explaining that the inputs come from cart, address and promo state already established by sibling tools. It stops short of naming which setters feed it, but no parameter-level guidance is needed.

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

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

Opens with a specific verb and resource ("Turn the cart, address and promo into a draft order") and immediately enumerates the returned fields. It is clearly distinguished from get_order_preview, which it names as the prior step rather than an alternative.

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 sequencing: "Call it only after showing get_order_preview and getting the human's OK" gives both the prerequisite and the alternative. It also states the correct call frequency ("once per purchase") and that the human, not the agent, completes payment.

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 past the annotations: it explains the resulting pricing state, the bundle-price exception, repeat-call behavior on an empty cart or no applied code, and the applied=false return signal. Annotation idempotentHint=true is corroborated rather than merely restated, and the no-op specifics add real 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?

Three short sentences, front-loaded with the action and its price effect, then usage, then edge-case safety. Every clause carries information an agent would otherwise have to guess.

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 no-parameter idempotent cart mutation with an output schema available, the description covers effect, routing, and no-op behavior. Nothing needed to invoke it correctly is absent, and return-format detail is left to the output schema.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. Nothing is missing, but no extra semantic value is possible here.

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 ('Drop the promo code from the cart') plus the effect on totals ('totals go back to full price'), with a useful caveat that a bundle price still applies. It is clearly distinguishable from apply_promo, 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?

States when to use it ('when the human no longer wants the code') and when it is unnecessary ('isn't needed before apply_promo, which replaces the code anyway'), naming the sibling that covers the alternative case. An agent can route between remove_promo and apply_promo with no 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 establish this as a read-only, idempotent, non-destructive search, but the description adds meaningful behavior beyond them: relevance ranking with a query versus best-sellers without, no paging, top-limit behavior with default 24 and max 48, adult-design exclusion, and error behavior for unknown colors or styles. These details materially help an agent predict results and failure modes.

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 dense but front-loaded: purpose and return shape come first, followed by sibling differentiation, filter behavior, ranking, paging constraints, and error handling. Every sentence carries operational information, and there is no redundant restatement of structured fields.

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

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

For a 7-parameter search tool with an output schema and rich annotations, the description covers what an agent needs: return fields, ranking logic, limit behavior, filter combination, style selection from user preferences, and error cases. It is complete enough to invoke correctly without additional documentation.

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 useful semantics: query is free text with examples, theme is canonical and comma-separatable, style should be derived from the shopper's saved fit, and max_price is USD. It also clarifies that limit caps results at 48 and that narrowing filters is the only way to reach additional matches. Color semantics are left mostly to the schema, which keeps it from a full 5.

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

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

The description states a specific verb and resource ('Search the allover.art catalog') and clarifies the return shape: one card per design with good_id, code, price, and url plus total match count. It explicitly distinguishes this tool from list_collections and get_product, so an agent can select it 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 explicit usage conditions ('find me a …' requests) and names alternatives: list_collections for curated themed pages and get_product for a single card's sizes/fabrics. It also explains how filters combine, how to choose style based on get_user_prefs, and how to work around the lack of paging by narrowing filters.

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 annotations, the description discloses phone normalization to international form, a warning result when normalization fails, that only required fields and phone are checked while the street is not verified, and that country can switch the order to local currency. These are meaningful behavioral details for a mutating checkout 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?

The description is dense but front-loaded: purpose and consumers first, then prerequisites, alternatives, validation behavior, and side effects. Every sentence carries operational meaning with no filler.

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

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

Given the mutation, prerequisites, validation rules, warning behavior, currency side effect, and output schema presence, the description is complete enough for an agent to call this tool correctly. Annotations cover safety and idempotency, and the description covers what they do not.

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 already 100%, so the baseline is 3. The description still adds semantic value beyond the schema by explaining phone normalization and country-code fallback, country-driven currency switching, and the fact that street text is not verified.

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: setting the delivery address for the current cart's checkout. It also names downstream tools (get_order_preview, prepare_order) that consume the address, clearly distinguishing it from siblings like get_saved_addresses or set_shipping_method.

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

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

It gives explicit when-to-use guidance, including the prerequisite of having at least one cart item, the behavior of replacing a prior address, and the recommendation to offer get_saved_addresses first for returning buyers. It also states failure conditions: missing fields or an empty cart return an error and save nothing.

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

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

Beyond the annotations, the description adds meaningful operational context: an unknown option_id returns an error and changes nothing, and at least one item must be in the cart. It does slightly repeat the idempotentHint with 'Repeating it is harmless,' but it still contributes substantial precondition and failure semantics not present in annotations.

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

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

Three tight sentences are front-loaded with purpose, then optionality, then preconditions and error behavior. Every sentence adds practical value for an agent deciding whether to call it.

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 simple one-parameter setter with an output schema, the description covers optionality, preconditions, error handling, and idempotency. Nothing material is missing for 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?

Schema coverage is 100%, so the schema already documents option_id as coming from get_shipping_options and currently being 'worldwide.' The description mostly reinforces this and adds error behavior, which is behavioral rather than parameter syntax or format detail.

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 ('Select the shipping method for the current cart's checkout') and ties the parameter to a named sibling ('get_shipping_options'). This clearly distinguishes it from the sibling that lists shipping options.

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 says the call is optional because only 'worldwide' exists today and is already default, and it names the condition for use: when the human explicitly picks a method or once more methods appear. That is explicit when-to-use guidance with a clear alternative context.

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 mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), yet the description still adds real value: omitted fields retain their saved value, empty strings clear them, and invalid input is atomic ('returns an error and saves nothing'). It also discloses cross-tool propagation (size feeds add_to_cart, fit maps to search_products style). It does not mention account/auth preconditions, which is the only notable gap.

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?

Leads with what gets saved and why, then the call condition, then field semantics, then side effects and error behavior — a natural decision order. Roughly 100 words with no filler; each 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?

An output schema exists, so return values need not be explained. The description covers selection criteria, partial-update semantics, valid values, error behavior, and effects on downstream tools — everything an agent needs 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 the baseline is 3; the description earns above that by adding case-insensitive matching, the omitted-vs-empty-string distinction for partial updates, and the downstream meaning of each field. The accepted value sets largely restate the schema, which keeps it from 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 (save) and resource (the shopper's default size/fit on their account), plus the practical goal (later chats skip asking). It is instantly separable from the sibling get_user_prefs, which it names as the read 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?

Gives an explicit invocation condition — 'only when the human states a size or fit or asks you to remember one' — which also implies when not to call it. It names the alternative (get_user_prefs) for reading and warns that any unlisted value errors out and saves nothing.

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 past the annotations by disclosing that qty=0 deletes the line, the 99 cap, that size/fabric changes re-price the line, that a failed index or unavailable variant is atomic ('changes nothing'), and what is returned. It also warns about index shifting after deletion — a real behavioral trap 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 core action, then semantics, then edge-case behavior, then the sibling routing hint. No filler sentences; every clause carries a fact the 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?

For a 4-parameter mutation with an output schema and full annotation coverage, the description covers sourcing the index, partial updates, destructive semantics, error atomicity, and the follow-up re-read. 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 meaning on top by tying qty=0 to removal, giving the max of 99, and explaining that size/fabric edits trigger re-pricing and must be available for the product. It doesn't add much on the index parameter beyond what the schema already says.

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

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

States a specific verb and resource ('Change one line already in the cart') plus the addressing scheme ('zero-based index from view_cart'). It also explicitly contrasts with add_to_cart, so an agent can distinguish it from the create-path siblings 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/when-not guidance: 'Pass only what changes', 'To add a different product use add_to_cart', and the re-read-view_cart-before-next-edit rule after a removal. The alternative tool is named with the condition that selects it.

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?

Well beyond the readOnlyHint annotation, it discloses that this is the same server-side cart the human sees in the browser (so browser-added items appear), that prices are as-added rather than fresh, and that line indexes shift after removal. These are exactly the behavioral traits that would cause a mis-call if omitted.

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 return shape, then the shared-cart context, then the index guidance, then the pricing alternative. Every sentence carries distinct information with no restatement 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?

For a no-param read with an output schema already documenting return values, the description covers everything an agent needs: what comes back, how it relates to browser state, staleness of prices, and the downstream index contract.

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 and there is nothing for the description to disambiguate. It correctly spends no words on a non-existent schema.

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

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

States a specific verb and resource ('Show the lines in the user's cart') and enumerates the returned fields (qty, size, fabric, subtotal), distinguishing it from get_order_preview which returns payable totals. An agent can tell exactly what this returns without opening the output 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 ('to get the zero-based line index that update_cart_item takes'), a stateful caveat (re-read after removing a line, since later indexes shift), and names the alternative for pricing (get_order_preview). Nothing about selection 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.