Custom Blinds Shop

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

With no annotations, the description must fully disclose behavior. It only says 'discard' without detailing side effects, reversibility, or permissions. A destructive mutation tool requires more 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?

The description is very short at two sentences, but the first sentence is jargon-filled and nearly useless. While concise, it sacrifices necessary detail for brevity.

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 it is a mutation tool with no output schema and one parameter, the description lacks critical context such as prerequisites, return behavior, or implications of discarding a cart. Sibling tools like get_cart and update_cart provide contrasting operations but are not referenced.

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 0% description coverage and the description fails to mention the single parameter (cart_id). The description adds no meaning beyond the schema's type and name.

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 'Discard a cart' clearly identifies the action and resource, distinguishing it from siblings like create_cart or get_cart. However, the preceding jargon 'UCP 2026-04-08 spec method' adds noise and slightly reduces clarity.

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 is provided on when to use this tool versus alternatives such as cancel_checkout or update_cart. The description lacks context for appropriate usage or 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?

No annotations are provided, so the description must disclose behaviors. It notes the checkout must be unpaid but omits details like idempotency, state changes, error handling for paid checkouts, or permission requirements.

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

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

The description is a single sentence, very concise. However, the phrase 'UCP 2026-04-08 spec method' is potentially unnecessary and may not help an agent. Still, it is efficient and 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?

With only one required parameter, no output schema, and no annotations, the description is too minimal. It lacks details on return values, error conditions, prerequisites (e.g., checkout must be unpaid), and when to avoid using 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?

The input schema has 0% coverage (no description for any parameter). The description does not mention the parameter checkout_id or explain its meaning, format, or constraints, so it adds no 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 'Cancel a checkout that has not yet been paid.' This provides a specific verb (cancel) and resource (checkout) with a condition, distinguishing it from siblings like complete_checkout or update_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?

No guidance on when to use this tool versus alternatives (e.g., cancel_cart, update_checkout). The description mentions 'UCP 2026-04-08 spec method' but does not provide practical usage context or exclusion conditions.

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

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

Describes returns: in_stock boolean, restock date, and up to 5 alternative colours. Mentions 'real-time', indicating fresh data. With no annotations, this provides sufficient behavioral context for a 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?

Single sentence, 24 words, front-loaded with 'Real-time per-colour stock check'. No extraneous info.

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 covers key return fields: boolean, restock date, alternative colours. Lacks error conditions or edge cases, but sufficient for a simple stock check 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 has 0% description coverage. Description indirectly references 'colour_name' via 'per-colour' but does not explicitly describe the parameters or add meaning beyond their names. Adequate for self-explanatory names but lacks elaboration.

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 'Real-time per-colour stock check', specifying the verb (check) and resource (colour stock). Differentiates from sibling tools like get_product which returns general product info.

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?

Implies usage for checking stock of a specific product colour, but does not explicitly state when to use vs alternatives like search_products or get_product. No exclusionary 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?

No annotations provided, but description discloses the return of payment_url and the effect on order status via webhook, though it omits authentication or error details.

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-load the key action, with no wasteful words.

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

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

Given the tool's simplicity and lack of output schema, description covers the core behavior and return value, though it lacks prerequisites or error 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 50%; description adds context for payment_method (override functionality) but does not explain checkout_id beyond the schema's requirements.

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 mints a payment link via a chosen payment_method and returns a payment_url, distinguishing it from sibling tools like create_checkout or 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?

Description implies usage after checkout creation and before payment completion but lacks explicit when-to-use or when-to-avoid guidance compared to 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 mentions the tool calculates price and returns a summary, but it does not disclose side effects (e.g., whether it stores the configuration), authentication needs, or error behaviors. The lack of transparency for a mutation-like tool is a gap.

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

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

The description is a single sentence that is front-loaded with the action and key inputs. It contains no unnecessary words and efficiently communicates the tool's purpose and output.

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

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

