Synchronity

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

Annotations already indicate this is a write (not read-only) and non-destructive operation. The description adds useful detail: adding items is non-destructive, batching items is encouraged, and out-of-stock behavior with email alerts is disclosed.

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

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

Two sentences, front-loaded with the core action and critical usage guidance (reuse cart_id, when to create_cart). No extraneous text.

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

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

Given complexity (8 params, nested objects) and presence of output schema, the description covers main points: batching items, addons handling, email for stock alerts. Does not explain return values, but 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 baseline is 3. The description adds value by explaining batching (add several products in one call), linking email to back-in-stock alerts, and detailing addons semantics beyond schema types.

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 the verb (Add) and the resource (product variant or base product to an existing cart). Distinguishes itself from create_cart by specifying reuse of existing cart_id and when to call create_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 tells the agent to reuse the active cart_id from chat history and to only call create_cart first if no cart exists. Provides clear when-to-use and when-not-to-use 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 readOnlyHint=false (write operation) and destructiveHint=false. Description adds that it returns the updated cart, which is consistent but not new behavioral depth. No mention of idempotency, error handling, or side effects.

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, each essential. First sentence defines the action, second sentence describes the return. No fluff.

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 simple parameters (three strings) and existence of output schema, the description captures the essential information. No missing context for agent selection.

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 parameters are well-described in schema. Description does not add additional meaning beyond stating the action.

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 action ('Apply'), resource ('discount or promotional code'), and target ('cart'). It also mentions the return value ('updated cart with discount applied'). No sibling tool performs the same function.

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?

No guidance on when to use this tool versus alternatives, prerequisites (e.g., cart must exist), or when not to apply a coupon. Implicit usage but not explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds behavioral details: polling mechanism, conditional return of delegation_token on 'approved' status. 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?

Two sentences with no wasted words. Front-loaded with the primary action 'Poll for human approval'. 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?

For a simple polling tool, description covers behavior, conditional output, and usage context (prerequisite and consumer). Output schema exists but description still explains the token usage.

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 provides full coverage (100%) with clear description of device_code as returned by request_delegation. The tool description does not add additional 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?

Clearly states the tool polls for human approval of a delegation request and returns the delegation_token on approval. It distinguishes from siblings by specifying the output usage in execute_checkout and the prerequisite request_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 mentions when to use (poll for approval) and how the output is used in execute_checkout. Does not explicitly state when not to use or alternative tools, but the context is clear enough.

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 valuable behavioral context beyond annotations: the fail-open strategy and that partial results are returned even if some sites time out. Annotations already indicate readOnlyHint=true and openWorldHint=true, so the disclosure is helpful but could include more details on concurrency or timeout limits.

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

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

The description is exceptionally concise with two sentences that convey the core purpose and a key behavioral detail. No extraneous information, and the most important aspect (cross-site comparison) is front-loaded.

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

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

Given the tool's complexity (6 parameters, 2 required, output schema present), the description adequately covers the key behavioral trait (fail-open). While it could mention that results are aggregated from multiple sites, the combination of annotations and schema provides sufficient context.

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 describes each parameter. The tool description does not add extra meaning to parameters beyond what is in the schema, meeting the baseline score of 3.

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: comparing products across multiple e-commerce sites simultaneously. It uses specific verbs and resources, and distinguishes from sibling tools like search_products and get_product by emphasizing the cross-site comparison aspect.

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, which provides context on how partial results are handled, but it does not explicitly specify when to use this tool versus alternatives like search_products. No when-not or alternative references 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?

Although annotations already show readOnlyHint=false, the description adds important behavioral context about session reuse and idempotency. However, it does not disclose error conditions or authorization requirements for creation.

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 concise sentences plus an IMPORTANT note. Every sentence adds value; no extraneous text. Front-loaded with purpose 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 2 parameters and an output schema, the description covers purpose, return value, and critical usage guidance. No missing information.

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 both parameters. The description adds no additional meaning beyond the schema, only referencing site_id implicitly via 'for a specific site'. 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?

