Custom Blinds Shop

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

With no annotations, the description carries full burden and does well: it discloses permanence ('Permanently delete', 'Irreversible'), side-effect isolation ('Has no effect on any checkout or paid order'), and recovery path ('create a new cart to restart'). This goes well beyond basic delete semantics.

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 purposeful: action, usage context, and side-effect/irreversibility caveat. No filler or redundant phrasing, and the key action is front-loaded.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description covers purpose, usage, behavior, and irreversibility. It is sufficient for an agent to correctly select and invoke the tool without additional context.

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

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

Schema coverage is 0% and the description only mentions cart_id in passing ('by cart_id'). It adds that cart_id identifies the target cart, but does not specify format, source, or validation. For a single simple parameter, this is adequate but not compensatory enough for a higher score.

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

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

The description clearly states 'Permanently delete a cart by cart_id' with a specific verb and resource. It distinguishes from siblings like cancel_checkout by focusing on cart deletion, and the 'permanently' modifier sets clear expectations of destructive action.

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

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

The description explicitly states when to use it: 'Use when the customer abandons the session or wants to start over.' It also clarifies a boundary ('Has no effect on any checkout or paid order'), but does not explicitly name alternative tools like cancel_checkout for checkout-related cancellations, so it falls just short of a full 5.

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 discloses key behaviors: release of checkout_id and no effect on confirmed orders. It implies the operation is only for unpaid checkouts. Some missing details (idempotency, errors) but core side effects are covered.

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 value: action, usage context, caveat, and restart advice. No filler or repetition. Perfectly concise.

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

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

For a simple one-parameter cancellation tool, the description covers what it does, when to use it, its side effects, and what to do next. No output schema needed, and the behavior is sufficiently specified.

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

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

The schema only lists checkout_id as a string with no description. The tool description explains that the checkout_id is the one from create_checkout and that it becomes released, adding context beyond the bare 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 aborts an unpaid checkout and releases its checkout_id. This specific verb+resource distinguishes it from siblings like cancel_cart (cancels cart) and complete_checkout (finishes payment).

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

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

Explicitly says when to use: 'after create_checkout but before completing payment.' Also gives exclusion: 'Has no effect on orders already confirmed by webhook,' and provides restart guidance. This fully covers when 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?

With no annotations, the description carries the full burden. It discloses the return shape (in_stock boolean, expected_restock_date, up to 5 alternatives) and frames the tool as a read-only verification via 'Verify' and 'Returns'. It stops short of error handling details, but the safety profile is evident.

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 states purpose, the second covers output and usage triggers. Every word earns its place, and the description is well 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?

For a two-parameter read-only tool with no output schema, the description covers return values, usage context, and practical reason for existing. It lacks error behavior, but given the small scope, it is nearly 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 0%, so the description must compensate. It indirectly references both parameters ('specific colour' for colour_name, and the configure_product context implies product_id), but does not explicitly map them or provide format constraints. Given the simplicity of the two parameters, the minimal compensation is adequate but not thorough.

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

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

The description opens with a specific action, 'Verify whether a specific colour is available', and clearly identifies the resource (colour) and its role as a pre-check for configure_product. This distinguishes it from siblings like search_catalog or get_product.

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

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

Provides explicit when-to-use guidance: 'Call this when a customer requests a named colour or when you want to prevent a configure_product failure due to an out-of-stock selection.' It lacks explicit alternatives, but the context is strong enough to guide the agent.

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

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

With no annotations, the description carries the full burden and does so excellently. It discloses the checkout-locking side effect, explains that payment confirmation arrives asynchronously via webhook, and instructs polling get_order for verification. This goes well beyond basic expectations.

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 that cover purpose, usage, return value, asynchronous behavior, and side effects with no redundancy. It is front-loaded with 'Phase 2 of 2' and 'Finalise', making the core purpose immediately 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 there is no output schema and only two parameters, the description fully accounts for what the tool returns (payment_url), how to use it, its side effect (locking), and the correct follow-up action (poll get_order). It also mentions cancellation handling, making it operationally 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?

