Synchronity

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. Description adds context about reusing cart_id and precondition (cart must exist). No contradictions, but behavioral disclosure beyond annotations is minimal.

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?

Description is two sentences, front-loaded with the core action. No fluff; every word 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?

Given the tool's complexity (8 params, nested objects, output schema), the description covers the essential context: action, precondition, and reuse of cart_id. It does not need to detail return values as output schema exists.

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 each parameter is well-documented in the schema. Description adds minimal extra meaning (e.g., reusing cart_id), but the schema already carries the burden.

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

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

Description explicitly states action (add) and resource (product variant/base product to cart). Distinguishes from sibling create_cart by specifying when to use each.

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?

Provides clear guidance to reuse existing cart_id from chat history and to call create_cart only if no cart exists. Lacks explicit exclusion for other alternatives like update_cart or remove_from_cart, but context is sufficient.

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 indicate this tool is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description confirms it modifies the cart and returns the updated cart. However, it does not disclose edge cases (e.g., invalid code) or additional behavioral details beyond what annotations provide.

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

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

The description is two sentences front-loaded with the action. Every word is necessary; no redundancy 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?

Given the tool's simplicity (3 required params, output schema exists), the description adequately states functionality and return value. Slight gap: no mention of cart existence requirement, but schema and context compensate. Overall complete.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds 'discount or promotional code' which aligns with the 'code' parameter. No additional semantic value is provided 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 clearly states the verb 'apply' and the resource 'discount or promotional code to the cart.' It distinguishes from sibling tools like 'add_to_cart' or 'create_cart' by specifying this tool is for discount codes.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., cart must exist) or conditions like code validity. No explicit when-not or alternatives are given.

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

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

Annotations provide readOnlyHint=true and openWorldHint=true. The description adds the polling behavior (repeated calls) and specifies the condition for returning a token. This enriches understanding beyond annotations.

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

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

Two sentences, front-loaded with purpose, no extraneous words. Highly concise and well-structured.

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

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

With an output schema present, the description does not need to detail return values. It covers the workflow and relation to siblings. Could mention polling loop duration or error handling, but overall adequate.

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%, but the description adds value by stating that device_code comes from request_delegation, providing source context.

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

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

The description clearly states the tool is for polling human approval of a delegation request. It specifies the action (poll), the resource (delegation approval), and the outcome (returns delegation_token). This distinguishes it from siblings like request_delegation and execute_checkout.

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

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

The description implies usage after request_delegation and before execute_checkout, and that polling continues until status is 'approved'. However, it does not explicitly exclude other scenarios or mention alternatives like submit_delegation_otp.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds beyond annotations by explaining the fail-open behavior and that partial results are returned on timeouts, which is valuable 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?

Two sentences, front-loaded with the core action, followed by a key behavioral detail. No wasted words.

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

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

Given 6 parameters (2 required) and a cross-site comparison function with fail-open, the description covers the main purpose and a key behavior. An output schema exists, so details on return values are likely covered there. Could mention handling of duplicate products or sorting, but not essential.

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 baseline is 3. The description does not elaborate on parameters beyond what the schema already provides; it adds no extra semantic meaning.

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

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

The description clearly states the purpose: 'Compare products across multiple registered e-commerce sites simultaneously.' It uses a specific verb and resource, and distinguishes itself from sibling tools like search_products (single-site) and get_product (single product).

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

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

The description mentions the fail-open strategy, implying when to use this tool (when tolerance for partial failures is acceptable). However, it does not explicitly exclude scenarios or point to alternatives such as search_products for single-site queries.

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 indicate non-read, non-destructive, open-world. Description adds that it returns a cart_id and emphasizes reuse. No contradictions. Could mention if previous carts are invalidated, but overall adequate.

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 focused sentences plus a critical note. Every sentence serves a purpose, front-loaded with core action and return value.

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 creation tool with two parameters and an output schema, the description fully covers what it does, when to use it, and an important reuse constraint.

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 fully describes both parameters. Description adds no additional parameter meaning beyond the schema.

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

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