Clearly states it creates a new shopping cart for a specific site and returns a cart_id. The verb 'create' and resource 'cart' are specific. Distinguishes from siblings like get_cart or add_to_cart by focusing on initialization.

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 to reuse an existing cart_id and not call create_cart again if one already exists for the site. This provides clear when-to-use and when-not-to-use guidance, referencing chat history 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?

The description discloses that the order is created UNPAID (status 'pending') and details the required delegation token and payment flow. It adds context beyond annotations (destructiveHint=true) and does not contradict them.

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

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

The description is well-structured: purpose first, then requirements, then a clear imperative note with step-by-step instructions. 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 complex checkout flow and 15 parameters, the description covers purpose, requirements, and post-usage steps. It references expected outputs (order_id, payment_url), but does not address error cases or invalid tokens, leaving minor 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?

Schema coverage is 100%, so the description adds minimal parameter meaning beyond summarizing that a delegation token and shipping address are needed. No new semantics for individual parameters are 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 'Execute checkout for a cart to create an order' which is a specific verb+resource. It mentions required inputs (delegation token, shipping address) and distinguishes from sibling tools like 'get_cart' or 'add_to_cart' by being the finalization 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 guidance is provided: 'do NOT stop here... Immediately continue the in-chat payment flow' along with a detailed sequence of subsequent calls (get_payment_methods, initiate_payment, etc.) and when to use payment_url as fallback.

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 behavioral details beyond annotations: returns rebuilt items if expired or null if no cart. No contradiction with readOnlyHint.

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, each essential: purpose then usage and return behavior. No 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?

Simple tool with output schema; description covers purpose, usage, and behavior completely. 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?

Schema coverage is 100%, description does not add significant extra info beyond schema but contextualizes site_id role.

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 retrieve buyer's in-progress cart for a site and mentions resuming conversation. Distinguishes from siblings like get_cart or create_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 says to call before assuming a new cart when conversation continues or after cart error. Could name alternatives but provides solid 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 declare readOnlyHint=true and destructiveHint=false. The description adds that the cart is shown to the user and the output includes items, pricing, discounts, and totals, which is additional context but not critical 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: first states purpose, second gives agent instruction. Front-loaded and efficient, though the instruction is about output format rather than tool functionality.

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 covers purpose and provides a useful behavioral note. The tool has simple parameters well-documented in the schema, making the description 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% with descriptions for both parameters. The description does not add any extra meaning beyond what the schema provides, so 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 clearly states 'Retrieve current cart contents' with specific verb and resource. However, it does not differentiate from the sibling tool 'get_active_cart,' which may cause confusion about which to use.

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?

No guidance on when to use this tool vs alternatives like 'get_active_cart' or 'create_cart'. The only instruction is about agent response brevity, not tool selection.

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), description adds valuable behavioral details: orders are buyer-private requiring a delegation token, payment status logic, and instruction not to assume database lag. This fully informs agent 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?

Single paragraph but densely informative with no redundancy. Front-loaded with main purpose. Slightly long but every sentence contributes meaningful guidance.

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, parameters fully described, and description covers essential behavioral nuances (payment status, delegation token usage). Complete for correct agent 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 has 100% coverage, but description adds semantic value for buyer_delegation_token by explaining its origin and purpose (confirming buyer ownership). This goes beyond the schema description.

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

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

Clearly states the tool retrieves order details by ID, listing specific information (items, status, shipping, tracking). Distinguishes from sibling tools like list_orders (which lists many) and other order-related tools.

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 context on when to use the tool and important caveats about payment status interpretation. While it doesn't directly compare to siblings, it gives actionable guidance (e.g., treat 'pending' as unpaid, initiate payment 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 read-only (readOnlyHint: true) and non-destructive. Description adds flow-step context (STEP 1), output structure (gateways array), and fallback behavior (DEFAULT_SITE_ID). 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?

Front-loaded with purpose, then output details, then step-by-step instructions. No extraneous words. Every sentence adds necessary information.

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

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

