SuperCheap

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description contributes the scope ('for this account') and the fact that the value is a yes/no enabled state, but adds no detail on defaults when unset 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?

One sentence, front-loaded with the verb and the exact fact being retrieved, with no filler or redundant restatement of the title.

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 parameterless boolean read with no output schema and full annotation coverage, the description supplies everything needed to call it correctly. The only minor gap is not stating what the response means when no preference has been recorded.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless read.

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?

States a specific verb (show) and resource (whether optional product analytics is enabled) scoped to 'this account', which is unambiguous. It doesn't explicitly name the sibling analytics_preference_set, but the get/set pairing is obvious from the name and the description clearly denotes a read.

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 is implied rather than stated: an agent can infer this reads the current opt-in state and that analytics_preference_set is the counterpart for changing it. There is no explicit when-to-use/when-not guidance, no prerequisites, and no mention of the setter as the 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?

Annotations already declare the full safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false), and the description's 'enable or disable' is consistent with that. It adds account scoping ('for this account') and the fact that analytics is optional, but says nothing about whether disabling stops collection immediately or affects stored data.

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?

One short sentence, front-loaded with the action and its target, with no filler or redundancy. Nothing could be removed without losing meaning.

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 one-parameter idempotent toggle with no output schema, the description is close to sufficient, and return values need not be explained. However, as a privacy-relevant setting, the absence of any note about the effect of disabling (immediate? retroactive?) leaves a meaningful gap.

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

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

The single boolean parameter has 0% schema description coverage, so the description carries the burden. 'Enable or disable' does convey that the flag toggles the preference on/off, which maps directly to analyticsEnabled, but it adds no detail on effect, timing, or reversibility beyond that mapping.

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 pairs a specific verb pair ('enable or disable') with a precise resource ('optional product analytics for this account'), so the agent immediately knows this is a mutation of the analytics opt-in setting. It does not explicitly name the read-side sibling analytics_preference_get, but the set/get naming makes the boundary clear.

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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to the obvious alternative analytics_preference_get. The agent must infer from the name alone that this tool writes rather than reads the preference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds no context about what clearing does to in-progress checkout, whether it is reversible, or confirmation behavior; it merely restates the operation already implied by the name and title.

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, front-loaded sentence with no wasted words. It is appropriately short for the operation, though it could add value by mentioning confirmation or sibling distinction.

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 destructive, idempotent mutation with no output schema and a required confirmation flag, the description is insufficient. It omits confirmation semantics, post-conditions, and differentiation from cart_remove_item, leaving significant gaps an agent would need to resolve.

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%: three locale parameters are documented, but the required 'confirmed' boolean (const true) has no schema description. The description mentions nothing about parameters, and the confirmation parameter is especially important for a destructive operation. Baseline 3 reflects that the schema mostly covers params, though the confirmation semantic gap is notable.

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?

States a specific verb ('Clear') and resource ('authenticated customer cart'), which is clear. However, it does not differentiate from cart_remove_item, which also removes content from the cart; the scope distinction (all items vs one item) is left implicit.

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?

There is no guidance on when to use this tool versus cart_remove_item, nor any mention of the destructive nature or prerequisites. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only that the cart is scoped to the authenticated customer and that quotes are 'current', but says nothing about an empty-cart response or stale/expired quote handling.

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 front-loaded sentence with a verb, scope, and return payload; no filler and nothing to trim.

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?

There is no output schema, so the description carries the burden of describing the return value; it mentions the cart and price quotes but not the item structure, currency/price breakdown, or empty-cart behavior. Adequate but with clear gaps for an agent consuming the result.

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%: all three required market codes are documented with ISO formats, regex patterns, and the pointer to market_list output. The description adds no parameter meaning beyond the schema, so the baseline 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?

States a specific verb (read) and resource (authenticated customer cart) plus the payload (current price quotes). This clearly contrasts with the mutation siblings cart_set_item, cart_remove_item, and cart_clear, though it never names them explicitly.

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 is only implied by the verb 'read'; there is no statement of when to call this versus checkout_quote or checkout_prepare_payment, and no note that an authenticated session/context is a prerequisite beyond the word 'authenticated'.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description contributes the useful precision that only a single exact line is removed (versus a bulk clear), but says nothing about error behavior when the item is absent or whether configurationId must match exactly.

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 tight sentence with the destructive scope front-loaded. Every word carries weight, though the brevity comes at the cost of the usage and behavioral detail noted elsewhere.

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-parameter mutation with no output schema, the description is minimally adequate: the schema carries all parameter semantics and annotations carry the safety profile. It nonetheless omits what happens on a mismatch or a missing item, which an agent would want before calling a destructive tool.

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

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

Schema description coverage is 100%, so the schema already documents itemId, configurationId, and the market codes in detail. The description's 'exact item/configuration line' wording hints that configurationId narrows the target, but adds no syntax or format meaning beyond the schema, so the baseline 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 gives a specific verb (Remove) and resource (item/configuration line from the cart), and the phrase 'one exact' distinguishes it implicitly from cart_clear. However it never names cart_clear or cart_set_item, so the sibling differentiation is left to inference.

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?

There is no explicit when-to-use guidance and no mention of alternatives such as cart_clear (remove everything) or cart_set_item (overwrite a line). The agent must infer the routing decision from the tool name alone.

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

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