For a tool with 8 parameters and no output schema, the description provides a high-level overview but lacks details on error conditions, return value structure, or prerequisites (e.g., product_id from search_products). It is minimally adequate but could be more helpful 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%, so baseline is 3. The description paraphrases the parameters (colour, dimensions, mount type) but adds no additional meaning beyond the schema's own descriptions. For example, it does not clarify the 'province' parameter's conditional logic or the 'finish' parameter's scope.

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 'Build' and the resource 'blind configuration', listing key inputs (product details, colour, dimensions, mount type, calculated price) and the output (configuration summary ready for ordering). It distinguishes itself from siblings like update_cart or create_order by focusing on configuration before ordering.

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

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

The description implies this tool is for building a configuration before ordering, but it does not explicitly state when to use it versus alternatives like create_cart or get_price. It lacks exclusions or context about prerequisite steps (e.g., product selection via search_products).

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 return of cart_id with a 24-hour TTL and optional seeding, but does not mention side effects, multiple cart allowances, or required permissions.

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 very concise with three short sentences, each providing distinct information: spec reference, core function, optional behavior, and return value with TTL. No unnecessary words.

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

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

Given no output schema, the description specifies return value and TTL. However, it does not detail response format or how to use the cart_id. The statement 'UCP 2026-04-08 spec method' adds context but is cryptic. Sibling tools provide context for cart flow.

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% with both parameters having descriptions. The description reinforces that they are optional but adds minimal extra meaning beyond the schema. With high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states 'Create a working cart' with a specific verb and resource. It distinguishes from siblings like cancel_cart, get_cart, update_cart by specifying creation, and mentions optional seeding of items and customer details.

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

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

The description implies usage as the first step in cart operations but does not explicitly state when to use this vs alternatives like create_checkout or update_cart. No exclusions or 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?

Discloses that it does not mint payment link, a key behavioral trait. Without annotations, this adds value, though more details on error handling or idempotency could improve 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?

Two sentences, front-loaded with spec method, 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 4 parameters, nested objects, and no output schema, the description is adequate but could mention return format more precisely and potential failure modes.

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%, with descriptions for cart_id and payment_method. Description clarifies that items or cart_id are alternatives, but doesn't detail the structure of items array or customer object, thus adding only moderate value 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?

The description clearly states it creates a checkout from cart_id or inline items + customer, returns checkout_id, and distinguishes from sibling complete_checkout. Specific verb and resource.

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 that it does not mint payment link and directs to call complete_checkout for that, providing clear when-not and alternative.

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 provides basic behavioral insight: creates a draft order, returns a payment link, requires authentication. It does not disclose side effects, draft lifetime, or failure handling, but it covers the core function.

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 short sentences, front-loading the main purpose. No redundant or vague text; every word adds value.

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

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

Given no output schema, the description mentions returning a payment link but does not detail the full response structure or states (e.g., error handling). It is complete enough for a basic draft order creation but lacks detail on subsequent steps.

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 does not add parameter-specific meaning beyond what the schema already provides, such as 'items array' or 'customer details'.

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

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

The description clearly states the tool creates a draft order and returns a Yoco payment link, using a specific verb-resource pair. It distinguishes from siblings like create_cart and create_checkout by specifying the outcome.

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

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

The description implies usage for creating a draft order with payment link, but does not explicitly state when to use this vs alternatives like create_checkout or complete_checkout. It only mentions API key authentication as a requirement, but no guidance on exclusion.

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. Description describes it as returning a URL, implying a read-only operation, but does not disclose potential side effects, authentication requirements, or rate limits. Adequate but not thorough.

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 adding value. Front-loaded with purpose, no unnecessary 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?