Despite having an output schema, description still outlines return shape (channels, gateways with id/label/channels). Covers prerequisites (order exists), next steps, and fallback. Complete for an agent.

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 value by explaining site_id fallback ('falls back to DEFAULT_SITE_ID if omitted') and noting order_id is the identifier. This goes 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?

Description clearly identifies as 'STEP 1 of the in-chat payment flow', specifies the resource (payment methods for an order), and distinguishes from siblings like initiate_payment or get_payment_status by detailing output and position in 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?

Provides explicit sequence: 'Call this first, after an order exists. Then call initiate_payment...' and instructs how to handle multiple gateways ('ask the buyer which they want to use'). No ambiguity.

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 readOnly and non-destructive. Description adds valuable context: polling behavior, success/failure handling, and the fact that purchase is not complete until status is 'paid' or 'processing'. Does not contradict 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?

Description is well-organized and informative, but slightly verbose with multiple sentences. However, every sentence adds necessary behavioral context. Front-loaded with purpose and key instructions.

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 payment flow and the presence of an output schema, the description adequately covers polling, success/failure, and user guidance. Could benefit from mentioning that the output schema contains the payment_status, but 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 coverage is 100% with clear descriptions for both parameters (site_id and order_id). Description does not add additional parameter semantics beyond what schema provides, so baseline score of 3 applies.

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

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

Clearly states it's the final step of in-chat payment flow, returns PaymentSession, and specifies the action based on payment_status. Distinguishes from sibling tools like initiate_payment and submit_payment_otp by emphasizing it is the final poll 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?

Provides explicit when-to-use: after initiate_payment/submit_payment_otp, and when-to-poll (every ~5 seconds). Gives clear criteria for success vs failure and what to tell the user. No alternative tools are mentioned but the context is very specific to the payment 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 indicate readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds context by noting it 'may return addons' and gives specific handling instructions. No contradiction with annotations. It discloses 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 paragraphs, but both are necessary. The first sentence efficiently states purpose, then transitions to addon details and usage instructions. No redundant information, but could be slightly more concise by merging some sentences.

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 low complexity (two params, simple read operation) and presence of an output schema, the description is complete. It covers the main output fields (variants, pricing, images, availability, addons) and provides additional context for handling addons. Agent has enough information 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% for both parameters (site_id and product_id), so baseline is 3. The description does not add additional meaning beyond the schema; it mentions the parameters only implicitly via the tool's purpose. No extra value added.

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 'Retrieve' and the resource 'detailed information about a specific product including variants, pricing, images, and availability'. It distinguishes from sibling tools like search_products (search) and add_to_cart (add to cart) by specifying the scope and output.

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 instructions: 'When a product has addons, present them to the buyer and collect every addon with required: true before calling add_to_cart'. Also advises on how to handle options with price_modifier and reminds the agent to keep reply brief because the card already shows details.

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 is read-only (Fetch, Returns) and non-destructive, consistent with annotations (readOnlyHint=true, destructiveHint=false). It adds value by detailing the rich return data (trust score, authenticity flags, sentiment analysis) and the recommended workflow, which goes beyond the annotation hints.

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 highly concise, two sentences with an emoji, front-loading the purpose and recommended usage. 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 existence of an output schema (mentioned in context signals) and clean annotations, the description sufficiently covers the tool's purpose, return values, and usage context. It is complete for an AI agent to select and invoke 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% with adequate descriptions for all four parameters. The tool description does not add new information about parameters, so it meets the baseline for high coverage without needing to compensate.

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 fetches product reviews and authenticity consensus, listing specific return fields (average rating, trust score, sentiment analysis, authenticity flags, recent reviews). It distinguishes itself from sibling tools like get_product and compare_products by recommending it for pre-purchase verification and scam detection.

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 recommends calling this tool before making purchase decisions and before adding each product to cart ('Always call this for each product before adding to cart to verify quality and detect scams.'). It provides clear context but does not explicitly state when not to use or name alternative tools.

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 hint (money spent) and open world hint. The description reinforces this by emphasizing the need for human approval and enumerating possible instruction actions (submit_otp, approve_on_phone, redirect). It adds context beyond annotations 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?