Annotations already declare this a non-read-only, destructive, idempotent write, and the description adds substantive context beyond them: the overwrite (not additive) semantics for the same itemId/configurationId, the append-when-absent behavior, standard pricing when wholesale is omitted, re-quoting of pricing/availability, the required cart:write scope, and that the updated cart view is returned. No behavioral gap is left for a mutation tool of this kind.

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 core action and overwrite semantics are front-loaded, followed by prerequisites, side effects and the sibling redirect. It is fairly long at seven sentences but each one carries a distinct fact; no sentence is redundant.

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 7-parameter mutation with no output schema, the definition covers everything needed: identity key semantics, overwrite vs append, auth scope (cart:write), prerequisite tool call, pricing re-quote side effect, and confirmation that the updated cart view is returned. Nothing an agent needs in order to call it correctly is missing.

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, but the description adds real meaning the schema does not: the composite itemId/configurationId identity that determines overwrite vs append, and the default pricing behavior when wholesale is absent. It stops short of explaining return-value shape or the interaction among the three market codes.

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?

States a specific verb+resource (set cart line quantity and wholesale selection) and pins down the exact identity key (itemId/configurationId). It explicitly distinguishes itself from siblings by naming cart_remove_item and by clarifying it overwrites rather than adds, so an agent can tell it apart from cart_get, cart_clear and cart_remove_item without opening any schema.

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?

Gives explicit when-to-use and when-not-to-use: call catalog_get_product first for supplier previews and use only configurations/buyer offers actually returned, use cart_remove_item to remove a line, and it names the condition under which a new line is appended. Alternatives and prerequisites are both spelled out.

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

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

Adds behavior that annotations cannot express: for supplier previews it may trigger background supplier-detail hydration and return a pending status that must be polled. This also explains why readOnlyHint=false despite a 'get' name, so it is fully consistent with the annotations.

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

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

Two sentences, front-loaded with the return contents before the conditional hydration caveat. The second sentence is dense but each clause (preview, hydration, pending status, retry) carries distinct information.

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

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

An output schema exists, so return-value detail is not required, and the description covers the non-obvious async hydration flow. The remaining gap is the unexplained detailLevel enum, which an agent needs to pick a sensible request.

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%: countryCode and languageCode are documented in the schema, but itemId and detailLevel are not. The description does not clarify the meaningful detailLevel enum (summary/standard/full), leaving the primary ambiguous parameter unexplained. Baseline 3 for partial coverage with no compensating 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?

States a specific verb+resource (get product) and enumerates exactly what is retrieved: details, offer, attributes, variants, media, and a deep link. This clearly distinguishes it from catalog_search_products and catalog_get_similar_products, which serve different retrieval patterns.

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?

Gives concrete usage context ('before choosing a configuration or adding it to a cart') and operational guidance for the pending state ('retry while pending until full product details are available'). It does not name sibling alternatives explicitly, so it falls 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?

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond them: pagination continuation semantics ('a short page is not exhaustion'), asynchronous supplier-expansion states and retry fields, and a pricing-display constraint. However it never explains why readOnlyHint is false despite the 'get/find' framing, leaving the agent to infer that supplier expansion mutates state.

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

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

Six dense sentences, front-loaded with the core action before pagination, retry, and display rules. No filler; every clause carries operational information.

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

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

An output schema exists, so return values needn't be spelled out, and the description does reference the key output fields (status, supplierExpansion, nextCursor, retryAfter). It is nearly complete, missing only guidance on the undocumented input 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 only 29% (just countryCode and languageCode documented), so the description must compensate. It clarifies cursor reuse and the 'same item and market' constraint, but says nothing about limit, offset, or expandSuppliers, which are the parameters most likely to be misused.

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?

States a specific verb+resource ('Find similar products') and scopes it to catalog and supplier sources, which separates it from catalog_search_products. It also names the sibling catalog_get_product for hydration, though it never explicitly says the search is keyed on itemId in the first sentence.

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 routing: use nextCursor with the same item and market for later pages, retry at retryAfter/supplierRetryAt when status is pending or supplierExpansion is queued/running/throttled, and hydrate supplier previews with catalog_get_product before configuring or adding to cart. When-to-use, when-to-retry, and the alternative tool are all named.

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

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

Annotations already declare idempotentHint=true and the safety profile, so the bar is lower. The description adds useful behavioral context beyond annotations: this is an 'impression signal' used to 'demote or exclude products in later searches,' which explains the downstream effect. It does not cover auth or return shape, but the core behavioral consequence is disclosed.

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

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

Three short sentences, front-loaded with the core instruction and followed by the necessary distinction from search plus the downstream consequence. No sentence is redundant, and the structure is easy for an agent to parse.

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

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

For a two-parameter mutation with an output schema and informative annotations, the description covers purpose and behavioral consequence well. However, because schema description coverage is 0%, the description should compensate by explaining itemIds and cursor, and it does not. The result is adequate but with a clear parameter-context gap.

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

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

Schema description coverage is 0% for two parameters (itemIds and cursor), and the description provides no parameter-level meaning at all. It never explains what itemIds should contain, their format, or what cursor is for, leaving the schema's bare constraints to carry the full burden.

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

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

The description uses a specific verb ('Record') and resource ('products that were actually presented to the shopper'), and it explicitly distinguishes this tool from searching by saying 'Searching alone does not mark products as viewed.' An agent can tell this is an impression-reporting tool, not a search or retrieval tool.

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

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