For a simple tool returning a URL with two optional parameters, the description covers the main use cases and parameter roles. No output schema needed as return is self-explanatory.

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 description adds context beyond schema by explaining what the 'mode' options do (measure vs visualize), enriching understanding.

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 returns a URL for the AR measurement tool and product visualizer, explaining what each does. It distinguishes itself from siblings like get_product or get_price by focusing on AR/visualization.

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 this when a customer wants to measure, visualize, or see how it looks before ordering.' Provides clear context on when to use, though it does not mention when not to or 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, the description must disclose behavioral traits but only mentions return values. It omits side effects, authorization needs, or limitations, leaving agents underinformed.

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, but the first sentence 'UCP 2026-04-08 spec method' is boilerplate that provides no actionable value, reducing conciseness.

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 partialy covers return values (contents, total, customer details) but lacks structural details. Adequate for a simple retrieval tool but not comprehensive.

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 'cart_id' is documented in schema but the description adds no extra meaning (e.g., format, required flag, or how to obtain it).

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

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

The description clearly states the tool returns cart contents, total, and customer details. The name 'get_cart' is self-explanatory and distinguishes from sibling tools like create_cart or update_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?

No explicit guidance on when to use this tool versus alternatives like get_checkout or get_order. The description lacks context for appropriate invocation.

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 bears full burden for behavioral disclosure. It hints at a read operation but omits details like idempotency, error handling, required permissions, or side effects. The opaque 'UCP 2026-04-08 spec method' adds no behavioral value.

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 very short (12 words) but wastes the first sentence on an irrelevant spec reference. It lacks structure and omits critical information about parameters and usage, making it more under-specified than 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 the lack of output schema and annotations, the description should cover return fields, parameter meaning, and error conditions. It only partially lists return fields and ignores the required parameter, leaving significant gaps for the 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?

The input schema has 0% description coverage and the tool description does not explain the 'checkout_id' parameter. The agent receives no semantic context beyond the schema's type and required status, which is insufficient 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 states 'Return checkout state, items, customer, payment status', clearly indicating a read operation on checkout resources. This distinguishes it from sibling tools like create_checkout or cancel_checkout, though it does not explicitly mention the read-only nature.

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 is provided on when to use this tool versus alternatives (e.g., update_checkout, cancel_checkout). There is no mention of prerequisites or conditions like needing an existing checkout 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?

With no annotations, the description fully discloses behavioral traits: production takes 5 working days excluding SA public holidays, delivery time varies, and the output includes dispatch date, production days, and a customer-safe summary. This provides sufficient transparency for an AI agent.

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

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

The description is three concise sentences, front-loading the purpose and adding essential details without redundancy. Every sentence contributes value.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description covers all needed aspects: purpose, production rules, delivery caveat, and return values. It is fully 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 a single parameter description. The description adds context about the date's role but does not enhance parameter semantics beyond what the schema already provides. 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 calculates the estimated dispatch date for an order, specifying the verb 'calculate' and the resource 'dispatch date'. It distinguishes itself from sibling tools by focusing on dispatch estimation, not other order-related operations.

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 a clear use case (calculate dispatch date) and includes a critical warning not to quote a specific delivery ETA. However, it does not mention when not to use this tool or suggest alternative tools for delivery estimates.

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 soft-auth requirement but does not confirm that the tool is read-only or describe any side effects, rate limits, or other 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?

The description is two sentences (26 words), directly front-loading the core purpose and key constraint. Every sentence earns its place 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?

The tool has no output schema and no annotations. The description covers purpose and auth, but lacks detail on return value structure, error conditions, or safety disclaimers. It is adequate but not comprehensive.

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 the description must compensate. It explains that order_id is the lookup key and customer_email is required for soft-auth matching, adding meaningful context beyond the bare schema definitions.

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

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

The description clearly states 'Look up a placed order by order_id', specifying the verb (look up) and resource (placed order). It distinguishes from sibling tools like create_order, and the identifier is explicitly named.

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

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

