Custom Blinds Shop

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

No annotations provided, but description fully discloses irreversibility, permanence, and lack of effect on related checkouts/orders.

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 with no redundancy. The core action is stated first, followed by usage guidance and consequences.

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 tool (1 param, no output schema), the description is fully adequate: covers what, when, side effects, and irreversibility.

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 0% but description mentions 'by cart_id', linking the parameter to its purpose. However, no additional constraints or format details are given.

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 action: 'Permanently delete a cart by cart_id'. Differentiates from siblings by mentioning no effect on checkouts or orders.

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: 'when the customer abandons the session or wants to start over'. Also advises on post-use: 'create a new cart to restart'.

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?

With no annotations, the description conveys that the tool aborts an unpaid checkout and releases the ID. It clarifies no effect on confirmed orders. While it implies a destructive action, it could further specify the state of the associated cart.

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

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

Three short, front-loaded sentences with no wasted words. First sentence defines action, second gives usage context, third provides alternative. 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?

For a simple cancellation tool, the description covers the core action, usage conditions, and what not to expect. It lacks explicit detail on cart lifecycle, but overall it is sufficient 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?

The single parameter 'checkout_id' is mentioned in context ('release its checkout_id'), but the description does not explain its format or provide guided usage beyond the context. Since schema description coverage is 0%, the description adds partial 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 verb 'Abort' and the resource 'unpaid checkout', and specifies the release of its checkout_id. It distinguishes itself from sibling tools like create_checkout and complete_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?

Explicitly states when to use ('customer changes their mind after create_checkout but before completing payment') and when not ('no effect on orders already confirmed by webhook'). Provides a clear alternative action: creating a new cart and checkout from scratch.

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?

With no annotations, the description carries full burden. It discloses return fields (in_stock boolean, expected_restock_date, up to 5 alternatives) and implies a read-only check by stating it 'verifies' availability. It could be strengthened by explicitly stating it's a read-only operation.

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 concisely states the action and return values, second provides usage guidance. No redundant information; 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 check tool with 2 parameters and no output schema, the description covers purpose, usage, and return fields. However, it omits potential error cases (e.g., invalid product_id) and could explicitly state it's a read-only operation.

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 0%, so the description must compensate. It implies that 'product_id' identifies the product and 'colour_name' specifies the colour, but does not provide explicit details on format, constraints, or examples. The overall context helps but leaves room for ambiguity.

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 a specific verb 'Verify whether a specific colour is available' and names the resource (colour stock for a product). It clearly distinguishes from sibling tool 'configure_product' by indicating this prevents failure from out-of-stock selections.

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 when to call: 'when a customer requests a named colour or when you want to prevent a configure_product failure due to an out-of-stock selection'. This provides clear context for usage, though it lacks explicit exclusions for when not to use.

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 checkout is locked after calling, payment confirmation is asynchronous via webhook, and return value is payment_url. No annotations provided, so description carries full burden and does it well.

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?

Packed with information but remains clear. Slightly long but justified by complexity; 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?

Covers purpose, usage, behavior, return value, and post-conditions (webhook, polling, lock). No output schema, but description compensates fully.

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 context that payment_method overrides previous values and ties methods to providers (Yoco/Ozow). Schema already has enum descriptions, but description enriches with override 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 phase 2 of checkout finalization, mints payment link, and returns payment_url. Distinguishes from related tools like cancel_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?

Explicitly tells when to use (after create_checkout), mentions alternative cancel_checkout if customer changes mind, and explains post-call flow (webhook, polling).

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 key behaviors: validates colour existence and stock, prices the blind, returns a configuration summary. Missing nuance on error handling and state changes, but given no annotations, it provides sufficient transparency.

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

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

Four sentences, each serving a purpose: main action, validation, output, usage hint. No extraneous words, front-loaded with core 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?

Covers purpose, validation, output destination, and prerequisite. Minor gap: no mention of error behavior if validation fails. Otherwise comprehensive for a config tool with no 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 coverage is 100%, but the description adds significant meaning: color validation context, mount type explanation, province routing logic, and product_id source. These details go well 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 clearly states the tool locks in a full blind specification, listing the key attributes (product, dimensions, colour, mount type). It distinguishes from siblings by specifying the return value is for create_cart and suggesting alternative flow with check_colour_stock.

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: 'Lock in a full blind specification' and a clear when-not-to-use hint: 'Call check_colour_stock first if availability is uncertain.' Aligns with siblings like check_colour_stock and create_cart.

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?