It clearly states the triggering condition: record only products actually presented to the shopper, and not mere search results. It does not name a specific alternative tool or give explicit when-not-to-use cases, but the distinction from search behavior is strong enough to guide 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 annotations present the bar is lower, yet this description discloses substantial behavior beyond them: background supplier discovery, pending/queued/running/throttled states with retryAfter/supplierRetryAt, that compact changes payload size not card selection, that zero previews does not mean exhaustion, and that the card UI renders all returned items. It is consistent with readOnlyHint=false by implying side effects from supplier expansion and previews.

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?

Almost every sentence carries real operational meaning, but it is delivered as one dense, hard-to-scan paragraph of roughly 330 words mixing pagination, retry, and rendering rules. Grouping into bullets or ordered sections would materially improve first-pass comprehension, so it sits at minimum-viable-plus rather than strong.

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 an 18-parameter tool with an output schema, the description covers the hard parts: async supplier expansion, pagination resumption, and UI rendering caveats. Return values are already handled by the output schema, but amount/vendor/provider filter semantics are left implicit, leaving a small gap.

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

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

Schema coverage is only 17%, so the description must compensate and largely does: it explains limit (1-48, default 12), compact (only above 24), expandSuppliers, freshOnly, waitForSupplierResults, maxWaitMs, cursor vs nextCursor and offset vs nextOffset, and the attributeId/valueId pair constraint. It leaves sort, vendorId, sourceProvider, and min/maxAmountMinor unexplained, so it is strong but not complete.

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 opening sentence gives a specific verb and resource with scope: 'Search canonical products with category, attribute, price, provider, vendor, sorting, and bounded pagination filters.' An agent can tell this is the product search entry point. However, it never names or differentiates from close siblings such as category_get_tree, category_search, or catalog_get_similar_products, so the reader must infer the boundary.

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?

Rich conditional guidance: set expandSuppliers=false when the shopper says not to search suppliers, freshOnly=true to exclude already-seen products, limit=N to match an explicit count, waitForSupplierResults=true to poll. It states when to do many things, but does not frame alternatives among sibling tools, which keeps it 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The word 'bounded' plus the warning about loading the entire taxonomy adds useful context, but there is no mention of truncation behavior, maxNodes interaction, or how locality (country/language) affects results.

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 short sentences with the purpose front-loaded and the scoping advice second. Nothing is wasted, though the second sentence could be tightened to also cover maxNodes.

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?

An output schema exists, so return values need not be described. For a 5-parameter read tool with only 40% schema coverage, the description is barely adequate: it covers the two scoping parameters but leaves maxNodes and the required locale parameters to the schema alone.

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 40% (only countryCode and languageCode are documented in-schema). The description names rootCategoryId and maxDepth and hints at their effect, adding meaning for two undocumented parameters, but omits maxNodes entirely and does not explain the depth/node relationship.

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?

States a specific verb and resource ('Return a bounded category subtree'), which is clearly distinguishable from the sibling category_search. However, it never names the sibling as an alternative, so differentiation is implied rather than 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?

It gives operational guidance ('Use rootCategoryId and maxDepth to avoid loading the entire taxonomy'), which tells the agent how to scope a call, but says nothing about when to prefer this over category_search or what happens if the scoping parameters are omitted.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context about lexical and semantic matching, which is not in the annotations, but it does not disclose result ordering, pagination, or how canonical categories are selected.

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 front-loaded sentence with no filler. Every word contributes to identifying what the tool searches and how it matches.

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?

An output schema exists, so return values need not be described. However, for a tool with four parameters, three required, the description omits when-to-use guidance and does not fill the query/limit parameter gaps, leaving it only minimally adequate.

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

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

Schema description coverage is 50%, leaving query and limit undocumented in both schema and description. The description does not explain query syntax or constraints, the role of limit, or how countryCode and languageCode affect matching, so it fails to compensate for the coverage gap.

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 names a specific verb ('Find') and resource ('canonical SuperCheap categories') and adds the matching method ('lexical and semantic matching'). It distinguishes categories from product search siblings by resource, though it does not explicitly differentiate this tool from category_get_tree.

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?

There is no guidance on when to use this tool versus alternatives such as category_get_tree or catalog_search_products, and no when-not-to-use conditions are provided. Usage is only implied by the purpose statement.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description goes well beyond them: it explains key binding ('bound to the first idempotencyKey used'), the do-not-switch-keys rule, and replay semantics ('Replaying after success returns the existing unpaid checkout and link... without creating another Stripe session'). This is exactly the behavioral protocol an agent needs to avoid duplicate Stripe sessions.

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 tight sentences with zero filler. The precondition is front-loaded, and the remaining content is dense idempotency guidance that directly affects correct invocation.

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

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

Covers the critical workflow (approval, prepared confirmation, idempotent retry, replay behavior) and even hints at the return ('the existing unpaid checkout and link') despite no output schema. Minor gaps remain: the 'confirmed' parameter is unexplained, the prerequisite sibling is only implied, and non-idempotency error cases (e.g., invalid/expired confirmation) are not mentioned.

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

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