The description implies usage context by requiring customer_email for soft-auth, but it does not explicitly state when or when not to use this tool versus alternatives like get_checkout or get_cart. No alternative tools are mentioned.

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 accurately conveys a read-only operation that returns capabilities. It does not disclose potential side effects (none expected) or authentication needs, but the purpose 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?

Two sentences: one defining the tool's output, one indicating usage context. Every word adds value, no redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers what an agent needs to know. Could mention the return structure, but not required.

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

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

Schema coverage is 100% for the single optional parameter. The description ('Optional. For future per-handler limit filtering') adds context about future use, but does not significantly enhance schema information.

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

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

The description clearly states it returns available payment handlers and their capabilities, naming specific handlers (Yoco card, Ozow instant EFT). This distinguishes it from siblings like create_checkout or get_cart, which focus on different aspects of the checkout flow.

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

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

Explicitly states to use before complete_checkout to inform the customer of options, providing clear context. It does not mention when not to use or alternatives, but the sibling list makes it evident.

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 it returns unit price and total in ZAR including VAT, but doesn't detail required auth, rate limits, or whether the price is calculated or cached. Adequate for a simple calculator.

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, 22 words, front-loaded with action, no redundancy.

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

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

Does not mention optional parameters (finish, province, quantity) or their effect. Missing context about province affecting contact info. Incomplete for a 6-param 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 covers all 6 parameters with descriptions. The tool description adds context that prices are in ZAR and include VAT, but doesn't add new meaning to specific parameters 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?

The description clearly states the tool calculates an instant price quote for a blind product based on width and height, distinguishing it from siblings like get_product (product details) or create_checkout (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?

No guidance on when to use this tool over siblings like configure_product or request_price_match. Lacks explicit context about alternatives or 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?

No annotations are provided, so the description carries the full burden. It discloses the output fields (colours, materials, etc.), which implies a read operation, but does not mention authentication, rate limits, or any side effects. The described behavior is clear but incomplete for a tool without 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 one sentence and efficiently conveys the tool's purpose and output. The opening 'UCP 2026-04-08 spec method' adds a technical detail that may not be necessary for an AI agent, but overall it is 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 the simple input (one parameter) and no output schema, the description lists the key return fields (colours, materials, features, pricing notes, schema URL), making it fairly complete. However, it lacks guidance on parameter value and usage 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?

The only parameter is product_id of type string, but the description does not clarify its format, source, or constraints. With 0% schema description coverage, the description should compensate by explaining the parameter, but it only describes the return value.

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

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

The description clearly states the verb 'Returns' and the resource 'full details for a single product', listing specific fields like colours, materials, features, pricing notes, and schema URL. It distinguishes this from sibling tools such as search_products or get_price.

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 'UCP 2026-04-08 spec method', which hints at the context, but does not explicitly state when to use this tool over alternatives or when not to use it. The purpose is implicit: use when you need full details for a specific product 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?

Discloses deterministic mapping and special handling for security, but lacks details on behavior for missing optional parameters and does not describe output format. With no annotations, description should cover more.

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 efficiently convey purpose and key behavior. Could be slightly more structured but is front-loaded and 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?

No output schema means description should explain return values, which it does not. Only covers 3 of 5 parameters, leaving gaps for location and aesthetic. Incomplete for agent to reliably 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?

Adds meaning by explaining primary_concern enum and special case for security, but only mentions 3 of 5 parameters (room, budget, primary_concern) and does not clarify location or aesthetic.

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 recommends Custom Blinds products based on primary concern, room, and budget. Differentiates from sibling tools like search_products by focusing on concerns and deterministic mapping.

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 guidance for security concern (hands off to brochure) and mentions deterministic mapping. However, does not explicitly state when to use this tool versus alternatives like search_products.

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 the routing logic and phone numbers. It could mention if the link opens directly or requires user action, but the core behavior is transparent.

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?

A single sentence that is front-loaded with the purpose and includes specific details. Every word is earned.

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, no output schema), the description covers the core logic well. It does not describe the return format or error cases, but for a link generator, it is sufficiently 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 75% (3 of 4 parameters described). The description adds context for the location parameter's role in routing but does not elaborate on customer_name or product_context beyond the schema. Baseline 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 generates a pre-filled WhatsApp link routed to a specific contact based on location. It is a specific verb+resource (generate link) and distinguishes itself from sibling tools like get_cart or create_order.

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

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