The description is lengthy but well-structured with sections for token, channel specifics, and post-call handling. Every sentence provides value, though some clauses could be tightened (e.g., aliases list).

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 all necessary contextual elements: step in workflow, token precondition, channel-specific requirements, and follow-up actions. Fits well with sibling tools and addresses complexity of 7 parameters and dynamic instruction handling.

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 extra meaning: phone format examples (+233...), provider aliases (telecel→vod, tigo→tgo), and the critical buyer_delegation_token requirement. This goes 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?

The description clearly identifies 'initiate_payment' as STEP 2 of the payment flow, starting a payment session for an order. It uses a specific verb ('Starts') and resource ('payment session'), and distinguishes itself from sibling tools like 'submit_payment_otp' and 'get_payment_status'.

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

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

Explicitly states when to use the tool (after obtaining buyer_delegation_token), provides alternatives for different channels, and instructs on post-call actions based on instruction.action. It also references sibling tools like 'request_delegation' and 'check_delegation' for token acquisition.

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=true and destructiveHint=false. The description adds important behavioral context: privacy restriction and the need for a delegation token, which goes 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?

Two sentences with no filler. The first sentence states the core function and filtering, the second explains the privacy mechanism. Every phrase serves a purpose.

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 provide safety cues, the description covers the essential aspects: purpose, filtering, and authentication. It does not detail pagination or result limit, but those are in the 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?

With 100% schema coverage, the baseline is 3. The description adds minimal extra meaning for parameters by noting the filtering option and the purpose of the delegation token. No parameter details are missing, but the description could clarify pagination 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?