The schema provides a description for payment_method (overrides previous values), and the tool description adds semantic value by mapping Yoco to card payments and Ozow to instant EFT. The checkout_id parameter is not elaborated, but the phase context implies it references an existing checkout, and schema coverage is 50%, so this is adequate.

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 role as 'Phase 2 of 2' and 'Finalise a checkout and mint the payment link', with a specific verb (finalise) and resource (checkout). It also differentiates from sibling tools like create_checkout, update_checkout, and cancel_checkout by specifying its unique finalisation step and return of payment_url.

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?

Usage guidance is explicit: it is the second phase of a checkout flow, and it directs the agent to use cancel_checkout if the customer changes their mind, and to poll get_order to confirm payment. This clearly indicates when to use this tool and what alternatives to consider.

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 the behavioral burden. It discloses that it validates colour existence and stock, prices the blind, and returns a summary for create_cart, implying it does not itself create the cart. It does not explicitly state whether the operation has side effects or is read-only, but the 'pass directly into create_cart' phrasing gives strong evidence of its non-mutating role.

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 conveying essential information: core purpose, validation behavior, output usage, and a practical caution. It is front-loaded with the main action and contains no redundant or filler 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?

No output schema exists, but the description explains the return value ('configuration summary to pass directly into create_cart') and the validation side-effect. It covers the essential flow (validate → price → return summary) and the prerequisite check_colour_stock. It does not elaborate on optional parameters, but those are fully documented in the schema, so the description is sufficiently complete for this complexity level.

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 baseline is 3. The description adds some context by grouping parameters into a 'full blind specification' and explaining the purpose of mount type ('inside recess or outside face-fix'), but it does not detail optional parameters like finish, province, or quantity that are already well-described in the schema. Thus it meets but does not exceed the baseline.

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

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

The description clearly states the tool's purpose with a specific verb ('Lock in') and resource ('full blind specification'), and enumerates the key attributes (product, dimensions, colour, mount type). It distinguishes itself from siblings by explicitly noting it returns a configuration summary for create_cart and references check_colour_stock as a prerequisite.

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

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

The description provides explicit usage guidance: 'Call check_colour_stock first if availability is uncertain,' and indicates the output should be passed to create_cart. It implicitly differentiates from get_price by focusing on full specification and validation. However, it does not name alternative tools or state explicit when-not-to-use conditions, so slightly below a 5.

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 the full burden. It discloses key behaviors: 'no auth needed', '24-hour TTL', 'returns a cart_id', and optional seeding with items/customer details. It lacks some details like idempotency or side effects but covers the essentials well for a cart creation 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 three sentences, front-loaded with purpose, quickly covering TTL, optional inputs, and next steps. Every sentence provides value with no fluff or repetition, making it concise and well-structured.

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

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

Given two optional parameters and no output schema, the description is remarkably complete. It explains the return value (cart_id), the TTL, the optional inputs, and the subsequent flow steps. This provides enough context for an agent to invoke the tool correctly and understand what happens next.

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

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

Schema coverage is 100% with clear descriptions for items and customer. The description adds 'Optionally seed' and 'pre-configured blind items', but this mostly restates the schema. It does not provide additional semantic value beyond what the schema already communicates, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Start the open UCP purchase flow' and 'Creates a cart session and returns a cart_id'. This distinguishes it from sibling tools like create_checkout or update_cart by explicitly identifying it as the entry point for the purchase 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?

It provides explicit usage guidance: 'no auth needed' indicates when this is appropriate, and 'Next step: update_cart to add items, then create_checkout → complete_checkout to mint the payment link' gives a clear workflow and context for sequencing relative to other tools. This effectively tells the agent when to use this tool as the starting action.

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 carry the full burden. It discloses the phase, that it returns checkout_id, and that it does not create a payment link, which is useful. However, it does not explain side effects (e.g., whether the cart is modified or invalidated), permissions, or error 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 three sentences, front-loaded with the core purpose, and each sentence adds distinct value: phase, required fields, and next steps. No filler or redundancy.

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

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