Schema description coverage is 0%, so the description must compensate. It explains idempotencyKey semantics thoroughly (first-key binding, retry with same key) and touches confirmationId ('retry with the same confirmationId'), but the required 'confirmed' boolean is never addressed beyond the vague implication of 'explicit user approval'. One parameter is richly covered, one partially, one not at all.

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?

States a specific verb and resource ('create the hosted Stripe payment link') and scopes it with the precondition 'use the prepared confirmation', which distinguishes this step from checkout_prepare_payment. An agent can tell it is the final materialization step rather than the preparation step.

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

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

Clearly says when to call it ('After explicit user approval', with 'the prepared confirmation') and gives retry conditions ('retry with the same confirmationId and exact same key; do not switch keys'). It implies the prerequisite sibling but never explicitly names checkout_prepare_payment or states when not to use it.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered externally. The description adds only the "authenticated customer" scoping hint; it says nothing about behavior for pending/expired checkouts, error conditions, or what the status values look like, so it does not go materially beyond the annotations.

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

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

A single front-loaded sentence with no filler. Given the tool's simplicity, the length is appropriate and every word carries information.

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

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

For a one-parameter read tool with full safety annotations this is close to adequate, but with no output schema the description should at least hint at what status values or fields are returned. Authentication requirements are only implied by the word "authenticated."

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% and the description says nothing about checkoutId — neither where it comes from nor what it identifies. The schema's uuid format and regex constrain the value structurally, but the description adds no semantic meaning beyond the parameter 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?

States a specific verb ("Read") and resource ("authenticated customer checkout/payment status"), so the intent is unambiguous. It doesn't differentiate itself from sibling checkout tools (checkout_quote, checkout_prepare_payment, checkout_create_payment_link), but the read-vs-write distinction is implicit in "Read".

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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to the sibling checkout tools it could be confused with. The agent must infer the usage context from the name alone.

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

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

Annotations already cover the safety profile (non-readOnly, idempotent, non-destructive), but the description adds real context: requires checkout:write scope, the confirmation is short-lived with an expiresAt, no order/charge is created, and the idempotencyKey binding rejects a different key on retry. This is substantial beyond-annotation detail, though return/pagination nuance is only lightly touched.

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 core action is front-loaded in the first sentence, with constraints and workflow following in logical order. It is dense and slightly run-on, but every sentence carries operational information rather than 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?

With no output schema, the description enumerates the returned values (cartRevision, confirmationId, expiresAt, totalAmountMinor, currencyCode, quote, selectedShippingOption), so an agent knows what to expect. Combined with the workflow and error conditions, it is complete for a 9-parameter, 7-required mutation tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explaining that selectedLines and cartRevision are validated against the live cart and must be passed again with the returned global cartRevision. It reinforces the binding of address, shipping option, and currency to the confirmation, going beyond field-level schema text.

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?

States a specific verb and resource ("Create a short-lived server confirmation bound to the exact selected cart lines...") and immediately scopes what it does not do ("Creates no order or charge at this stage"). It is clearly distinguishable from checkout_quote and checkout_create_payment_link, which are named directly.

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?

Gives an explicit ordered workflow: after checkout_quote, prepare this confirmation, have the user review the total/shipping, then call checkout_create_payment_link only after approval. It also states the blocking condition (cart changes) and the required retry behavior (same idempotencyKey).

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

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

The annotations flag destructiveHint=true and idempotentHint=true, but the description earns credit by explaining the actual side effect: a selected line may be repriced to current value and the shared cart revision advanced, and that unselected lines are preserved. That is mutation detail not derivable from the hints, though the interaction between 'advance the shared cart revision' and idempotentHint is left unaddressed.

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 purpose, followed by input provenance, then behavior and exclusions. No sentence is redundant — each one carries either scope, precondition, or side-effect information.

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

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

For an 8-parameter mutation tool with no output schema, the description covers preconditions, side effects, and exclusions well, but it never indicates what the quote returns (prices, shipping options, acceptance flags), which is the tool's core output and would be the main remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds provenance the schema lacks: selectedLines and cartRevision must be copied from cart_get, and unlisted lines remain in the cart. This is useful beyond the field-level descriptions.

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

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

The description states a specific verb and resource — quote the explicitly selected cart lines plus available shipping — and immediately bounds the scope. It also distinguishes itself from adjacent siblings by declaring 'It does not create an order or initiate a payment,' separating it from checkout_prepare_payment and checkout_create_payment_link.

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 places the tool in the checkout flow ('before asking the user to confirm payment') and gives a concrete precondition: copy selectedLines and cartRevision from cart_get. It doesn't spell out when to re-quote versus proceed to payment, but the surrounding context is clear enough to act on.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety/mutation profile is covered. The description does add one genuinely non-structured behavioral rule (do not fabricate missing personal data), but says nothing about duplicate handling, required-field failures, or what a successful save returns.

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 short, front-loaded sentences with no filler; the action is stated first and the constraint second. It is efficient, though the terseness is partly under-specification rather than disciplined concision.

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 10-parameter, 6-required mutation tool with zero schema descriptions and no output schema, this description is far too thin. An agent gets no field guidance, no create-vs-update disambiguation, and no expectation of the write's result.

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% across 10 parameters with 6 required, so the description must carry the semantic load and does not. It only indirectly implies that required fields (recipientName, phoneNumber, formattedAddress, etc.) must be supplied by the user rather than guessed, with no field-level meaning added.

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

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