Description clearly states 'List recent orders for a site' with optional status filtering. The verb-resource-action pattern is explicit, and the scope (per site, per buyer) distinguishes it from sibling tools like get_order (single order) or list_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 explains that orders are buyer-private and require a buyer_delegation_token, giving clear context on when to use this tool (listing a specific buyer's orders). However, it does not mention when not to use it or contrast with alternatives like get_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 already provide readOnlyHint=true and destructiveHint=false. The description adds workflow context (retrieving site_id for subsequent tools), which is valuable beyond 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?

Two sentences, no wasted words. Front-loaded with the primary action, followed by usage guidance. Perfectly concise.

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

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

Given no parameters and the existence of an output schema, the description sufficiently explains what the tool does and why it's important (provides site_id). Complete for its 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?

The tool has zero parameters, so schema coverage is 100%. The description adds no parameter-specific info, which is appropriate. For a parameterless tool, baseline is 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 the tool's purpose: 'List all registered e-commerce sites.' It uses a specific verb ('list') and resource ('registered e-commerce sites'), and distinguishes itself from sibling tools by noting that it retrieves site_id required by others.

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 advises when to use: 'Use this first to find a site by name... and get its site_id, which is required by all other tools.' This provides clear context and differentiates from other tools that require the site_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 indicate readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description enriches this by detailing the exact actions: creating carts per store, adding items, setting shipping address, reporting out-of-stock items, and arming back-in-stock alerts when customer.email is provided. It also clarifies that the tool does not finalize the purchase, which is critical behavioral context 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?

The description is concise yet comprehensive. Each sentence adds value: the first states the core function, the second explains when to use it, the third lists what it does not do, and the fourth provides additional behavioral details (out-of-stock handling). No fluff or repetition, and the structure is logical.

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 all aspects: the tool's actions (create carts, add items, set shipping), its limitations (does not handle selection/payment), output (carts with delivery options), and optional features (back-in-stock alerts). Given the complexity of multi-store and nested parameters, the description is fully adequate for an AI agent to understand and 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% with descriptions for each parameter. The tool description adds extra context, e.g., that customer.email arms back-in-stock alerts and that items may span multiple stores grouped by site_id. While the schema already provides adequate descriptions, the tool description adds meaningful usage context that helps an agent understand parameter relationships.

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: assembling checkout-ready cart(s) for multi-product and multi-store requests. It uses specific verbs ('Assemble', 'Creates') and distinguishes itself from sibling tools like 'create_cart', 'add_to_cart', and 'set_shipping_address' by noting it combines these steps. It also explicitly states what it does NOT do (select delivery, check out, pay), leaving no ambiguity.

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 provides usage guidance: 'Use this when the buyer lists several products at once... instead of calling create_cart/add_to_cart/set_shipping_address separately.' It also clarifies when not to use it by stating it does not handle delivery selection, checkout, or payment. This gives 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; description adds no new behavioral context beyond confirming removal action.

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 concise sentences with no unnecessary words; front-loads the action and prerequisite.

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 removal tool with output schema present, description adequately covers purpose and prerequisite; slight gap in usage guidance but 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 coverage is 100% and description does not add significant meaning beyond what the schema provides, merely restating the item_id requirement.

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 action ('Remove') and resource ('line item from the cart'), distinguishing it from siblings 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?

Description mentions prerequisite (item_id from cart contents) but does not explicitly state when to use vs alternatives like adjusting quantity via set_cart_quantity.

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 explains what happens ('emailed when product next seen in stock'), what the return value represents ('whether an email alert was armed'), and the consequence of missing email. This adds value 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?

Five sentences with front-loaded purpose. No wasted words. Every sentence contributes clarity.

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 that an output schema exists (context signal), the description adequately covers behavior and return value. No missing information.

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 context: email is 'recommended — without it no alert is sent', and product_title helps for 'clearer alert + merchant view'. This 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 starts with a clear verb 'Subscribe' and resource 'back-in-stock alert'. It explicitly states the action on an 'out-of-stock product'. This is unique among siblings 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?

The description provides explicit usage guidance: 'Use when the buyer asks to be notified...' with example phrases. It also advises collecting the buyer's email for the alert to work, which is practical.

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?

Describes security-critical behavior: the agent never sees the OTP code and cannot approve on behalf, going well 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 concise sentences that pack essential flow logic and warnings 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?

Covers both flows, prerequisites, post-actions, and ethical constraints; output schema presence reduces need to document returns.

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?

Adds meaning beyond schema by explaining the behavioral impact of email (triggers OTP flow) and marketing_opt_in (requires explicit consent). Schema coverage is 100%, so baseline 3 is exceeded.

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 a human delegation flow for checkout/payment, distinguishing it 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 explains two usage paths (with and without email), recommends the email path, and directs to call submit_delegation_otp or poll check_delegation accordingly.

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

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

Annotations declare readOnly, openWorld, non-destructive; description adds critical context: returns paginated interactive card, card reflects exact results, filters must be applied on call, and search behavior when empty. 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?

Description is relatively long but every sentence is informative and necessary. Front-loaded with core purpose. Could be slightly more concise, but the detail is justified by tool 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 9 parameters, output schema exists, and sibling context, this description covers all aspects: browse vs search, filter mapping, card behavior, empty results handling, and agent response style. Extremely 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 coverage is 100%, yet description adds significant value beyond schema: explains when to omit query (browse), how to use multiple queries, and maps natural language price constraints to min_price/max_price. Also clarifies use of in_stock and category filters.

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 'Find products on a registered store' and distinguishes browse vs search with explicit instructions. Purpose is unambiguous and highly specific.

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 exhaustive guidance: when to browse vs search, how to translate user constraints into parameters (price, stock, category), and cautions against refiring empty searches. Also explains agent's reply brevity due to card rendering.

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 (which indicate non-read-only and non-destructive), the description adds that it binds the rate to the cart, updates the total, and pre-fills checkout. No mention of idempotency or errors, but useful 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, no wasted words. 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 tool's moderate complexity, an output schema exists, and the description fully covers prerequisites, effects, and next steps. 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?

Schema coverage is 100%, so baseline is 3. The description repeats the schema's note about option_id from cart.shipping_options, adding no new detail but reinforcing the workflow.

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 selects a shipping option returned by set_shipping_address, distinguishing it from sibling tools like set_shipping_address and execute_checkout. The verb 'select' and resource 'shipping option' are specific.

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 call before execute_checkout and implies it should follow set_shipping_address. No exclusions or when-not-to-use are given, but the workflow 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?

The description discloses that the update is live (destructiveHint is already true), requires specific parameters, and returns the updated cart. It adds context beyond annotations, such as the removal behavior and the live update 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 concise sentences with no wasted words. The first sentence clearly states the action, and the second provides key details.

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 4 required params, full schema coverage, and an output schema, the description adequately covers behavior, parameter usage, and return value. It may lack explicit error handling or prerequisites, but is sufficiently complete for typical use.

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 source of item_id ('from the cart contents') and reinforcing that quantity is absolute and 0 removes the line, which enhances understanding 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 'Set' and the resource 'a cart line's quantity', and distinguishes from siblings like add_to_cart and remove_from_cart by emphasizing that it updates the live server cart and can remove a line with quantity 0.

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 explains when to use the tool: to set a line's absolute quantity, and that a quantity of 0 removes the line. It does not explicitly mention when not to use or provide alternatives, but the context is clear enough for an AI agent to differentiate.

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

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

Annotations declare readOnlyHint=false (write operation) and destructiveHint=false (not destructive). The description adds that the tool returns available shipping options, which the annotations do not cover. It does not contradict annotations, and the behavioral context (setting address) is clear.

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 main action (set and return), followed by ordering and recommendations. Every sentence adds value, 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 presence of an output schema (context: true), the description does not need to detail return values. It covers purpose, usage context, required parameters, and sequence. The description is complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds a note about country_code being required and recommends postal_code/state for accurate rates, which provides additional usage context but does not fundamentally add new meaning beyond the 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?

The description states exactly what the tool does: 'Set the cart shipping destination... and return available shipping options with costs.' It uses a specific verb (set) and resource (cart shipping destination). It also distinguishes from the sibling tool select_shipping_option by calling out the ordering dependency.

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 sequence guidance: 'Call after items are in the cart and before select_shipping_option.' It also specifies which parameters are required (country_code) and recommends optional ones for accuracy (postal_code/state). This helps the agent decide when to invoke the tool.

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 critical context beyond annotations: it requires user-provided code, cannot be automated, and returns a delegation_token. It aligns with readOnlyHint=false and destructiveHint=false, and adds 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?

Two 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?

For a verification step, the description covers the prerequisite, input, and output usage. It is complete given the tool's complexity and the presence of an 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?

Schema already documents parameters well (100% coverage). The description adds meaning by linking code to email context and explaining the output token's purpose, enhancing understanding of the 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 specifies the action ('submit the 6-digit code'), the resource ('delegation approval'), and the returned token. It clearly distinguishes from siblings like request_delegation and submit_payment_otp.

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 states when to use it (after receiving the code from user) and that the code must be obtained from the user's email, implying the prerequisite request_delegation. It lacks explicit alternatives but is clear enough.

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 destructive and open world. Description adds that token must be same as initiate_payment and that polling is needed for final status, which informs agent about non-blocking nature and required follow-up.

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 concise sentences front-loaded with step number, condition, and action. No redundancy. Efficient use of text.

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

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

Complete given complexity: specifies step, condition, required token, and polling advice. Output schema exists for return values. References sibling tools appropriately.

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 good descriptions. Description reinforces token requirement but doesn't add significant new semantics beyond 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 it submits the OTP for mobile money payment authorization, explicitly linking to initiate_payment with specific condition (instruction.action == 'submit_otp'). Distinguishes from siblings like submit_delegation_otp by specifying payment context.

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

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

Explicitly says when to use: STEP 3 for mobile_money only, with condition from initiate_payment. Provides post-submission guidance to poll get_payment_status. No explicit when-not, but condition implies exclusivity.

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