Given the tool's complexity (2-phase flow, nested customer object, two input modes), the description gives essential context: phase, required fields, and what it returns. It lacks details on error conditions and side effects, but covers the primary usage scenario well. The presence of sibling tools like complete_checkout and update_checkout fills some context 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 50%, so the description must compensate. It explains the either/or relationship between cart_id and items, and clarifies that customer name/email/phone are required. However, it does not detail the structure of the items array, which remains opaque.

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 function: converting a cart or inline items and customer into a checkout. It explicitly positions this as Phase 1 of a 2-phase purchase flow, distinguishing it from complete_checkout and 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?

Provides clear guidance: use before complete_checkout, use update_checkout for corrections. It specifies required customer details and notes that no payment link is minted yet. It doesn't explicitly mention when to use create_cart or when to avoid this tool, but the phase context gives sufficient direction.

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 the full transparency burden. It discloses auth requirements, the legacy status, the server-side price re-verification, and the return of a Yoco or Ozow payment_url. It stops short of describing error behavior or side effects beyond order creation, so a 4 is appropriate.

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

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

The description is compact and every sentence earns its place: legacy/auth warning, explicit alternative, usage condition, price re-verification note, and return value. It is front-loaded with the most important caveat and contains no filler.

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

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

Given the tool's complexity (legacy auth, nested items, price handling, payment providers) and the absence of annotations and output schema, the description covers the essential aspects for correct invocation: when to use, auth requirement, pricing behavior, and the returned payment_url. It is sufficiently complete for an agent to decide and call correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by clarifying that unit_price_zar and total_price_zar are ignored and re-verified server-side, which is not evident from the schema alone. It also implies the items array is the core payload, but does not detail every nested field beyond what the schema already provides.

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 what the tool does: creates an order and returns a payment link, while immediately distinguishing itself from the preferred UCP flow (create_cart → create_checkout → complete_checkout). It specifies the legacy, auth-required nature and the single-call path, making it distinct from sibling checkout 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?

Explicit usage guidance is provided: prefer the open UCP flow when no credentials are available, and use create_order only if holding a Bearer token and needing a single-call path. It also warns that agent-supplied prices are ignored, which is critical guidance for safe 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 provided, the description carries the full burden of behavioral disclosure. It explains how each mode works (phone camera + A4 page for measurement, room photo for visualization), which goes beyond a simple surface-level description. It does not detail return values or error scenarios, but the tool's name implies it returns a URL, and the description is reasonably transparent for a simple GET-like 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 concise and well-structured: two sentences cover the core purpose and mechanics, and a third sentence succinctly explains the parameters. There is no unnecessary jargon or repetition, making it easy for an agent to quickly grasp the tool's function.

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 primary use cases, the mechanics of both modes, and the optional product_id. It does not explicitly describe the return value (URL) but the tool name covers that. For a tool with only two optional params and no output schema, this 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?

The schema already provides 100% coverage with clear descriptions for both parameters (mode and product_id). The tool description adds some context about the meaning of 'measure' vs 'visualize', but this largely restates the schema. Since schema coverage is high, the 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's purpose: to surface the AR measurement tool or product visualizer for specific customer needs (measuring windows or previewing blinds). It uses a specific verb ('surface') and resource, and the focus on AR/visualization distinguishes it from sibling tools like get_product 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 provides clear context for when to use the tool ('when a customer wants to measure their window or preview a blind in their room'), but it does not explicitly mention when not to use it or name alternative tools. This meets the 'clear context, no exclusions' criteria.

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 the full burden. It reveals that the cart is live (current state), includes customer details 'stored so far' (potentially partial), and expires after 24 hours of inactivity. The word 'Retrieve' implies read-only, which is sufficient for a simple getter. It lacks details on error handling or permissions but covers key 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 three sentences, each earning its place: the first states purpose and contents, the second gives workflow guidance, and the third provides the expiry behavior. It is front-loaded with purpose and contains no fluff.

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

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

For a simple one-param read operation, the description covers what it returns, when to call it, and a key behavioral detail (expiry). It does not have an output schema, but the description already lists the return contents. Missing error scenarios are not critical for such a tool, making it fairly 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?

The schema has 0% description coverage for parameters, so the description must compensate. It does mention 'by cart_id', but this adds little beyond the parameter name itself. No format, source, or example is given. Since there is only one simple parameter, it is adequate but does not go beyond what is already obvious.

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

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