Names a specific verb and resource ('Save a delivery address'), which distinguishes it from the read/delete siblings customer_address_list, customer_address_delete and customer_address_update. It does not, however, state the boundary against customer_address_update, which is the closest sibling.

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?

There is no statement of when to create versus update an existing address, no mention of prerequisites, and no named alternative. The single constraint ('Never infer missing personal information') is a data-handling caution, not usage routing.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description's 'explicit confirmation' largely restates the schema's confirmed const:true constraint and adds no further behavioral detail such as permanence of deletion or effect on defaults.

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 tight sentence with the destructive action front-loaded and no filler. Nothing is wasted, though its brevity leaves gaps it could have filled given the low schema coverage.

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 destructive, non-read-only mutation with no output schema, the entry covers the confirmation requirement but omits consequences: whether deletion is permanent, what happens to a default address, or what the response indicates. Annotations cover the safety hints, so this is minimally 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 0% for two parameters, so the description must carry meaning. It maps implicitly onto both: 'one saved delivery address' corresponds to addressId and 'explicit confirmation' to confirmed. This is adequate but adds no format, identity, or semantics beyond what the schema's uuid pattern and const already convey.

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?

States a specific verb (delete) and a precisely scoped resource (one saved delivery address), which distinguishes it from the sibling customer_address_update/list/create tools. It is clear and direct, though it does not explicitly name an alternative tool.

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

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

The phrase 'after explicit confirmation' implies a precondition for use, matching the required confirmed=true parameter, but there is no guidance on when to delete versus update, or what to do when an address is the default. Usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world behavior, so the safety profile is covered. The description adds only the scoping detail that results belong to the authenticated customer's saved addresses — modest added value over the structured hints.

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

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

A single efficient sentence with no filler, and the resource scope is front-loaded immediately after the verb. Nothing in it is redundant.

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 read-only list tool with rich annotations and no output schema, the description is minimally sufficient. However, it omits what a returned address contains and whether countryCode is an optional filter, leaving an agent to infer filter semantics.

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% and the single countryCode parameter is never mentioned in the description. The schema shows a ^[A-Z]{2}$ pattern but gives no prose explaining that this filters addresses by ISO country; the description does not compensate for that gap.

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?

States a specific verb (List) and resource (saved delivery addresses) scoped to the authenticated customer. The read verb distinguishes it from customer_address_create/update/delete siblings, though the description never names those alternatives explicitly.

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 versus customer_address_create or the other address siblings, and no prerequisites stated. The 'authenticated customer' phrase implies an auth requirement but does not spell out the context of 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?

Annotations only declare destructiveHint=true and idempotentHint=true; the description clarifies the mechanism by stating that required fields and the default selection are overwritten while addressLine2/administrativeArea/postalCode are retained when omitted. That merge/overwrite split, especially the warning that the default flag is overwritten, is real behavioral content not conveyed by the annotations. Auth requirements and error behavior remain undisclosed.

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, purpose first, then the destructive/merge behavior. No filler and nothing redundant with the schema or annotations.

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 an annotation-provided safety profile and no output schema, the description covers the most consequential detail an agent needs (which values survive omission and that the default selection is clobbered). Remaining gaps are authorization requirements and failure modes, which are secondary.

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% across 11 parameters, so the description must carry the load. It does explain the crucial overwrite-vs-retain split and names the optional 'address line, area, and postal code' fields, but it never addresses addressId semantics, countryCode format, phoneNumber constraints, or the individual required fields.

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?

States a specific verb and resource ('Update one saved delivery address') and scopes it to a single record, which distinguishes it from the list/delete siblings in practice. It never explicitly names customer_address_create or customer_address_delete as alternatives, so differentiation comes mostly from the verb.

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 merge semantics imply this is a partial-update tool for an existing address, which indirectly signals when to use it, but there is no explicit guidance on when to use it versus customer_address_create (new address) or customer_address_delete (removal). Usage is inferred, not stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is covered structurally. The description adds only the optionality of the configuration and the single-item scoping; it does not say what happens on a duplicate add (idempotency behavior in practice) or what the call returns.

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 front-loaded sentence where the action, the object, and the optional modifier appear in order. No filler and nothing to trim.

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 add tool with no output schema and covered safety annotations, the essentials are present. It still omits auth/prerequisite context and the interpretation of its two identifiers, which is the main gap given the 0% schema description coverage.

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 carries the burden and does partially map its fields: 'one canonical product' -> itemId and 'optionally with a selected configuration' -> the optional configurationId. It does not clarify what a 'canonical' product is versus a variant, nor what a configurationId references, so the compensation is incomplete.

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

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

States a specific verb and resource ('Add one canonical product ... to favorites'), which clearly separates it from favorites_remove and favorites_list. However, it never explicitly names or contrasts those siblings, and the meaning of 'canonical product' is left unexplained.

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 no when-to-use guidance, no prerequisites (e.g., authentication), and no indication of how this differs from cart_set_item, which is the obvious alternative for adding a product to a purchase flow. Usage has to be inferred entirely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuine context by disclosing the sort order (most-recently-saved), but says nothing about pagination behavior or whether results are capped.

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, well-formed sentence with the resource, scope, and ordering front-loaded. Nothing is padded or redundant.

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

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