No annotations are provided, so the description must disclose behavioral traits. It states 'no auth needed', mentions the 24-hour TTL on cart_id, and indicates optional seeding. However, it does not describe error conditions, idempotency, or whether calling it multiple times creates multiple carts. The description is adequate but lacks some behavioral details expected for a mutation tool.

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

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

The description is two sentences long, front-loaded with the core purpose in the first sentence, and wastes no words. It efficiently communicates the essential information: purpose, no auth, return value, TTL, optional parameters, and next steps.

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 no output schema, the description specifies the return value (cart_id with TTL) and provides a clear workflow (next steps: update_cart, create_checkout, complete_checkout). However, it lacks details on validation or format requirements for the optional parameters (items, customer), which could be important for correct 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?

The input schema has 100% coverage with descriptions for both parameters. The description adds semantic value by referring to items as 'pre-configured blind items' and 'customer details,' which clarifies the expected format and purpose beyond the generic schema descriptions. It improves understanding of what the parameters represent.

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 starts the purchase flow, creates a cart session, returns a cart_id with a 24-hour TTL, and optionally seeds items and customer details. It is specific about the verb and resource ('create cart') and is distinguished from siblings by being the first step in the flow, with explicit next steps mentioned.

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 context: 'Start the open UCP purchase flow — no auth needed.' It also indicates when to use it as the initial step and hints at the sequence (next steps). However, it does not explicitly state when NOT to use it or mention alternatives among siblings, such as using a different 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?

No annotations are provided, so the description carries the full burden. It discloses that customer name, email, and phone are required, and that it returns a checkout_id without minting a payment link. However, it does not discuss side effects (e.g., whether the cart is modified or locked), authentication needs, rate limits, or error conditions. For a creation tool, more depth on safety and flow constraints would be beneficial.

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 four sentences, each adding distinct value: purpose, flow context, requirements, and next steps. It is front-loaded with the most critical information and avoids redundancy. 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 tool's complexity (4 parameters, nested objects, no output schema, no annotations), the description covers the multi-phase flow, required inputs, and corrective alternatives. It lacks details on return value structure, error states, and idempotency, but provides sufficient context for an agent to integrate into the broader purchase process.

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 50%, but the description adds meaning beyond the schema. It explains the mutual exclusivity of 'cart_id' vs 'items', notes required customer fields (name, email, phone), and implies a default payment method ('yoco'). The description contextualizes the parameters within the purchase flow, which helps an agent understand how to fill them.

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 'Phase 1 of 2 in the purchase flow' and defines the tool's action: convert a cart into a checkout. It distinguishes from the sibling tool 'complete_checkout' by noting that no payment link is minted yet. The verb 'create' and resource 'checkout' are explicit.

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 instructions on when to use this tool (first phase of purchase) and what not to expect (no payment link). It mentions 'use update_checkout to correct customer details before finalising', offering an alternative for corrections. However, it does not explicitly contrast with other sibling tools like 'create_cart', but the context of purchase flow 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?

Discloses that the tool requires authentication (Bearer token), server-side price re-verification (agent-supplied prices ignored), and returns a payment_url. Since no annotations exist, description carries full burden and does so well.

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 with no wasted words. Front-loads key information: legacy status, preferred alternative, usage condition, behavioral note, and return type.

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 auth requirement, price validation, return value, and alternative flow. Lacks error handling details but sufficient given the tool's simplicity and no 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 coverage is 100%, but description adds value by noting that unit_price_zar and total_price_zar are ignored due to server-side verification. This clarifies parameter behavior 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 states it creates an order and returns a payment URL. It distinguishes itself from the open UCP flow by specifying it is a legacy auth-required single-call alternative.

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

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

Explicitly recommends preferring the open UCP flow and only using create_order when a Bearer token is available and a single-call path is desired. Provides clear alternative context.

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

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

The description explains the AR tool's behavior (uses phone camera, A4 page, customer-uploaded photo) and the modes. Without annotations, it carries the full burden; it is sufficiently transparent for a simple URL retrieval tool.

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

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

Three sentences, front-loaded with purpose, every sentence adds value. No redundant information.

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

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

For a 2-parameter tool with no output schema, the description covers purpose, usage, and parameters. It lacks explicit mention of the return value (URL), but the tool name implies it.

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

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