The description clearly states the verb 'Retrieve' and the resource 'live cart state' by `cart_id`, with a specific list of contents (item list, totals, customer details). This distinguishes it from sibling tools like `get_checkout` and `get_order`, which target other resources.

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 when-to-use guidance: 'Call after update_cart to confirm changes are correct before proceeding to create_checkout.' It does not explicitly state when not to use it or mention alternatives, but the workflow context is strong and 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?

With no annotations provided, the description carries the full burden of disclosure. It clearly states what the tool returns, including the conditional payment_url ('if already minted'), and the verb 'poll' implies a non-destructive read operation. It does not mention error handling or rate limits, but for a simple retrieval tool, this is reasonable and non-contradictory.

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 action, and every clause serves a distinct purpose. There is no filler or 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?

For a single-parameter tool with no output schema, the description covers the key aspects: what it does, what it returns, and when to use it. It omits potential failure modes or detailed return structure, but the listed return items give sufficient context for an agent to choose and invoke the tool correctly.

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

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

The schema description coverage is 0%, so the description must compensate. It mentions checkout_id as the tool's input and clarifies its role as the identifier used to poll a checkout. While this adds some semantic context, it provides no format examples or constraints beyond what the schema's type 'string' already implies. The description adds a bit of meaning but not enough to fully compensate for the lack of schema documentation.

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

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

The description opens with 'Poll a checkout by checkout_id,' which pairs a specific verb ('poll') with a clear resource ('checkout'). It further distinguishes itself by itemizing the returned data (status, item list, customer details, payment_url), setting it apart from sibling tools like get_cart or get_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?

Explicit usage guidance is provided: 'Use to verify customer details before calling complete_checkout, or to retrieve the payment_url if complete_checkout was already called.' This tells the agent precisely when to invoke this tool and references a sibling tool to clarify the workflow.

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 the full burden and does well: it discloses the 5-working-day production window, excludes public holidays, names the return fields (dispatch_date, production_days, summary), and warns against quoting delivery dates due to courier variability. This is rich, honest behavioral context.

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

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

The description is efficient and well-structured: leading with the core purpose, then key behavioral details, then a usage cue. Every sentence adds value without redundancy or fluff.

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

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

For a tool with one optional parameter and no output schema, the description fully covers what the agent needs: what the tool does, what it returns, and important caveats. It is contextually complete for its simple scope.

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 order_date is fully described in the schema (ISO format, example, default), so the description adds little beyond what the schema provides. Baseline 3 is appropriate since schema coverage is 100%.

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 function: 'Estimate when a new order will be dispatched.' It uses a specific verb and resource, and the focus on dispatch timing distinguishes it from sibling tools like get_order 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 tells when to use the tool: 'Call this when a customer asks "when will it arrive?"' It also provides a critical exclusion: 'Never quote a final delivery date' — clear guidance on the tool's role and limitations.

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 the full burden and does so thoroughly. It discloses the soft-auth requirement, exact-match rule, and the motivation (prevents arbitrary lookups). It also enumerates return fields, including the payment status enum (paid|pending|failed), production status, and conditional dispatch date, giving a clear behavioral picture.

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

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

Two sentences, front-loaded with the core action, then adding essential auth and return details. Every sentence earns its place with no repetition or filler.

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

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

For a simple two-parameter getter with no output schema and no annotations, the description fully covers what the tool does, how to call it, and what it returns. It even explains the security rationale, making it independently sufficient for an agent to decide when to use 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 description coverage is 0%, so the description must compensate for both parameters. It does: order_id is explained as the lookup key, and customer_email is explained as soft-auth with an exact-match requirement. This adds meaningful semantic context far beyond the bare 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?