The description explicitly provides routing logic: use Duncan Kane for Garden Route, shop line otherwise. This gives clear context for when to use each number, though it does not explicitly state when not to use the tool or compare to 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 provided, so description carries full burden. Only states it's a 'UCP spec method' but does not disclose any behavioral traits like read-only, auth needs, 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 concise sentences with no redundancy. Front-loaded with spec reference and clear action statement.

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; description does not explain return format, default behavior when no filters applied, pagination, or limits. Incomplete for a tool with 4 parameters.

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 low (25%). Description lists the parameter categories but does not explain 'dimensions' clearly (maps to max_width_mm and max_height_mm) or provide constraints for colour. Partially compensates but not fully.

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 'filter' and the resource 'catalogue', and distinguishes from sibling 'search_catalog' by specifying structured criteria vs free text.

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: use for structured criteria (category, colour, dimensions), use search_catalog for free text. Provides clear when-to-use and 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?

No annotations are provided, so the description must cover behavioral traits. It states the return (WhatsApp link and confirmation) and what it does not apply to. However, it does not disclose whether it creates a record, requires authentication, or has any rate limits. The mutation aspect ('submit') is implied but not elaborated.

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: first states action, second explains conditions, third lists exclusions. No redundant information, highly efficient and well-structured.

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

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

Given the complexity (8 parameters, no output schema), the description covers purpose, conditions, exclusions, and return value. It lacks details on post-submission behavior (e.g., claim processing) but is sufficient for an AI agent to understand the tool's role among 25+ sibling tools.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by specifying that dimensions must match (implicitly linking width_mm/height_mm to the product) but does not elaborate on parameters like competitor_name vs. competitor_url 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 'Submit a price match claim on behalf of a customer' and specifies the conditions (authorized South African retailer, same product/dimensions/specs). It also lists exclusions, making the purpose very specific and differentiated from sibling 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?

The description provides clear context for when to use (customer price match request) and explicitly lists exclusions (e.g., 'Does NOT apply to Blinds Direct, clearance items, flash sales, or out-of-stock items'). It does not name alternative tools but the exclusions serve as 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?

Given no annotations, the description discloses key behaviors: swatches are not standalone, they are sent with order, cap of 5. However, it does not mention side effects (e.g., whether this modifies an existing cart/order) or auth requirements.

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

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

Three sentences, no wasted words. First sentence states the action, second explains constraint, third gives guidance. Ideal structure for agent consumption.

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, constraints, and usage guidance adequately for a registration tool. Missing details about return value or error handling, but output schema is absent so less burden. Overall complete enough for safe 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?

Schema coverage is 67% (most parameters have descriptions), but the description adds no additional parameter-level detail beyond what schema provides. Some parameters like customer_name and customer_email lack description in both schema and 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?

The description clearly states the action ('Register a swatch request against an order') and distinguishes from standalone swatch requests, making it easy to understand what the tool does.

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 swatches are dispatched at order placement, caps at 5, and instructs not to promise standalone delivery, guiding the agent to direct customers to order first. This provides clear when-to-use and when-not-to-use 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?

No annotations are provided, so the description carries full burden. It discloses return fields but omits details like pagination, limits, or read-only behavior. Adequate but not comprehensive.

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 unnecessary words. The first sentence ('UCP 2026-04-08 spec method') is cryptic but brief; the second is clear. Generally well-structured.

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

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

For a simple search tool with one parameter and no output schema, the description adequately outlines functionality and return fields. However, missing usage guidance and behavioral limitations reduce completeness.

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

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