With an output schema present, return values need not be explained, and annotations fully cover safety semantics. The remaining gap is that the two undocumented parameters (limit, query) are left ambiguous for an agent trying to control page size or filter.

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 50%: countryCode and languageCode are documented in the schema, but 'limit' (default 50, max 100) and 'query' (maxLength 200) carry no description anywhere. The tool description adds no parameter meaning at all, so it fails to compensate for the uncovered half.

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?

States a specific verb and resource ('List the authenticated customer favorites') plus the ordering guarantee ('most-recently-saved order'). It reads clearly against siblings favorites_add and favorites_remove, though it never names or contrasts them explicitly.

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 is only implied by 'authenticated customer favorites' — an agent can infer this is the read-side of the favorites family, but there is no explicit when-to-use, no prerequisites, and no mention of alternatives like favorites_add/favorites_remove.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds no behavioral context beyond that — it does not say whether removing a non-favorite errors or is a silent no-op, nor what happens to an associated configuration.

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 front-loaded sentence with no wasted words. It is appropriately sized for a simple removal operation.

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 mutation with annotations covering destructive and idempotent behavior, the definition is minimally sufficient. It lacks error/edge-case behavior and any relationship to the favorites_list sibling, leaving gaps an agent would want filled.

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

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

Schema description coverage is 0%, so the description must compensate. It partially does by mapping 'canonical product' to itemId and 'selected configuration' to configurationId, clarifying the two distinct removal modes, but omits format, length limits, and which is required.

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?

States a specific verb (remove) and resource (favorites), and clarifies the removable targets as 'one canonical product or selected configuration'. This distinguishes it well from favorites_add and favorites_list, though it does not name those siblings explicitly.

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, no prerequisites (e.g. the item must already be favorited), and no mention of favorites_list for verification. Usage is only implied by the verb.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the substantive context that results are market combinations spanning country, language, currency and checkout availability, but says nothing about pagination or default result size.

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 tight sentence with the resource scope front-loaded and no filler. It is efficient, though the abstract noun 'combinations' is slightly less concrete than saying it returns a list of markets.

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

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

With an output schema present, return-value explanation is unnecessary, and the safety annotations are complete. However, for a three-parameter discovery tool the description is thin: it never explains filtering semantics for query or limit, which is the main gap an agent would need filled.

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 33%: limit and query have no schema descriptions, and the description does not explain what query matches or what limit controls. Only the availability enum is documented in the schema, and the description's mention of 'checkout availability' only loosely gestures at 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 states a specific verb ('Find') and enumerates the resource dimensions (country, language, currency, checkout availability), so the agent knows exactly what data set this returns. It doesn't need sibling differentiation because no sibling tool covers markets.

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?

There is no when-to-use guidance, no mention of when this is preferable to other lookups, and no prerequisite or scoping notes. The agent is left to infer that this is a discovery endpoint from the name alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the agent knows this mutates state and is safe to repeat. The description adds the customer-confirmation precondition, but it never explains what actually changes on the order (status transition?), whether the action is reversible, or what permission it requires.

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 front-loaded sentence with zero filler. It is arguably truncated rather than wasteful, but the structure itself is efficient and the action is stated first.

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 destructive, state-changing order operation with no output schema and 0% parameter documentation, one sentence is not enough. An agent cannot tell what the confirmation does to the order, whether it triggers downstream effects (refunds, payouts, review requests), or what the boolean flag gates.

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% for both parameters, so the description must carry the semantic load and it carries none — neither 'orderId' nor 'confirmed' is mentioned in prose. The schema's const:true on 'confirmed' is self-documenting structurally, but an agent gets no explanation of why the flag exists or what orderId should reference beyond its UUID format.

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?

States a specific verb+resource ('Confirm that an order was delivered'), which is unambiguous and distinct from read-side siblings like orders_get or orders_get_tracking. It does not, however, explicitly contrast itself with orders_decide_replacement or orders_request_cancellation, the other order-state mutators.

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 phrase 'after explicit customer confirmation' gives a real precondition for when this tool is appropriate, which is more than most definitions offer. But it names no alternatives and never says when NOT to call it (e.g. what to do if the customer has not confirmed, or before a delivery date has passed).

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false, so the safety profile is largely covered. The description adds the customer-confirmation precondition, but that is also encoded in the schema's `confirmed: {const: true}`, so the added behavioral value is modest.

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 front-loaded sentence with no filler: the decision, its scope, and its precondition in one clause. Nothing to trim and nothing buried.

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?