The description begins with a specific verb-resource pair ('Retrieve a confirmed order's status, items, and payment details by order_id'), clearly distinguishing this from sibling tools that handle carts, checkouts, or product lookups. The scope is unambiguous: it targets confirmed orders, not unconfirmed checkouts or other resources.

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 clearly implies the tool is for retrieving confirmed orders and explicitly states that customer_email is required and must match exactly, which is a critical usage constraint. However, it does not mention any alternatives or explicitly say when not to use this tool versus a sibling like get_checkout, so it stops short of a 5.

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 the full burden. It discloses that the tool returns Yoco (card, immediate) and Ozow (instant EFT via South African bank account), which is specific behavioral information. It does not discuss side effects, but 'List' implies a read-only operation and no mutation is suggested.

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 short sentences, front-loaded with the main purpose, and every sentence provides useful information without unnecessary detail.

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 one optional parameter, no output schema, and no annotations. The description explains what it returns and when to use it, plus how the result is used in other tools. This is sufficient for an AI agent to invoke it correctly.

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

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

The sole parameter order_total_zar is already described in the schema as optional and for future per-handler limit filtering. The description does not add any additional meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool lists available payment processors and their capabilities, naming specific processors (Yoco and Ozow). This distinguishes it from sibling tools like create_checkout or get_cart, which are about other aspects.

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

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

It explicitly states to call when the customer asks 'how can I pay?' or before presenting options, and explains how the result informs the payment_method field in create_checkout and complete_checkout. It does not discuss alternatives or exclusions, but the trigger context is clear.

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

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

With no annotations provided, the description carries the full burden. It discloses return values (unit_price_zar, total_price_zar) and that VAT is included, adding useful behavioral context. It also hints at the next step in the flow. While it does not explicitly state side-effect-free behavior, the 'Get' prefix and the focus on returning values imply 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?

The description is two sentences long, front-loaded with the core purpose, and includes necessary prerequisites and next steps. Every sentence earns its place with no wasted words.

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

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

Given no output schema, the description compensates by naming the return values and confirming VAT inclusion. It covers purpose, prerequisites, and next step. Optional parameters are fully described in the schema, so their absence in the description is not a major gap. Missing edge-case handling, but sufficient for correct invocation.

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

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

The input schema covers all parameters with descriptions, achieving 100% coverage. The description reinforces which parameters are required and specifies the source of product_id, but it does not add significant new meaning beyond the schema. 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's function: 'Get an exact ZAR price for a product at specific dimensions.' This provides a specific verb ('Get'), resource ('price'), and scope ('product at specific dimensions'), distinguishing it from siblings like get_product or get_delivery_estimate.

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 context: it requires product_id from search_products or lookup_catalog, and directs to call configure_product next. This establishes a clear workflow and prerequisites, though it does not explicitly state alternatives or when not to use 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 the transparency burden and does well by listing exactly what is returned: colours with in-stock status, materials, features, and maximum supported dimensions. It implies a read-only fetch operation. It does not cover failure modes or permissions, but the disclosure is solid for a simple read 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?

Two sentences: the first states purpose and return payload, the second gives usage context. No wasted words, important details are front-loaded, and the format is easy to scan.

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

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

Although there is no output schema, the description enumerates the main return fields and connects the tool to the configure_product workflow. It could mention possible absence of pricing or error behavior, but for a single-parameter retrieval tool, the description 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?

The schema only defines product_id as a string with no description. The description compensates by explaining that the id is a product identifier and providing realistic examples (roller-blockout, venetian-25mm-aluwood), adding meaningful format context beyond the bare 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 starts with a specific verb and resource: 'Fetch complete details for one product by id,' immediately clarifying the tool's primary behavior. It also provides concrete examples of product IDs, distinguishing it from search or listing siblings like search_products and 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 states when to use: 'Use before configure_product to confirm a colour exists and is in stock before committing.' This is clear contextual guidance, though it doesn't mention alternatives (e.g., check_colour_stock) or explicit when-not-to-use scenarios.

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 the transparency burden. It discloses validation constraints ('must be one of'), return content ('product_id with rationale'), and a special routing behavior for security concerns. It doesn't explicitly state non-destructive behavior, but the recommendation nature implies it, so enough context is 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?

Three dense sentences cover purpose, input constraints, optional filters, output, next steps, and a routing exception. No wasted words and the main verb is front-loaded.

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

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

For a 5-param tool with no output schema, it explains required input, optional filters, output, workflow, and an exception. Minor ambiguities like the meaning of 'location' and the security routing context prevent a perfect score, but it's sufficient for an agent to select and invoke 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?

Despite 0% schema coverage, the description names all five parameters conceptually: primary_concern (with allowed values), room (with examples), location, budget, and aesthetic. However, it omits details like budget format/currency and location values, so the compensation is partial.

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 action: 'Translate a customer's primary concern into a product recommendation' and lists valid concern values. It also distinguishes itself from siblings by specifying the return of a product_id and pointing to downstream tools (get_price/configure_product), making its role unique.

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

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

It provides context by showing when to use the tool (to turn a concern into a recommendation) and even routes security concerns to a brochure MCP (Garden Route only). It mentions next steps but doesn't explicitly contrast with sibling search/catalog tools, so it's not a 5.

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 the full burden of behavioral disclosure. It transparently reveals the routing logic (Garden Route vs. other South African locations), the specific phone numbers, and the pre-filled deep link behavior. It does not mention return format or potential side effects, but the core behavior is well disclosed for a read-only URL generation 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, front-loaded with the core action, followed by concise routing details and usage guidance. Every sentence provides necessary information with no redundancy or fluff.

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

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

Given no output schema and no annotations, the description covers the essential aspects: purpose, routing behavior, and when to use. It could have mentioned the exact return format (e.g., a URL string), but the phrase 'pre-filled WhatsApp deep link' sufficiently implies the output. Overall, it is complete enough for an AI agent to select and invoke the tool correctly.

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

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

The input schema already covers 75% of parameters with descriptions. The tool description adds value by explaining that 'location' drives routing and that 'message' is a prefill, but it does not add meaning for 'customer_name' or 'product_context' beyond their schema names. This is adequate but not exceptional.

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 ('Generate'), identifies the resource ('pre-filled WhatsApp deep link'), and clearly states the purpose (hand off customer to the right contact). It also differentiates from sibling tools by specifying routing logic based on location, which is unique among the listed 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 explicitly states when to use the tool: when the customer prefers human assistance or when self-serve checkout isn't appropriate. It also provides location-based routing conditions, but it does not explicitly name alternative sibling tools for comparison, so it falls slightly short of a 5.

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 carry the transparency burden. It communicates that this is a non-destructive read/filter operation and discloses the return fields (id and product_url). It does not mention pagination, auth, or empty-result behavior, but for a simple lookup tool, the core behavior is well covered.

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, front-loaded with the tool's purpose, and every sentence adds value. It efficiently covers functionality, ideal usage, and the alternative tool without unnecessary verbosity.

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

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

For a tool with four optional parameters and no output schema, the description gives enough context about the filter fields and the response shape. It does not specify behavior for no results or whether filters are combinable, but given the low complexity, it is reasonably complete.

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

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

Schema description coverage is only 25%, so the description must compensate. It names all four parameters and provides the category enum values, but it does not explain matching semantics for colour name (exact vs partial), the meaning of max_width_mm/max_height_mm beyond their names, or how multiple filters interact. This is adequate but not comprehensive.

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 this is a structured catalogue filter that narrows by category, colour, or dimensions, and returns matching products with id and product_url. It explicitly distinguishes from the sibling search_catalog tool for open-ended queries.

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

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

It provides explicit usage guidance: use when the customer has stated a blind type, and use search_catalog for open-ended natural language queries. This gives a clear when-to-use and when-not-to-use directive.

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 adds useful context about verified SA retailer prices, exclusions, and the WhatsApp link return value. However, it ambiguously says 'Submit a price match claim' yet returns a pre-filled link, leaving unclear whether any backend submission actually occurs. This side-effect ambiguity is a notable gap.

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

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

The description is three sentences, front-loaded with the action, and structured with exclusions and requirements in a clear, non-redundant way. There is no waste; every sentence contributes to understanding.

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, no output schema, and no annotations, this description covers purpose, thresholds, exclusions, required parameters, and return value. The main gap is the unstated side-effect semantics (actual claim submission vs. link generation), but overall it is fairly complete for the complexity involved.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that product, dimensions, and specs must be identical, indirectly guiding which parameters (width_mm, height_mm, product_id) are essential for a valid claim. It also clarifies the competitor_price_zar must be from a verified SA retailer.

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 function: submitting a price match claim when a customer finds the same blind cheaper elsewhere. It includes specific conditions (identical product, dimensions, specs) and exclusions, making it fully distinguishable from siblings like get_price or get_whatsapp_handoff.

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 clear non-applicable cases (Blinds Direct, clearance/flash-sale, out-of-stock). It also specifies minimum required inputs (product_id and competitor_price_zar), giving actionable 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?

Since no annotations are provided, the description carries the full transparency burden. It discloses key non-obvious behaviors: swatches are not sent standalone, they ship at order placement, and the request is capped at 5 codes. This is valuable context beyond the bare 'register' semantics. It does not mention side effects like requiring an existing order, but the main policy 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 sentences, front-loaded with the primary purpose, then key policy, then customer guidance. Every sentence earns its place, with no redundant or vague wording. It is concise yet comprehensive for the core message.

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 6 parameters and no output schema, the description covers the essential 'what' (register swatches), 'when' (with order placement), and 'how to handle objections' (pre-order asks). It does not explicitly mention required fields, but the schema provides that. It also doesn't describe error conditions, but the description is adequately complete for an AI agent to select and use the tool correctly in most 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?

Schema description coverage is 67%, which is moderate. The description adds meaning to swatch_codes by specifying the max of 5 and that they ship with the order, which is useful. It does not elaborate on customer_name or customer_email, but those are common fields. Baseline 3 is appropriate because the schema already covers some parameters, and the description adds limited extra parameter-level detail.

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

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

The description clearly states the tool registers up to 5 colour swatches for dispatch with the customer's order, using a specific verb ('Register') and resource ('colour swatches'). It distinguishes itself from sibling tools by emphasizing the swatch-and-order context, and the 'NOT sent as standalone postal sample' clause differentiates it from any standalone sample request tool. Scope and constraints 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 context on when the tool is appropriate: swatches ship only with order placement, not as standalone samples. It also gives explicit customer-handling guidance for pre-order requests ('explain they ship with the blind and guide them to place their order first'). However, it does not explicitly compare this tool to alternative tools like submit_enquiry, so some exclusion guidance is missing.

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 the burden of disclosing behavior. It states the output fields and the 'full catalogue' scope, implying a read-only search operation. It does not mention any side effects, pagination, or errors, but for a search tool this is adequate context.

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

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

The description is three sentences: what, what it returns, and when to use alternatives/next steps. Every sentence contributes meaningful guidance with no fluff.

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

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

For a single-parameter search tool with no output schema or annotations, the description gives the essential context: purpose, usage examples, return fields, alternative tools, and downstream integration. This is sufficient for correct tool selection and invocation.

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

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

The schema covers the query parameter 100%, and the description adds value by giving richer usage examples ('blockout for bedroom', 'wood venetian') and explaining how the query fits into the larger workflow. This goes beyond the schema's minimal 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 a specific action ('Free-text search') on a specific resource ('the full catalogue'), and differentiates from siblings by noting the alternative for filtering. The returned fields are listed, making the tool's purpose unmistakable.

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

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

It explicitly tells when to use this tool ('open queries') with concrete examples, and when not to ('For filtering by category, colour, or dimensions use lookup_catalog instead'). It also instructs how to chain the result to downstream 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?

No annotations exist, so the description carries the burden. It discloses filter behavior and return fields (product_id, name, description, features, stock count), implying a read-only query operation. It doesn't mention auth or side effects, but none are expected for a search 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, each with a distinct purpose: when to use, what filters/returns, and next step. No redundant words or filler.

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

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

No output schema, but the description explicitly lists the returned fields. It doesn't mention pagination or result limits, but for a filterable search tool the provided information is sufficiently complete for correct invocation.

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

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

The input schema has 100% parameter descriptions, so the description doesn't need to explain each parameter. It adds usage context around parameter selection but doesn't deepen semantic meaning beyond what the schema already provides.

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/filters products when no product ID is known, lists filter dimensions (type, colour, size), and specifies return fields. This distinguishes it from get_product (which presumably uses an ID) and other catalog 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?

Explicitly instructs 'Use when the customer hasn't specified a product ID yet' and directs the next step to get_price or configure_product, providing clear usage context and an implied alternative (get_product for ID-based lookup).

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 burden. It discloses the Bearer token requirement and 24-hour response time, which is useful. However, it does not describe side effects (e.g., whether an enquiry record is created), return behavior, or idempotency, leaving significant behavioral aspects opaque.

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

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

Two sentences, front-loaded with purpose and alternatives, then auth and required inputs. Every sentence earns its place with 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?

For a tool with five parameters and no output schema, the description covers purpose, alternatives, auth, required parameter provenance, and expected latency. It lacks side-effect details but is otherwise complete for an enquiry submission 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 descriptions cover all parameters, but the description adds critical context: product_config must come from configure_product output, and it names the required customer fields. This aids correct invocation beyond schema property 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 that this is a legacy auth-required tool for sales team follow-up by email, distinct from the checkout flow. It names the alternative UCP flow, which directly distinguishes it 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 provides when to use (customer wants sales follow-up by email) and when not to use (prefer UCP flow for credentialless checkout). It names specific alternative tools, giving clear actionable 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the exact effect of each operation ('add appends items', 'remove drops items by 0-based index', 'set replaces the full item list', 'clear empties the cart'), describes how the customer field merges details, and notes the checkout-in-progress constraint. It does not mention return values, errors, or permission requirements, but it covers the core mutation semantics 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, front-loaded with the core purpose, a terse but complete enumeration of operations, and a final constraint. Every sentence adds information without redundancy or filler. The structure is easy to parse and immediately actionable.

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 5 parameters, nested objects, and no output schema or annotations, which raises the completeness bar. The description covers operation semantics, the customer merge behavior, and the critical checkout-in-progress limitation. It also advises confirming with get_cart, implying the update may not return the updated state itself. However, it omits details about the return value, possible errors, and the exact item format, so it is not 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 description coverage is only 20%, so the description must compensate. It adds meaning beyond the schema by explaining the op enum ('add' appends, 'set' replaces, etc.), clarifying that indices are 0-based, and specifying that customer merges name/email/phone. The items parameter's role is implied through the op descriptions, though cart_id and the exact structure of items are not fully elaborated. This is stronger than the low-coverage baseline.

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

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

The description opens with a clear verb+resource: 'Modify an open cart before checkout.' It then details the four operations (add, remove, set, clear), giving specific meanings for each. This distinctively separates it from sibling tools like update_checkout, which target a different 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?

The description explicitly states when to use the tool ('before checkout') and provides a clear exclusion: 'Cannot modify a cart that already has a checkout in progress.' It also recommends a follow-up step ('Call get_cart afterwards to confirm'), but it does not explicitly name alternative tools for when the cart is not open or checkout needs modification.

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 the full burden. It discloses the return value (updated checkout state) and error behavior for paid/cancelled checkouts, giving the agent a good sense of side effects and preconditions. It does not mention idempotency or whether customer fields are replaced wholesale, but the key behavioral traits are covered.

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

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

The description is two sentences, front-loaded with the action, then providing return and error details. Every word adds value, and the structure is highly scannable.

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 no output schema and moderate complexity, the description covers purpose, usage timing, return value, and error conditions. It could be more complete by describing the exact shape of the updated checkout state or noting any partial-update semantics, but the essential context is present.

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

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

The schema description coverage is 0%, but the description explicitly explains the 'customer' nested object contains name/email/phone/address and enumerates the 'payment_method' options (yoco | ozow). It additionally clarifies that checkout_id refers to an unpaid checkout, providing meaning beyond the raw 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 identifies the action ('Correct customer details or switch payment method') and the target resource ('unpaid checkout'). It distinguishes itself from the sibling complete_checkout by explicitly mentioning it as the subsequent step, and the error condition clarifies the scope.

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: it should be used on unpaid checkouts before calling complete_checkout. It also implies exclusions by stating an error occurs if already paid or cancelled, though it does not explicitly name alternative tools (e.g., update_cart) or list 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.