Description clearly states 'Create a new shopping cart for a specific site. Returns a cart_id.' The verb and resource are specific, and it distinguishes from sibling tools like get_cart or get_active_cart.

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

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

Explicitly instructs when and when not to use the tool: 'Reuse the active cart_id across multiple products... Do NOT call create_cart again if you already have a cart_id.' This provides clear context and alternatives.

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 indicate destructiveHint=true and readOnlyHint=false. The description adds crucial behavioral details: the order is created UNPAID (status 'pending'), and the payment_url is a manual fallback. It also discloses that the agent must drive the subsequent payment flow, not stop here. This goes beyond annotations, providing complete transparency about side effects and required follow-up actions.

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 efficiently structured: the first sentence states purpose and key effect, the second lists requirements, and the rest is a clear, imperative note about the continuation flow. Every sentence serves a distinct, useful purpose. Despite length, it is front-loaded and easy to parse, with no wasted words.

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

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

Given the tool's complexity (15 params, 12 required), the description covers the essentials: what it does, key requirements, and the critical follow-up steps. An output schema exists, so return values are handled. The description is complete enough for an agent to use the tool correctly, though it could mention error scenarios or prerequisites like a valid, non-empty cart.

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 input schema already documents all parameters with descriptions. The description adds modest context: it mentions that buyer_delegation_token comes from user auth and that a shipping address is required, but does not elaborate on individual parameter formatting or usage beyond what the schema provides. The baseline of 3 is appropriate; the description adds some value but is not essential for understanding parameters.

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

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

The description clearly states the tool's purpose: 'Execute checkout for a cart to create an order.' It specifies the action (checkout), resource (cart), and result (order). The title annotation 'Place order (checkout)' reinforces this. While sibling 'quick_checkout' exists, the description distinguishes by detailing requirements (delegation token, shipping address) and the unpaid state of the order. This provides sufficient clarity for selecting the tool.

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

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

The description explicitly states preconditions: 'Requires a buyer delegation token (from user auth) and a shipping address.' It includes an IMPORTANT block that instructs the agent not to stop after checkout, but instead to continue the in-chat payment flow with specific next steps (get_payment_methods, initiate_payment, etc.). It even explains when to use the manual payment_url fallback. This is exceptionally clear guidance on when and how to use the tool vs. alternatives.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds context about cart rebuilding on expiration and returning null, as well as resuming a conversation, which goes beyond the annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. The structure is efficient and clear.

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 presence of an output schema, the description adequately covers the tool's behavior, including return states and usage context. The term 'resumes a conversation' could be more explicit, but overall complete for a simple retrieval 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% for the single parameter site_id, described simply as 'Registered site ID'. The description does not add further detail about the parameter's meaning or constraints, but the schema is sufficient.

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

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

The description clearly states the tool retrieves the buyer's in-progress cart for a site, with specific context of resuming a conversation. It distinguishes from siblings like create_cart and get_cart by focusing on 'active' carts.

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

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

The description provides explicit guidance: 'Call this before assuming a new cart when a shopping conversation continues or after a cart error.' It implies when to use but does not explicitly mention alternatives when not to use, though siblings are known.

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?

Discloses that the UI already shows cart contents, so the agent should not re-list them. This adds context beyond annotations (readOnlyHint, destructiveHint) and explains expected 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 extremely concise with two sentences, front-loaded with the action and followed by a practical usage instruction. Every sentence earns its place without 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 the presence of an output schema and annotations, the description adequately covers what is retrieved and how to respond. The only missing element is differentiation from 'get_active_cart', but overall it's complete for a read-only tool.

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

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

The input schema has 100% coverage with clear descriptions for both parameters. The description adds no additional meaning beyond what the schema provides, warranting the baseline score.

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

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

The description clearly states the tool retrieves 'current cart contents, including items, pricing, discounts, and totals.' However, it does not differentiate itself from the sibling tool 'get_active_cart', which may have overlapping functionality.

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?