This is an irreversible, state-changing order decision with no output schema, and the description omits what happens after the choice, whether it can be undone, what 'eligible' means, or what the agent should report back. For a destructive tool that commits a refund or replacement, that is a notable shortfall.

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 carry parameter meaning. It conveys the two valid `action` values (refund vs replace) and the confirmation requirement, but says nothing about where `orderId` comes from or what 'eligible' means operationally, leaving a gap for the third parameter.

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 names a specific verb ('Choose') and the concrete decision domain ('refund or replacement' for an order), which an agent can distinguish from neighbors like orders_request_cancellation or orders_confirm_delivery. It stops short of naming a sibling explicitly, so a 5 is not warranted.

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 gives a clear precondition: the order must be 'eligible' and the action may only be taken 'after explicit customer confirmation.' That is real when-to-use guidance, though it never names an alternative tool or states what to do when the order is not eligible.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and repeatability are covered. The phrase 'authenticated customer order' adds a useful scoping detail (results are limited to the caller's own orders, since no customer identifier is accepted), but no auth failure or not-found behavior is described.

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?

One short, front-loaded sentence with no waste. It is efficient, though borderline under-specified for the amount of structure the neighboring tools carry.

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 single-parameter read with a full set of annotations and no output schema, the minimum viable information is present. It still omits what happens on an unknown/unauthorized orderId, which is relevant given the tool is auth-scoped.

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% and the single required parameter orderId is undocumented in both schema and description. The schema supplies format and pattern constraints but not meaning, and the description does not compensate by saying where the ID comes from or that only the owner's order resolves.

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?

States a specific verb (Read), resource (order), and cardinality scope (one), which implicitly separates it from orders_list. However, it doesn't name any sibling or clarify how it differs from orders_get_tracking, which also retrieves order-related data.

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?

There is no guidance on when to reach for this tool versus orders_list or orders_get_tracking, and no mention of preconditions such as owning the order or having a valid orderId from a prior call. Usage must be inferred entirely from the tool name.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description does add genuinely useful non-annotation context: the order must be the authenticated customer's, i.e. an authorization/ownership constraint, and results come back 'normalized.' It does not disclose rate limits, freshness, or empty-result 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?

One sentence, zero filler, front-loaded with the verb and resource. Nothing to trim and nothing buried.

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 read tool with an existing output... there is no output schema, so the description would ideally say a little about the tracking event shape or ordering. It covers the ownership constraint adequately but leaves localization and return-format questions entirely to inference.

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 carries the full burden. It implies a single order identifier ('one authenticated customer order') but never mentions languageCode, which is a required parameter governing localized output — a meaningful gap the schema does not fill either.

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?

Specific verb ('read') plus resource ('normalized tracking events') and scope ('one authenticated customer order') make the function unambiguous relative to orders_get/orders_list. It stops short of naming siblings or stating what 'normalized' means, so it is clear but not maximal.

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?

There is no when-to-use/when-not guidance and no reference to alternatives like orders_get or orders_list, despite many order-related siblings. The only implicit usage signal is 'one ... order,' which implies a single orderId rather than a list.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is fully covered. The description adds 'bounded pagination', which is useful behavioral context, but it never explains what the bound is or how to page beyond it, and there is no offset/cursor parameter to reconcile this.

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?

One tight sentence with the core resource and the notable constraint front-loaded; there is 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?

For a small read-only list tool with rich annotations and no output schema, the description is minimally adequate, but the vague 'bounded pagination' claim is left unexplained and the lone parameter is described in neither schema nor prose.

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% and the single 'limit' parameter is undocumented anywhere. The description gestures at pagination but never mentions 'limit', its default of 20, or its maximum of 50, so it does not compensate for the coverage gap.

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?

Clear verb+resource ('List ... orders') scoped to 'authenticated customer orders', which naturally separates it from the singular orders_get sibling. It does not explicitly name the alternative, but the plural/list framing is 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?

The phrase 'authenticated customer orders' implies the context of use (fetching one's own order history), but no when-to-use, when-not-to-use, or alternative sibling (e.g., orders_get for a single order) is stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds the guardrail premise (verify current total/currency before acting) but does not say what the cancellation actually destroys, whether the refund is immediate or pending, or what happens on a failed verification. No contradiction with annotations.

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

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

A single front-loaded sentence with no filler; the precondition is embedded where it is needed. It earns its place, though for a destructive financial action the sentence is arguably compressed to the point of omitting consequential detail rather than being optimally 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 destructive, open-world mutation with no output schema and 0% schema coverage, the description is thin. It never clarifies what 'request' means operationally (immediate vs pending approval), what the refund outcome is, whether the operation can be retried safely, or how failures surface — all of which an agent needs before invoking it.

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

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

Schema coverage is 0% and all four parameters are required, so the description carries the burden. It implicitly explains the intent of expectedTotalMinor and expectedCurrencyCode as stale-price guard rails ('confirming the exact current order total and currency'), which is useful. But orderId and the confirmed=true const are never addressed, leaving half the surface undocumented.

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?

States a specific verb and resource ('Request cancellation') plus the adjacent refund action, which is more than a restatement of the title. It is clearly distinguishable from every sibling, none of which handle order cancellation. It stops short of 5 only because it never names an alternative tool or scope boundary.

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?

Gives one real precondition — confirm the exact current order total and currency first — which is genuine usage guidance. However, it offers no when-not-to-use case, no mention of the pending nature of a 'request', and no routing to siblings such as orders_decide_replacement for related post-purchase flows.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, covering the safety and repeat-call profile. The description adds two pieces of context annotations do not carry: the conversation must be customer-owned and the action requires explicit confirmation. It still omits consequences of closing (message history retained? customer able to reply?) and error cases such as already-closed conversations.

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 front-loaded sentence with zero filler. Every element (scope, ownership, confirmation requirement) earns its place.

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

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

A destructive mutation with no output schema and 0% parameter documentation needs more than one sentence. Annotations cover safety and idempotency, and confirmation is enforced by the schema, but the description says nothing about post-close state, irreversibility effects on the customer, or 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 description coverage is 0%, so the description must compensate. It loosely maps to both parameters: 'one ... conversation' implies a single conversationId, and 'after explicit confirmation' corresponds to the required confirmed=true const. It adds no syntax, format, or ownership-validation detail beyond that hint, leaving the burden on the schema's uuid pattern and const.

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?

States a specific verb+resource ('close ... conversation') plus scope qualifiers ('one', 'customer-owned'), so the operation is unmistakable. It does not name or differentiate from siblings like support_conversation_create or support_conversations_list, which a 5 would require.

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?

'after explicit confirmation' gives a gating condition for invoking the tool, which is real usage guidance. However, there is no mention of alternatives (reopen, escalate, reply via support_message_send) or when NOT to close a conversation.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and idempotency profile is covered. The description adds the important behavioral constraint that the message wording must be customer-approved and verbatim, but says nothing about permission requirements, what happens on a duplicate clientMessageId, or the result of a successful call.

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 front-loaded sentence with no filler; the verb and resource lead. It is efficient, though the terseness is a symptom of under-specification rather than deliberate economy.

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 six-parameter mutation with zero schema descriptions and no output schema, this is far too thin. The agent gets no information about required fields, idempotency semantics via clientMessageId, the meaning of the forced confirmed=true flag, or expected results.

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% across six parameters, so the description carries the full explanatory burden and falls short. It only hints at the body ('exact customer-approved message') and obliquely at confirmed, leaving orderId, subject, attachmentIds, and the idempotency role of clientMessageId completely undocumented.

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?

States a specific verb and resource ('Create a support conversation') and adds the distinguishing constraint that the body must be the exact customer-approved message. It does not explicitly name siblings such as support_message_send or support_conversation_close, so an agent must infer the boundary between creating a conversation and appending to one.

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

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

'Using the exact customer-approved message' implies a precondition and a workflow (message must already be approved by the customer before calling), which is useful implied guidance. However, no alternative is named and no explicit when-not condition is given, so the agent must infer that support_message_send is for existing conversations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the vague 'authenticated' scope qualifier and says nothing about pagination, ordering, or what the response contains — behaviorally important for a list endpoint.

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 short sentence with zero filler, and the verb/resource is front-loaded. It is efficient, though its brevity leaves it under-specified rather than genuinely 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 listing tool with a pagination-limited parameter and no output schema, the description should at minimum say what a page contains, ordering, or how to page further. None of that is present, so an agent must guess at result semantics.

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% and the single `limit` parameter is never mentioned in the description. The schema does supply type, default (20), minimum and maximum, so the agent can call it, but the description adds no meaning beyond the schema.

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

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

States a concrete verb+resource ('List ... support conversations'), which cleanly separates it from support_messages_list and support_conversation_create. However, it never explicitly contrasts itself with those siblings; the distinction has to be inferred from the noun.

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?

There is no guidance on when to call this versus support_messages_list (messages for a conversation) or the other support_* tools, and no mention of prerequisites such as needing an authenticated session. The word 'authenticated' hints at a precondition but doesn't state one.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is largely covered. The description adds a real behavioral detail – the message must be the customer-approved text sent to an owned conversation – but omits the required confirmation gate and what happens on failure, leaving meaningful gaps.

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

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

A single eleven-word sentence with the verb front-loaded and no filler, which is efficient. However, given a five-parameter mutation with a confirmation gate, this brevity reads as under-specification rather than disciplined 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?

For a write tool with no output schema, five parameters and zero schema documentation, the description is far too thin. The confirmation requirement, idempotency behavior, attachment handling, and error/return expectations are all absent, so an agent cannot call it correctly without inference.

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% across five parameters, so the description carries the full burden and delivers very little. 'One owned conversation' loosely implies conversationId ownership and 'exact customer-approved message' hints at verbatim body content, but clientMessageId (idempotency), attachmentIds, and the confirmed const-true confirmation gate are never explained.

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?

States a specific verb ('Send') and resource ('message') scoped to a single owned conversation, which clearly separates it from the read-only sibling support_messages_list. The phrase 'exact customer-approved message' is slightly opaque but the core action is 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?

No when-to-use guidance, no exclusions, and no reference to alternatives such as support_messages_list or support_conversation_close. The only usage constraint offered is 'one owned conversation', which is a scoping fact rather than routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description's only added value is the 'customer-owned' scoping constraint (only the caller's own conversations). It says nothing about pagination despite a max limit of 100, so behavioral disclosure beyond annotations is thin but consistent.

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 seven-word sentence with the resource and scope front-loaded and zero filler. It is efficient, though the brevity shades into under-specification rather than pure 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?

For a list tool, the description omits the essentials an agent needs: pagination/truncation behavior given the hard limit of 100 and no cursor parameter, and any indication of what a message record contains. Annotations cover safety and no output schema exists, but the listing semantics are left entirely unexplained.

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 carries the full burden. 'One ... conversation' weakly implies the required conversationId, but the limit parameter (default 50, max 100) is never explained — no statement about whether results are truncated or how to page. The description does not compensate for the coverage gap.

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 a specific verb and resource ('Read messages') scoped to 'one customer-owned support conversation', which distinguishes it from support_conversations_list (conversations, not messages) and support_message_send (write vs read). It stops short of explicitly naming those siblings, but the scope phrase is enough for an agent to route correctly.

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?

There is no explicit when-to-use, when-not-to-use, or alternative-tool guidance. The single-conversation scoping implies the tool requires a conversation context, but nothing tells the agent how to pick between this and support_conversations_list, or what to do first to obtain a conversationId.

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