Schema coverage is 100% with a clear parameter description. The tool description adds little beyond the schema, only restating 'free-text query' with examples. 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 searches the Custom Blinds catalogue by free-text query and returns specific fields. However, it does not differentiate from sibling tools like search_products or lookup_catalog, leaving potential 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?

No guidance on when to use this tool versus alternatives. Sibling tools exist for similar purposes (e.g., search_products, lookup_catalog, get_product), but the description provides no context for choice.

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 indicates a read operation and lists outputs, but omits details like idempotency or performance characteristics. Adequate but not exhaustive.

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

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

Three concise sentences, no wasted words. Front-loaded with action and scope, each sentence adds distinct value. Excellent structure.

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

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

With 5 optional parameters and no output schema, description covers key aspects: filters, return fields, and province special case. Lacks mention of pagination or case sensitivity but sufficient 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?

Schema coverage is 100%, and description adds context beyond schema descriptions, e.g., explaining province parameter's special behavior. Provides clear mapping between parameters and their use.

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 'Search the Custom Blinds product catalogue' and lists specific filters and return fields. It is distinct from siblings like 'search_catalog' and 'get_product', making the tool's purpose unambiguous.

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 explains when to use the tool: to search the blind catalogue with filters. However, it does not explicitly exclude other cases or mention alternatives, which would strengthen 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?

No annotations are provided, so the description must disclose behavior. It states that it sends an email and requires API key authentication. It does not mention side effects like record creation or idempotency, but the core action is transparent.

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

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

The description is three concise sentences with no unnecessary words. It front-loads the key action and includes essential context efficiently.

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 explains the action and authentication but does not cover return values or what happens after submission (e.g., confirmation). It also does not reference related tools like configure_product, which might be expected given the product_config object.

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% description coverage, so the baseline is 3. The description mentions 'product configuration and customer message' but does not add significant meaning beyond the schema's own 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 action ('submit a product enquiry'), the recipient ('Custom Blinds sales team'), and the content (product configuration and customer message). It effectively distinguishes from sibling tools like create_order or request_swatch.

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

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

The description implies usage for customer enquiries and mentions authentication. However, it does not explicitly differentiate from alternatives like create_order for purchases, though the tool name and context make it reasonably 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?

No annotations are present, so the description bears full responsibility. It mentions modification and customer merging but lacks details on side effects, permissions, or data persistence beyond stating the 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?

The description is three sentences and to the point, but the first sentence referencing a spec method is unnecessary and adds noise.

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

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

Given the tool has 5 parameters, no output schema, and many sibling tools, the description is overly brief. It fails to explain return values, error conditions, or typical usage scenarios.

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 description adds meaning for op (enum values) and customer (merge behavior) beyond the schema. However, schema description coverage is only 20% and the items array is left undocumented; the indices parameter is described in the schema.

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

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

The description clearly states the tool modifies cart contents and enumerates specific operations (add, remove, set, clear), which differentiates it from sibling tools like create_cart or get_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?

The description provides no guidance on when to use this tool versus alternatives (e.g., when to create vs update a cart) nor any conditions or prerequisites.

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 key constraint (no updates to paid checkouts) but lacks info on idempotency, side effects, or success/error responses. Minimal but adequate for core 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?

Two sentences, no fluff, front-loaded with purpose. Every word 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 mutation tool with no annotations or output schema, description provides essential usage rules but omits parameter details and operational outcomes. Adequate but could be richer.

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%, description mentions customer and payment_method but not checkout_id or nested structure. Insufficiently compensates for undocumented 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?

Clearly states verb 'Update' and resource 'checkout', specifying modifiable fields (customer details, payment_method) and constraint (before completion). Distinguishes from siblings like cancel_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?

Provides explicit condition 'before completion' and exclusion 'Cannot update a paid checkout', guiding when to use. No mention of alternatives but context is clear.

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