Schema coverage is 100%, and the description adds context (e.g., 'pre-select a product' with example values) beyond the schema descriptions, making the parameter semantics clearer.

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 'surfaces the AR measurement tool or product visualizer' with specific use cases (measure window or preview blind). It differentiates from sibling tools like 'get_product' or 'lookup_catalog' by focusing on AR 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?

The description gives clear usage context ('when a customer wants to measure their window or preview a blind') and explains the mode parameter. However, it does not explicitly state when not to use or provide 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?

No annotations are provided, so the description carries full burden. It discloses the cart expiration (24h inactivity) but does not explicitly state the operation is read-only or describe behavior when cart_id is invalid. However, the description is truthful and provides key 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?

Each sentence serves a distinct purpose: (1) what the tool does, (2) when to use it, (3) expiration policy. No redundant or extraneous text. Efficiently uses three sentences 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?

For a simple retrieval tool with one parameter and no output schema, the description adequately covers purpose, usage timing, and a key constraint (expiration). It does not specify error handling (e.g., if cart doesn't exist) or the exact structure of the response, but the output is implied (item list, totals, customer details). Slight gap in completeness for edge cases.

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 schema description coverage at 0%, the description adds minimal value: it mentions the parameter is a cart_id but does not explain its format, source, or constraints (e.g., required length, valid characters). The parameter name is self-descriptive, but the description should provide more guidance for correct invocation.

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 a 'live cart state' by cart_id, including item list, totals in ZAR, and customer details. It distinguishes this from sibling tools like create_cart, update_cart, cancel_cart, and get_checkout by specifying the exact resource 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?

Explicitly advises to call after update_cart to confirm changes before proceeding to create_checkout, providing a clear workflow context. Also notes the 24-hour inactivity expiration, helping the agent decide when to use this tool versus 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?

With no annotations, description covers return values and conditional payment_url. Does not mention error behavior, rate limits, or auth requirements, but adequately describes the read operation.

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 action and return values, followed by usage guidance. No extraneous 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?

For a simple get tool with one param and no output schema, description covers purpose, return fields, and usage context. Could mention error conditions or the 'if already minted' condition more explicitly.

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

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

Only parameter checkout_id is mentioned implicitly as 'by checkout_id'. Schema coverage is 0%, and description adds no format or constraints beyond the schema. For a single parameter, more detail would help.

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 polls a checkout by ID and lists returned fields (status, items, customer details, payment_url). It distinguishes from siblings by mentioning specific use cases with complete_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?

Explicitly states when to use: to verify customer details before complete_checkout or retrieve payment_url after. Lacks explicit 'when not to use' but provides clear 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?

Discloses production time (5 working days, holiday exclusion), return fields, and the caveat about delivery date variability. All relevant behavioral details are provided.

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 at ~4 sentences, front-loaded with purpose, 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 low complexity and no output schema, the description provides all necessary context: purpose, return values, and usage guidance.

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

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

Schema coverage is 100% and the description does not add meaningful info beyond the schema's default explanation, so a baseline 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 the tool estimates dispatch time for a new order, specifying the return fields and distinguishing from siblings by focusing on delivery estimation.

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 when to use ('when a customer asks when will it arrive?') and provides a clear usage boundary (do not quote final delivery date).

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?

With no annotations provided, the description carries full burden. It discloses the retrieval nature, required email match for security, and return fields (payment status, production status, dispatch date). It does not mention error handling or rate limits, but for a simple read-only tool, coverage is good.

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 and parameters, second adds return value details. No redundant text; every word is informative. Front-loaded with the 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?

The description covers the tool's purpose, key parameters, and return values adequately. Given the low complexity (2 required params, no output schema), it lacks only minor details like pagination or error scenarios, but overall it is sufficient.

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 0%, so the description must compensate. It explains that order_id identifies the order and customer_email serves as soft-auth requiring exact match. This adds significant meaning beyond the schema, though it could also specify expected format (e.g., UUID).

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 explicitly states 'Retrieve a confirmed order's status, items, and payment details', providing a specific verb and resource. It clearly distinguishes from sibling tools like create_order or get_cart by specifying it is for confirmed orders.

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 customer_email is required for soft-auth and must match exactly, which is a key usage constraint. However, it does not explicitly compare to alternative retrieval tools (e.g., get_checkout) or state when not to use this tool. The usage context is implied but not fully 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?

No annotations provided, so description carries full burden. It discloses return values (specific processors and capabilities) and mentions downstream use in create_checkout and complete_checkout. No side effects are mentioned, but it's a read-only listing with no destructive hints needed.

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: purpose, specific returns, and usage guidance including downstream connection. No redundancy, front-loaded with key 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?

Given only one optional parameter, no output schema, and no annotations, the description covers purpose, usage, return specifics, and downstream impact completely. The agent can correctly select and invoke this tool.

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

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

Schema coverage is 100% with one optional parameter described both in schema and description. The description merely restates the schema's 'Optional. For future per-handler limit filtering.' without adding new semantics, so baseline 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 the tool lists available payment processors and their capabilities, explicitly naming Yoco and Ozow with details. This differentiates it from sibling tools like create_checkout or complete_checkout that use the result.

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 guidance: 'Call when the customer asks how can I pay? or before presenting options.' While no explicit alternatives are given, the usage context is well-defined and sufficient for an agent to decide when to invoke this 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?

With no annotations, the description carries full burden. It states returns include unit_price_zar and total_price_zar inclusive of VAT, which is helpful. However, it does not explicitly confirm no side-effects (read-only) or mention any rate limits or error conditions.

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 provides prerequisites and next step. No unnecessary words, front-loaded, 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?

The description covers purpose, prerequisites, returns, and subsequent step. Given no output schema, it includes return fields. However, it could mention how optional parameters (finish, province) affect pricing or any error scenarios, 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 description coverage is 100%, so the description adds minimal value beyond reinforcing required parameters and their source. It provides no new semantics beyond what's in the schema, thus baseline 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 retrieves an exact ZAR price for a product at specific dimensions. It specifies the verb 'get', the resource 'price', and the required dimensions, distinguishing it from sibling tools like search_products or configure_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 outlines prerequisites (product_id from search_products or lookup_catalog, width_mm, height_mm) and advises the next step (call configure_product). It lacks explicit when-not-to-use or alternatives, but the sequential guidance 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?

Despite no annotations, the description fully discloses that it returns product details, colours with stock status, materials, features, and dimensions. It implies a read-only operation.

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: the first specifies purpose and output, the second provides usage context. No extraneous 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?

Fully captures what the tool returns and workflow context, with no output schema needed due to the descriptive listing of return fields.

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?

Provides concrete examples of product IDs (e.g., roller-blockout, venetian-25mm-aluwood) beyond the schema's generic string type, compensating for 0% schema coverage.

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 ('Fetch complete details') and resource ('one product by id'), and distinguishes it from siblings like check_colour_stock and configure_product by placing it in a workflow.

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 before configure_product to confirm a colour exists and is in stock before committing,' providing clear when-to-use guidance and indirectly indicating 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?

No annotations provided, so description carries full burden. Discloses return format (product_id with rationale) and special routing for security. Does not explicitly state non-destructive nature, auth needs, or rate limits, but the read-only nature is implied. Could be more explicit but covers key behavioral aspects.

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 core purpose, followed by optional params and return value. Every sentence adds value with no redundancy. Well-structured for quick comprehension.

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?

No output schema, so description explains return value (product_id with rationale). Covers special routing for security concern. Lacks explicit error handling or behavior for invalid inputs, but given the simple recommendation context, it is sufficiently complete. Could mention what happens if security concern is given but customer is not Garden Route.

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 0%, so description fully compensates. Lists all enum values for primary_concern, explains optional params (room with examples, location, budget, aesthetic), and provides context for the security concern special case. Adds significant meaning beyond raw 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 tool translates a customer's primary concern into a product recommendation, with specific verb and resource. Distinguishes from siblings by noting return value (product_id with rationale) and suggesting next steps (get_price or configure_product). Also specifies a special routing for security concern, differentiating behavior.

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 describes when to use (when a customer has a primary concern), lists allowed values for primary_concern, explains optional narrowing parameters, and gives explicit next steps. Also provides exclusion for security concern routing to brochure MCP for Garden Route customers, serving as a when-not-to-use guideline.

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?

No annotations are provided, so the description carries full burden. It explains the routing logic based on location, which is a key behavioral detail. It does not mention side effects or error handling, but for a non-destructive link generation tool, the transparency is good.

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 purpose, followed by routing details and usage guidance. Every sentence adds value 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?

For a simple tool with conditional routing, the description covers purpose, routing logic, and usage conditions. It does not specify the return format (e.g., whether it returns a URL string or markdown), but that is a minor gap.

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 75%, and the description adds context beyond the schema, particularly how the 'location' parameter drives routing. However, it does not elaborate on 'message' or 'customer_name' beyond their 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 states 'Generate a pre-filled WhatsApp deep link to hand the customer off to the right contact.' It uses a specific verb (generate) and resource (deep link), and distinguishes from sibling tools by focusing on handoff to human assistance.

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: 'when the customer prefers human assistance or when self-serve checkout isn't appropriate.' This implies when not to use, but does not name specific alternative tools, though siblings like complete_checkout and submit_enquiry provide 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?

Despite no annotations, description notes it 'Returns matching products with id and product_url', indicating read-only behavior and output structure. Lacks details on error handling, parameter combination logic, or limits, but covers core behavior adequately.

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

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

Three sentences, each adding distinct value: purpose+parameters, usage context, sibling differentiation. No redundant information. Front-loaded with 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?

Covers purpose, parameters, usage, and output structure. Missing details on return set (e.g., pagination, ordering) and parameter optionality. Good for moderate complexity but could be more thorough given lack of output schema and annotations.

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?

Lists all four parameters with category enum values explicitly. With only 25% schema description coverage, the description adds value but does not fully compensate: colour name format, measurement units, and parameter optionality are not detailed.

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 a structured catalogue filter with specific parameters (category, colour, max_width_mm, max_height_mm) and distinguishes from sibling search_catalog. The verb 'narrow by' and resource 'catalogue' are explicit.

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 'Ideal when the customer has stated a blind type' and directs to 'Use search_catalog for open-ended natural language queries'. Provides clear context for when to use this tool versus 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?

With no annotations provided, the description must disclose behavioral traits. It states the output is a pre-filled WhatsApp link, but omits whether the claim is stored, if verification happens automatically, any side effects, or authorization requirements. The focus is on eligibility rather than 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 four sentences with no wasted words. It front-loads the purpose, lists exclusions, and states requirements. Structure is clear and 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?

Given no output schema or annotations, the description covers purpose, usage, exclusions, required inputs, and output type. However, it lacks details on error handling, verification process, and what happens after submission, leaving some 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 each parameter is documented. The description adds minimal meaning beyond the schema, mainly restating required parameters. Baseline 3 is appropriate as the schema does the heavy lifting.

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 ('Submit a price match claim'), the resource ('a price match claim for blinds'), and the condition ('when the customer has found the same blind cheaper elsewhere'). It distinguishes from sibling tools, as no other tool handles price matching.

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 when to use the tool ('when the customer has found the same blind cheaper elsewhere') and provides exclusions ('Not applicable to: Blinds Direct, clearance or flash-sale prices, or out-of-stock items'). It implies usage context but does not mention 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?

With no annotations, the description carries full burden. It discloses that swatches only ship with the order and are capped at 5, but omits preconditions (e.g., existence of an order) and does not explain error behavior 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?

Three concise sentences with no fluff. Front-loaded with purpose, then constraints, then customer handling. 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 6 parameters, no output schema, and no annotations, the description covers main behavior but lacks details on preconditions (e.g., an existing order), response format, or error handling. Could be more 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 67%, and the description adds valuable context: customer_phone is used as WhatsApp number, product_interest provides examples, and swatch_codes includes the max 5 cap. However, customer_name and customer_email still lack description, and format of swatch_codes is not detailed.

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 registers up to 5 colour swatches to be dispatched with the customer's order. It distinguishes itself from potential confusion about standalone samples, and its purpose is distinct from sibling tools like checkout or product configuration.

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 (when customer wants swatches) and what to do if asked before ordering (direct to place order first). It implies not to use for standalone requests, but does not name alternative tools explicitly.

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?

No annotations provided, but description covers what the tool does and what it returns. It lacks mention of pagination or result limits, but for a search tool this is sufficient.

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, all essential. Front-loaded with main purpose, then examples, then follow-up. 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?

For a simple search tool with one parameter and no output schema, the description is complete: explains input, examples, return fields, and next steps. No obvious 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?

Only one parameter 'query' with schema description 'Free-text query'. The tool description adds concrete examples ('blockout', 'venetian') and clarifies the return fields, adding value 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 it's for free-text search across the full catalogue, gives concrete examples ('blockout for bedroom', 'wood venetian'), lists returned fields, and distinguishes from sibling tool 'lookup_catalog'.

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 when to use (open/free-text queries) and when not (for filtering by category, colour, dimensions → use lookup_catalog). Also provides follow-up guidance: pass returned id to get_product or get_price.

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?

No annotations are provided, so the description carries the full burden. It explains that the tool returns product_id, name, description, features, and in-stock colour count. It does not mention destructive actions, which is appropriate for a search tool. 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?

Three sentences with no waste: first sentence gives usage guideline, second sentence lists filters and return fields, third sentence suggests next steps. Essential information is front-loaded and well-organized.

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 output schema, the description adequately explains what the tool returns (product_id, name, description, features, colour count). It also covers the effect of the province parameter. For a search tool with 5 parameters, this is complete and actionable.

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 explaining that filters include blind type (with examples: roller, venetian, etc.), colour name (partial match), and maximum dimensions. It also contextualizes the province parameter (Garden Route vs. other locations).

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: 'Use when the customer hasn't specified a product ID yet.' It specifies filters (blind type, colour, dimensions) and distinguishes it from sibling tools like get_product which requires an ID.

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 when to use (customer hasn't specified product ID) and provides next steps (pass product_id to get_price or configure_product). It implies when not to use (if product ID known, use get_product instead) but doesn't explicitly state exclusions.

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?

With no annotations, the description must disclose behavioral traits. It reveals that the tool is legacy, requires Bearer token, and expects async response within 24 hours. However, it doesn't specify if the tool is read-only or destructive, or what the success response looks like, leaving minor gaps.

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

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

Three sentences, each earning its place: context/alternative, usage condition, and requirements/timeline. No redundancy, front-loaded with the most important comparison.

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 5 parameters, nested object, and no output schema, the description covers purpose, usage, auth, input guidance, and response time. It lacks explicit mention of return value or error handling, but for a submit tool this is acceptable.

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 describes all parameters, so baseline is 3. The description adds value by instructing to pass a 'configure_product output' for the product_config parameter, clarifying its origin. This is helpful beyond the schema's field 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 states the tool's purpose: submitting an enquiry for a sales team follow-up. It distinguishes from siblings by explicitly contrasting the preferred UCP checkout flow and specifying that this tool is only for non-payment follow-up.

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 on when to use the tool ('customer wants a sales team follow-up by email rather than paying online') and when not to (prefer the UCP flow for credentialless checkout). It also mentions the auth requirement and response timeline.

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?

No annotations provided, so description carries full burden. It discloses mutation behavior, operation effects (appending, dropping, replacing, emptying), and merging of customer details. Does not detail side effects like item validation or pricing changes.

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 covering all key info: operations, customer merge, constraint, and follow-up. No wasted words, front-loaded with 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?

Covers operation types, parameter roles, and a usage constraint. Suggests follow-up. Lacks details on nested object structures and return behavior, but no 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 coverage is only 20% (only indices documented). Description adds meaning to op (enum values explained), items (used with add/set), indices (0-based removal), and customer (merging details). Does not detail structure of items or customer objects.

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 modifies an open cart before checkout, and specifies operations (add, remove, set, clear). It is distinct from sibling tools like create_cart or get_cart, though could explicitly contrast with them.

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?

Includes when to use (before checkout) and a constraint (cannot modify if checkout in progress). Advises to call get_cart afterwards. Does not explicitly mention alternatives like create_cart for new carts.

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?

With no annotations provided, the description carries full burden. It discloses return value (updated checkout state) and error conditions (paid/cancelled). Missing details like idempotency, partial update behavior, or access requirements, but covers the main behavioral traits.

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 extraneous information. Front-loaded with the primary purpose and key conditions. 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 3 parameters (one nested object) and no output schema or annotations, the description covers input fields, behavior, and return. Lacks explicit statement that updates are partial (only specified fields modified), but overall provides sufficient context for an update 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 description coverage is 0%, so description must compensate. It explains that 'customer' contains name, email, phone, address and that 'payment_method' has enum values yoco/ozow. However, it does not detail the structure of the customer object (e.g., required sub-fields, nesting). Adds some value but incomplete.

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 'Correct' and resource 'checkout', lists specific fields (name, email, phone, address) and payment method options (yoco, ozow). It also distinguishes itself from the sibling tool 'complete_checkout' by indicating it should be called before it.

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 directs to use this tool on an unpaid checkout before calling complete_checkout, and warns of errors if the checkout is paid or cancelled. However, it does not mention alternatives or exclusions relative to other sibling tools like 'update_cart'.

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