Provides explicit instruction: 'keep your text reply to one brief sentence — do not re-list the cart contents.' This guides the agent on how to present results, though it does not specify when to choose this tool over alternatives.

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

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

The description adds significant behavioral context beyond the annotations. Annotations declare readOnlyHint=true and destructiveHint=false, and the description reinforces this (read-only retrieval). It also discloses the delegation token requirement and nuanced status interpretation, providing transparent guidance on how the tool behaves and should be used.

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 relatively long but each sentence serves a distinct purpose (purpose, constraint, status interpretation, workflow guidance). It is front-loaded with the primary function. While it could be slightly condensed, its comprehensiveness justifies the length for a non-trivial 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?

Given the presence of an output schema (indicating return structure is documented separately), the description covers everything necessary: purpose, parameter semantics, usage guidelines, and behavioral transparency. There are no apparent gaps for an agent to select and invoke 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 coverage is 100%, so the schema already describes all three parameters. However, the description adds valuable context for the buyer_delegation_token, explaining its purpose ('the delegation token from this buyer's checkout approval') and that it is required to read the order. This goes beyond the schema's description and aids correct usage.

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

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

The description clearly states 'Retrieve details for an order by its ID' and lists the included information (items, status, shipping, tracking). While it is specific and unambiguous, it does not explicitly differentiate from the sibling tool 'list_orders', which lists orders rather than retrieving a single one.

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

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

The description provides extensive usage guidance: it explains the need for the buyer_delegation_token, how to interpret order status (pending/unpaid), warns against assuming synchronization delays, and prescribes a concrete workflow for unpaid orders (get_payment_methods → initiate_payment → get_payment_status). It also tells the agent not to mark a task successful until status is 'processing' or 'completed'.

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. Description adds value by explaining it's a read operation in a multi-step flow and describes return structure. No contradiction.

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?

Concise single paragraph with flow step, return description, instructions, and fallback. Slightly dense but efficient.

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 only 2 params, output schema present, description covers purpose, usage, and integration. No gaps for this tool's complexity.

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

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

Schema coverage is 100%, baseline 3. Description adds fallback info: site_id defaults to DEFAULT_SITE_ID if omitted. This extra context justifies a 4.

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

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

The description clearly states it returns payment channels and gateways for an order, and explicitly marks it as STEP 1 of the payment flow, distinguishing it from siblings like initiate_payment.

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?

Provides step-by-step usage: call this first after an order exists, then call initiate_payment with chosen channel. Mentions handling multiple gateways, though no explicit when-not conditions.

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?

Discloses polling behavior and status interpretation beyond annotations (readOnlyHint=true). The description explicitly states 'No delegation needed (read-only),' reinforcing the safe read nature. No contradictory behaviors are present.

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 a single dense paragraph with every sentence adding value. It front-loads the core purpose ('FINAL STEP') and presents polling frequency, conditions, and actions concisely. No wasted words.

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

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

Given the tool's role in a multi-step payment flow and the presence of an output schema, the description covers all necessary context: polling interval, success/failure conditions, user instructions, and safety. It fully addresses the complexity without missing critical details.

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% (both parameters have descriptions). The description does not add new meaning to the parameters beyond the schema; it does not mention site_id at all. Baseline 3 is appropriate as the description focuses on usage flow rather than 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 clearly states the tool is the 'FINAL STEP' of the payment flow and returns the current PaymentSession for an order. It uses specific verbs ('returns', 'poll') and distinguishes it from sibling tools like initiate_payment and submit_payment_otp by positioning it as the polling step to check the outcome.

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?

Provides explicit when-to-use guidance: poll every ~5 seconds after initiate_payment/submit_payment_otp. Defines success conditions ('paid' or 'processing') and failure condition ('failed'), including user messaging. Also specifies not to treat purchase as complete until these statuses are met, and notes no delegation is needed.

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

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

The description discloses that the tool may return `addons` — optional items with `required` flag and `price_modifier`, which goes beyond the annotations (readOnlyHint, destructiveHint) that only indicate read-only and non-destructive behavior. No contradictions 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?

The description is a single paragraph, fairly concise, but combines functional purpose with usage instructions. While efficient, it could be slightly more structured (e.g., separate usage guidelines). Still, no unnecessary verbosity.

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 complexity of the tool (returning addons with important implications for cart flow) and the presence of an output schema (so return values don't need elaboration), the description sufficiently covers all aspects needed for correct usage. It tells the agent exactly what to do with addons, ensuring completeness.

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 schema already has 100% coverage with descriptions for both parameters (site_id and product_id). The description does not add additional parameter-specific semantics; it only mentions them in the context of the product retrieval but no extra details like format or constraints. 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 uses specific verb 'Retrieve detailed information about a specific product' and lists key resources (variants, pricing, images, availability, addons). It clearly distinguishes from sibling tools like search_products (search) and compare_products (comparison) by focusing on a single product's details.

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

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

Provides explicit when-to-use guidance: it tells the agent to present addons to the buyer, collect required addons before calling add_to_cart, and show price modifiers. It also instructs to keep reply brief because the card already shows product details. This directly addresses tool selection and downstream usage.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds value by detailing the return fields (average rating, trust score, authenticity flags) and emphasizes safe usage, which confirms the non-destructive nature.

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 with no wasted words. Front-loaded with the recommendation, followed by concise list of outputs and usage directive. Efficient and to the point.

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 tool with moderate complexity, the description is complete: it specifies when to use, what it returns, and aligns with the output schema. No gaps remain.

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 all parameters described. The description does not add further parameter semantics but stays neutral. Baseline score of 3 is appropriate as no additional meaning is provided.

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

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

The description clearly states the verb 'fetch' and resource 'product reviews and authenticity consensus', and distinguishes from sibling tools by recommending it before purchase decisions.

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

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

Explicitly states 'Always call this for each product before adding to cart', providing clear context for when to use. No explicit alternatives mentioned, but the recommendation 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 indicate destructive and readOnly false. Description elaborates extensively: starts a financial transaction, requires human approval, channel-specific behavior (mobile_money vs card), and detailed response handling. 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?

Efficiently front-loaded with 'STEP 2' and structured with prerequisites, channel specifics, and post-call actions. Every sentence adds value; no redundancy.

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 7 parameters, two channels, delegation flow, and output schema (exists), the description covers all necessary context: how to call, what to expect (instruction with action), and how to proceed. References sibling tools (request_delegation, check_delegation, submit_payment_otp, get_payment_status) to complete the picture.

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%, but description adds significant meaning: exact phone format (055... or +233...), provider alias mapping (telecel→vod, tigo→tgo), and clarifies that phone and provider are required only for mobile_money. Also explains gateway optionality and default behavior.

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?

Clearly states it is step 2 of the payment flow, starts a payment session, and returns a PaymentSession with instruction. Distinct from siblings like get_payment_status or submit_payment_otp by specifying its role in the multi-step process.

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?

Provides explicit prerequisites (buyer_delegation_token) and how to obtain it via request_delegation and check_delegation. Describes post-call actions based on instruction.action. Does not explicitly name alternative tools, but context implies sequencing and when to use other steps.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds that orders are buyer-private and only the token holder's orders are returned, which is valuable behavioral context beyond annotations. However, 'recent' is vague and could be more precise.

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 two sentences, front-loading the action and then providing the key constraint. No unnecessary words, every sentence adds value.

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 presence of output schema and annotations, the description covers input semantics and privacy. It does not mention pagination explicitly (though schema has page/per_page), and 'recent' is vague. Still, it is largely complete for the tool's purpose.

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 descriptions cover 100% of parameters. The description adds meaning by explaining the token's origin (from checkout approval) and the privacy constraint. This supplements the schema without redundancy.

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

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

The description clearly states the tool lists recent orders for a site with optional status filtering. It distinguishes from siblings like get_order (specific order) and get_active_cart (active cart) by focusing on order listing and buyer privacy.

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

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

The description provides context on when to use the tool, notably requiring buyer_delegation_token from checkout approval. It does not explicitly exclude usage scenarios or compare to alternatives, but the clear requirement of the token guides appropriate usage.

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 indicate read-only and non-destructive behavior. The description adds context about the tool's role as a first step and that it returns site_id, which is valuable beyond the annotations. No contradictions.

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 two sentences long, both essential. It front-loads the core functionality and provides a concrete example, making it efficient and easy to parse.

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 no parameters, simple behavior, and the presence of an output schema, the description is fully complete. It covers the tool's purpose, usage, and relation to other 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?

There are no parameters, and the schema coverage is 100%. The description adds meaning by explaining the tool's output (site_id) and usage, meeting the baseline for 0 parameters.

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

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

The description clearly states it lists all registered e-commerce sites and retrieves site_id, which is required by other tools. The verb 'list' and resource 'sites' are specific, and the purpose is distinct from sibling tools (no other list tool for sites).

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

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

The description explicitly says to 'use this first' to find a site and get its site_id, which is needed by all other tools. This provides clear guidance on when to use the tool, though it does not explicitly mention when not to use 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds that it creates carts per store, reports out-of-stock items, and can auto-arm back-in-stock alerts via customer.email, providing full 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?

The description is well-structured, starting with the main purpose, then usage guidance, exclusions, and additional details. Every sentence adds value without redundancy.

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 tool's complexity (multi-store, nested objects), the presence of an output schema, and rich annotations, the description fully covers the behavior, use cases, and limitations, leaving no gaps.

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

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

With 100% schema coverage, the description adds value by explaining the items array structure, that shipping_address applies to every store, and that customer.email triggers back-in-stock alerts, going beyond the schema's basic definitions.

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

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

The description clearly states the tool assembles checkout-ready carts in one call for multi-product and optionally multi-store requests, distinguishing it from separate calls like create_cart, add_to_cart, and set_shipping_address.

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 use this when a buyer lists several products at once or provides an address upfront, and lists what it does not do (select delivery, check out, pay), directing to select_shipping_option and execute_checkout.

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 indicate destructiveHint=true and readOnlyHint=false. The description adds no extra behavioral context, such as what happens if the item doesn't exist or if removal affects cart totals or state.

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 core action, and no extraneous information. Every sentence is valuable.

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 simplicity of the tool (remove item), the description is adequate. There is an output schema (not shown) to document return values, but the description doesn't elaborate on post-removal state or errors.

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 detailed descriptions for each parameter. The description repeats the requirement for item_id but does not add new semantic meaning beyond the schema.

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

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

The description clearly states the action 'Remove a line item from the cart', which is a specific verb and resource. It distinguishes from sibling tools like add_to_cart and set_cart_quantity.

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

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

The description mentions the requirement for item_id from cart contents, providing some context. However, it does not explicitly state when to use this tool over alternatives or when not to use 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?

Discloses that without email only demand is recorded, and that the alert is sent via email. Annotations already indicate non-destructive and open-world, and description adds behavioral context without contradiction.

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 purpose, no unnecessary words. Every sentence adds value.

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

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

Covers purpose, usage scenario, parameter importance, and return value. Output schema exists so return details are not needed. Complete for the tool's complexity.

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 descriptions for each property. Description adds value by explaining why email is recommended and product_title optional, going 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?

Description clearly states the tool subscribes the buyer to a back-in-stock alert for an out-of-stock product. It uses specific verb 'subscribe' and resource 'back-in-stock alert', differentiating from sibling tools like add_to_cart or get_product.

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 'Use when the buyer asks to be notified...' and provides example phrases. Could be improved by stating it's only for out-of-stock products, but the context is clear.

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

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

Discloses both flows, explains that passing email results in a code emailed to the buyer (which the AI never sees), and that omitting email falls back to a browser link. Annotations indicate non-read-only and non-destructive, which aligns with the description. No contradiction.

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?

Concise single paragraph that starts with the core purpose, then presents the recommended flow, then the alternative, ending with a critical constraint. Every sentence earns its place.

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

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

Given the complexity of the delegation flow (two methods), annotations, and presence of an output schema, the description covers all necessary behavioral context, including the two paths, privacy aspect, and polling requirement.

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%, but the description adds significant value: explains the purpose of `email` (preferred flow), default for `scopes`, and strict condition for `marketing_opt_in` (only if buyer explicitly agreed).

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

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

The description clearly states the tool starts the human delegation (approval) flow for checkout/payment, distinguishing between the email-based flow and the device flow fallback. It also differentiates from sibling tools like submit_delegation_otp and check_delegation.

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 recommends passing email for in-chat approval via submit_delegation_otp, and describes the alternative device flow with polling check_delegation. States 'You can never approve a delegation yourself,' which is crucial guidance.

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

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

Annotations already indicate safe read (readOnlyHint=true) and open-world results (openWorldHint=true). Description adds detail: the card shows products, prices, IDs, and Add-to-cart controls, and emphasizes that filters must be applied via parameters. No contradiction.

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 lengthy but every sentence serves a purpose. It front-loads the main action and then systematically covers usage patterns. Could be slightly trimmed but remains well-organized and efficient for the complexity.

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 output schema exists (not shown), the description fully covers usage, parameter mapping, and behavioral expectations. Includes edge cases like empty results and multiple queries. No gaps for the complex 9-parameter 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% (baseline 3). Description significantly adds value by explaining the browse vs search distinction for query/queries, and provides concrete examples for mapping user phrases to price params and in_stock/category. Goes well beyond schema descriptions.

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?

Clearly states it finds products on a registered store, distinguishes between browsing (no query) and searching (with query), and mentions the interactive card result. Differentiates from sibling tools like get_product and compare_products.

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?

Provides explicit guidance on when to browse vs search, instructs to map buyer budget/price constraints to parameters, advises calling once with best intent, and handles empty results. Also tells the agent to keep replies brief and not re-list the card.

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 indicate non-read-only (readOnlyHint false) and non-destructive (destructiveHint false). The description adds meaningful behavioral context: it 'binds the rate to the cart so the total includes shipping', explaining the side effect beyond just selecting. This clarifies the impact on cart state and the necessity of ordering with execute_checkout.

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 two sentences: the first states the core purpose, the second adds behavioral and timing details. It is front-loaded with the action and entirely free of fluff. Every sentence adds value and is necessary for correct invocation.

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?

The description covers prerequisites (set_shipping_address called), the effect (rate binding, total update), and the appropriate time to call (before execute_checkout). Given the presence of an output schema and the tool's simplicity, this is nearly complete. One minor gap: it does not explain what happens if the option_id is invalid, but the error handling can be inferred from typical API behavior.

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 basic descriptions for each parameter. The description adds specific context for option_id by noting it comes from 'cart.shipping_options', which is a helpful cross-reference. However, cart_id and site_id receive no additional explanation beyond the schema. Since schema carries most of the burden, a 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 clearly specifies the action: selecting one of the shipping options returned by set_shipping_address. It explicitly ties the tool to a specific context (shipping selection within checkout flow) and distinguishes it from siblings by referencing the sequential dependency on set_shipping_address and the precondition for execute_checkout.

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

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

The description gives explicit usage context: call after set_shipping_address and before execute_checkout. It states the effect (binds rate, updates total). It does not explicitly list alternatives, but the sequential instruction is clear and helpful for an agent navigating the checkout flow.

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 indicate destructiveHint=true and readOnlyHint=false. The description adds context: the cart is authoritative, updates are live, and zero removes the line. 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?

Three sentences clearly separate purpose, requirements, and special behavior (removal). Concise and front-loaded, but could be slightly more efficient with word choice.

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 presence of an output schema and full parameter coverage, the description covers all needed context: live update, required fields, removal behavior, and return value.

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?

All four parameters have detailed descriptions in the schema (100% coverage). The description restates item_id and quantity requirements but adds no new meaning beyond the schema.

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

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

The description clearly states the tool sets a cart line's quantity, specifying it's live and authoritative. It distinguishes from siblings like remove_from_cart and add_to_cart by focusing on quantity adjustment, including removal at zero.

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

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

The description provides clear context (requires item_id and quantity, server as source of truth) but lacks explicit when-to-use vs alternatives. It implies use for updating quantities, which is distinct from addition or removal.

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 indicate readOnlyHint=false and destructiveHint=false, consistent with the description. Description adds that the tool collects buyer input and returns shipping options, but doesn't specify side effects like overwriting previous address. Good 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?

Three short sentences, front-loaded with purpose and return value, then usage order, then parameter guidance. No unnecessary words.

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

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

Given the output schema exists and annotations cover safety, description is complete: it explains purpose, return value, prerequisites, and parameter hints.

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 has 100% coverage with descriptions, so baseline is 3. Description adds value by emphasizing required country_code and suggesting postal_code/state for accuracy, aiding interpretation.

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

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

The description clearly states the tool sets the cart shipping destination and returns available shipping options with costs. It distinguishes from the sibling tool select_shipping_option by specifying the order of calls.

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 after items are in the cart and before select_shipping_option, and advises to include postal_code/state for accurate rates. Provides clear usage 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 indicate readOnlyHint=false, destructiveHint=false, openWorldHint=true, which are consistent. The description adds key behavioral details: the code is user-provided via email, and success returns a delegation_token. It does not contradict annotations and supplements them with practical constraints.

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

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

The description is three sentences long with no filler. It front-loads the action (submit code), explains the context, and ends with the critical limitation (agent cannot obtain code). Every sentence adds unique value.

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 tool has 3 parameters, no nested objects, and an output schema exists, the description fully covers the workflow: it specifies the input requirements, the user's role, and the output outcome. No gaps or missing information for an agent to use 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?

Schema coverage is 100%, so baseline 3 is appropriate. The description adds meaning by explaining that 'code' is a 6-digit code from the buyer's email and 'device_code' comes from request_delegation, while 'site_id' is optional. This clarifies the source and type of each parameter 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 clearly states the tool submits a 6-digit code to approve delegation and returns a delegation_token for checkout/payment. It distinguishes from sibling tools like request_delegation and submit_payment_otp by specifying the exact input and outcome.

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

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

The description explicitly informs that the agent cannot obtain the code itself — the user must read it from their email and provide it. It also ties the tool to request_delegation. While it doesn't state when not to use it, the context is clear enough for an agent.

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

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

The description discloses the behavioral effect (authorizing a charge) and required inputs for safe execution. Annotations already indicate destructiveHint=true, and the description adds context about needing the delegation token and polling afterwards, with no contradiction.

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 step and condition, no extraneous words. Every sentence contributes essential information (when, what, requirement, post-action).

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 output schema exists, the description sufficiently covers the use case: it explains the triggering condition, required token, and follow-up polling. No gaps remain for safe and 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% with clear parameter descriptions. The description adds value by reinforcing that buyer_delegation_token must be the same as used in initiate_payment. However, it does not detail every parameter, but the schema handles that adequately, so a slight above-baseline score 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 clearly states it is step 3 for mobile_money only, used when initiate_payment returns action "submit_otp". It identifies the specific verb 'Submits' and resource 'one-time password', and distinguishes from sibling tools like submit_delegation_otp by scoping to payment flow.

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

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

Explicitly provides when to use (step 3, conditional on action), what is required (same buyer_delegation_token), and post-invocation steps (poll get_payment_status). This gives clear guidance on usage context and next actions.

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