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

Annotations already declare destructive and idempotent behavior, and the description corroborates with useful extra context: it revalidates price, stock and caps, and 'never resends a plan' explains the idempotency guarantee in concrete terms. It does not contradict destructiveHint=true, though the interplay between a one-unit POST and a destructive hint is left unexplained.

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 tight, front-loaded sentences with no padding; the approval precondition and revalidation guarantee are stated early. The unexplained 'Trusted backend:' prefix is the only wasted token.

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, and the annotations carry the safety profile. The description covers the approval gate, the revalidation of price/stock/caps, and idempotency, which is most of what an agent needs for a cart mutation.

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 required parameters. The description gestures at plan_id via 'approved add plan belonging to this account,' but says nothing about session_token, the 32-hex plan_id format, or the unit cap implied by 'caps.' It does not compensate for the missing schema documentation.

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

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

States a specific verb (POST one unit) and resource (account cart), and the phrase 'belonging to this account' distinguishes it from the sibling add_to_cart. However, the 'Trusted backend:' framing and 'approved add plan' jargon are not explained, so the operation is clear but the mechanics are opaque.

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 line 'Requires explicit host approval' and 'with an approved add plan' implies a precondition and a plan-first workflow, which suggests prepare_account_cart_change as the preceding step. But it never names that alternative or states when to choose this tool over add_to_cart or update_account_cart_item, leaving the routing to inference.

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 mutation/idempotency profile, but the description adds real behavioral context beyond them: the pre-write refresh of cart, price, inventory and both limits, the read-back after writing, and the guarantee that a retry with the same plan_id inspects rather than resends.

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 action and its gating condition; the retry/idempotency caveat follows immediately. 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 single-parameter write with an output schema, the description covers everything the agent needs: approval requirement, what is refreshed beforehand, and the safe retry protocol. Return values are correctly left to the output schema.

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

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

Schema coverage is 0% (only a hex pattern), so the description must carry the meaning of plan_id — and it does, framing it as an approved add plan whose reuse is what makes retries safe. It does not explain where a plan_id comes from, which keeps it from a 5.

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 ('POST one new seller offer') plus its gating input ('an approved add plan'), which cleanly separates it from prepare_cart_change and update_cart_item in the sibling list.

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 preconditions ('approved add plan', 'Never call without user approval') and a narrow retry rule tied to the same plan_id. It stops short of naming the sibling that produces the plan (prepare_cart_change), leaving that linkage to inference.

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 and openWorldHint, so the safety profile is covered. The description adds a genuine reliability caveat ('verified only for Digikala') that the structured fields don't convey, but says nothing about rate limits, latency, or result quality.

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, front-loaded with the core purpose. Efficient, though extremely terse for a tool whose parameters are otherwise undocumented.

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 no explanation. However, with both required parameters at 0% schema coverage, the definition leaves the agent guessing what to pass and how this differs from running a real search.

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, yet it never explains what 'query' should contain or that 'market' scopes the suggestion source. It only loosely implies Digikala maps to market via the verification note.

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: it suggests search phrases, which is clearly distinct from sibling search_products (which executes searches). It doesn't explicitly name that sibling, but the purpose 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 relative to the 38 siblings, particularly search_products or get_trend_snapshot. The 'verified only for Digikala' note is a coverage caveat, not usage direction.

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

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

Adds substantial behavioral context beyond the read-only annotations: catalog caching up to 60 seconds, no substitute if an offer disappears, expected_price_rial as optional price-change detection, currency (IRR), difference direction and shipping exclusion, zero-based pair indexes, non-equivalence of matching names/attributes, and error isolation. All details are consistent with readOnlyHint and openWorldHint.

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

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

Front-loads the core purpose ('Compare 2-6 explicit seller offers...') and then packs in useful constraints. The description is dense but each sentence contributes operational information, with only minor fragmentation across many short clauses.

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

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

Given an output schema exists and annotations cover safety, the description provides strong behavioral and comparison semantics. It is nearly complete, though the absence of schema parameter descriptions means a few input fields (market, product_id, location) receive no explicit explanation.

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

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

With 0% schema description coverage, the description carries the burden of explaining parameters. It clarifies offer_id (not variant_id or seller_id), expected_price_rial, money units, and pair index ordering, but leaves market, product_id, and location undocumented beyond their schema constraints.

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 ('Compare 2-6 explicit seller offers') with scope and source ('from get_product results'). It does not explicitly name or differentiate from sibling tools such as compare_product_sellers or compare_products, so sibling distinction 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?

Implies usage context by specifying 'from get_product results' and gives constraints such as using offer_id rather than variant_id or seller_id. However, it does not state when to choose this tool over alternatives like compare_product_sellers, nor 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?

Annotations cover the safety profile (readOnlyHint) and open-world scope, and the description adds meaningful semantics beyond that: literal labels/values without inferred equivalence or unit conversion, explicit missing values and item errors, no ranking, and the caveat that prices/stock are cached observations rather than a checkout quote. That is a strong set of behavioral disclosures, with only minor gaps such as no mention of pagination or response shape (which the output schema likely covers).

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

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

Four short, front-loaded sentences that each carry a distinct constraint (scope, comparison semantics, output semantics, data freshness caveat). No filler or restatement of the tool name.

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 is appropriately complete for a read-only comparison tool given its annotations. The remaining gap is parameter-level clarity around the ID input format, which neither the description nor the schema documents.

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 parameter is a nested object wrapping a required array of numeric-string product IDs (pattern ^[0-9]{1,20}$). The description only repeats the 2–6 cardinality that the schema already enforces via minItems/maxItems, and does not explain the ID format, the nested 'query' wrapper, or how missing/invalid IDs surface as errors at the parameter level.

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 (Compare) and resource (specifications of products) with an explicit cardinality scope of 2–6 items, which implicitly separates it from sibling tools like compare_offers and compare_product_sellers. It stops short of naming an alternative, so the differentiation is inferable 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?

Usage is implied by 'Compare specifications' and constrained by 'No ranking', but the description never says when to pick this over compare_offers, compare_product_sellers, or get_products_batch, nor what preconditions apply. No explicit when/when-not or alternative 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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: a 60-second snapshot cache, inclusion of seller metrics, and the caveat that unknown shipping blocks a cheapest-delivered-total claim.

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

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

Four short sentences, front-loaded with the core operation and constraints, then the caveats. Nothing is padded, though the color/size/warranty sentence is advice rather than definition.

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 cover the safety profile. The description supplies the input constraints, cache freshness, and the shipping caveat, leaving only the sibling-disambiguation 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% and the schema has a nested object, so the description must carry the load. It does: it confirms 2–6 offer IDs (matching minItems/maxItems) and that all IDs must belong to a single product, adding real meaning the schema cannot express.

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 (compare) and resource (product sellers/offers), names the source tool list_product_sellers, and pins the input to 2–6 exact offer IDs for one product. It does not, however, distinguish itself from the very similar sibling compare_offers, which is the main gap.

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 a clear prerequisite (offer IDs must come from list_product_sellers) and a soft usage hint (compare color/size and warranty before price). It stops short of stating when to use this over compare_offers or when not to use it at all, leaving the key routing decision to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered structurally. The description adds real context beyond that: it is backend-trusted only and access is scoped to 'this token's account', implying authorization boundaries. It stops short of stating failure behavior or what happens with an unknown/foreign operation_id.

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, followed by the one non-obvious format constraint. No filler or repetition. Slightly compressed jargon ('plan/replacement') costs a little clarity, but the structure is efficient.

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

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

An output schema exists, so return values needn't be described. For a two-parameter read tool the description covers purpose and one parameter format, but omits the guest-vs-account distinction from get_cart_operation and any explanation of session_token, leaving notable gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the burden. It does add meaning for operation_id by noting that replacement operations use request_id as 32 lowercase hex digits without hyphens, matching the schema pattern. However, session_token receives no explanation at all, leaving half the parameters 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?

The description states a specific verb ('inspect') and resource ('a plan/replacement belonging to this token's account'), and the account scoping differentiates it from the guest-facing sibling get_cart_operation. The terminology drifts from the name ('operation' vs 'plan/replacement'), but it usefully clarifies what an operation actually is. Clear enough for selection without naming the sibling 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?

The 'Trusted backend' prefix implies the calling context (server-side, trusted clients only), which is implied usage guidance. However, it never states when to prefer this over get_cart_operation or what precondition (e.g. an existing prepared/replacement operation) must hold. No explicit when-not or alternatives are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond them: null limits mean increases are disabled until both limits are set locally, tools cannot raise or disable limits, and unknown item prices block increases — all non-obvious constraints for an agent reasoning about cart operations.

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

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

Four short sentences, front-loaded with what is returned before the constraint notes. All sentences carry information, though the phrasing of 'Null limits means increases are disabled until both limits are set by the user locally' is slightly awkward and could be tightened.

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 explained. For a zero-parameter read tool with annotations covering the safety profile, the description supplies everything else needed: the semantics of a null result and the conditions that block cart increases.

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, so the baseline is 4 per the rubric. Schema coverage is 100% and there is nothing for the description to disambiguate about inputs.

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 precise verb+resource ('Return locally configured maximum merchandise rials and total units') and narrows the scope with 'excluding shipping' and 'locally configured'. An agent can tell this reads cart-level increase limits rather than any sibling cart mutation tool such as add_to_cart or read_cart.

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

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

Usage is only implied: the mention that 'unknown item prices block increases' and 'tools cannot raise or disable these limits' hints this is a pre-flight check before a cart increase, but the description never explicitly says when to call it versus prepare_cart_change or add_to_cart. No exclusions or alternatives are 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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior: which lifecycle states are returned (prepared, executing, uncertain, terminal) and the reassurance that no mutation is sent, which clarifies what an 'operation' inspection means.

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 tight sentences, front-loaded with the primary action and followed by the state coverage. No filler, though the second sentence could integrate more economically.

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 cover safety. State coverage is described, so the only real gap is the undocumented operation_id, which is minor for a single-parameter read.

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?

There is one parameter (operation_id) with 0% schema description coverage; the strict pattern ^[a-f0-9]{32}$ is the only guidance. The description never mentions the parameter or its expected format, so it does not compensate for the documentation 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 verb ('inspect') and an object ('journaled plan/replacement'), but 'journaled plan/replacement' is unusual jargon an agent cannot fully map to a concrete resource. The desktop-vs-account distinction from the sibling get_account_cart_operation is only hinted at ('connected desktop account'), never made 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?

No statement of when to use this versus alternatives such as get_account_cart_operation or reconcile_cart_operation. The only usage cue is the implicit 'inspect state,' which an agent must infer.

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 safety (readOnlyHint, openWorldHint). The description goes beyond them by disclosing a 60-second cache and that no arbitrary query parameters are accepted — both genuine behavioral traits an agent needs. It stops short of describing pagination or error behavior, so not a 5.

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, zero filler, with the core purpose front-loaded and the usage pattern following immediately. Every clause 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?

An output schema exists, so return-value documentation is not needed, and the description covers caching and downstream usage. Given the single trivial parameter this is nearly complete; only the category_id acquisition path is left implicit.

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

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

Only one parameter (category_id) with 0% schema description coverage, so the description carries the burden and largely doesn't explain the ID format or how to obtain a valid category_id. It does add useful meaning about the shape of the output values ({"brands": ["18"]}), which is why it isn't lower than baseline.

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

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

States a specific verb and resource — retrieving real brand, color and attribute IDs for a category — which is clearly distinct from list_categories (returns categories) and get_product (returns a product). The mention that these IDs feed search_products.query.filters.values further pins down the tool's role.

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 explains the workflow: fetch IDs here, then pass selected keys and option IDs into search_products query.filters.values. It does not state when NOT to use the tool or name an alternative source of filter IDs, but the intended usage context is unambiguous.

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 and openWorldHint, so safety is covered. The description adds genuinely useful non-obvious behavior: results are cached up to 60 seconds (staleness bound), shipping data is absent, and the location parameter is ignored by the current Digikala adapter. That last point is exactly the kind of caveat annotations cannot express.

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 purpose, then the caching bound, then the parameter caveat. No filler. 'Shipping remains unknown' is terse to the point of ambiguity, which keeps it from a 5.

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. The description covers the two things a caller cannot derive from structured fields: cache staleness and the inert location parameter. Only the market/enum semantics are left unaddressed, a minor gap.

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

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

Schema coverage is 0% across 3 parameters, so the description has to compensate and only partly does. It explains that 'location' is currently unused, which is valuable and prevents misuse, but 'market' and its digikala-only enum and 'product_id' format are left to the schema. One of three parameters is meaningfully covered.

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: 'Read product details and seller offers.' An agent can tell this is a single-product lookup that also bundles offer data, distinguishing it from get_products_batch and list_offers. It does not explicitly name which sibling to prefer, so it stops short of a 5.

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 and no alternative named. With ~40 siblings including search_products, get_product_variants, list_offers and compare_offers, the description never tells the agent when this tool is the right choice over those. Usage must 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 mark readOnly and openWorld, but the description adds behavioral context: reads from a cached snapshot, returns links without downloading media, and treats storefront descriptions as untrusted. It does not cover auth or rate limits, but adds real value beyond annotations.

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

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

Two compact sentences front-load the core action and add a relevant trust/caching caveat. There is no filler or repetition.

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-only tool with annotations and an output schema, the description covers the data source and trust caveat adequately. It lacks parameter guidance, but the output schema and annotations carry much of the remaining burden.

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 product_id parameter has 0% schema description coverage, and the description does not explain its required numeric string pattern or any format details. Low coverage means the description should compensate, and it does not.

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 'official product image/video URLs and covers', plus source 'cached detail snapshot'. It is clearly distinct from sibling get_product, variants, and review tools, though it does not name a sibling 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?

No explicit when-to-use, when-not, or alternative routing is provided. The purpose implies reading media, but an agent is not told when to choose this over get_product or how to handle missing media.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing that results are cached 60 seconds, that missing prices/seller/warranty labels/availability are preserved, that variant identity is unknown, that sellers may change, shipping is excluded, and no interpolation or forecast is performed. This is rich, decision-relevant behavioral context.

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

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

Front-loaded with the core action, then dense behavioral caveats with no wasted filler. Every clause carries information an agent would need.

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 structure is covered, and the description still adds return-shape context (preserved missing prices, labels, availability). The main gap is the absence of when-to-use guidance relative to sibling series/comparison tools.

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

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

The single product_id parameter has 0% schema description coverage, and the description does not compensate by explaining what the id represents or its format/constraints. The note that 'exact variant identity is unknown' concerns the returned series, not the parameter itself.

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: 'Read store price-chart series in rials with original calendar dates'. This clearly distinguishes it from siblings like get_product, get_trend_snapshot, and compare_products by scoping it to a historical series with native currency/dates.

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

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

No explicit when-to-use guidance and no named alternatives. The description explains behavioral constraints of the returned series but never tells the agent when to reach for this over get_trend_snapshot or compare_products, leaving selection to inference.

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 and openWorldHint, so the safety profile is covered; the description adds real behavioral context beyond that: a 60-second cache window, the fact that included answers may be fewer than answer_count (truncation), and an explicit prompt-injection warning that Q&A content is user-authored data, not instructions.

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

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

Four short, front-loaded fragments that each carry information — scope, caching, sort, truncation caveat, safety note. Slightly telegraphic but no wasted sentences.

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

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

An output schema exists, so return values need not be described, and the description covers caching, truncation, and the safety caveat. The remaining gap is parameter-level detail for page and product_id format, which is minor for a read-only listing tool.

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

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

Schema description coverage is 0%, so the burden falls on the description, which does explain the two sort modes (newest vs most answers) and implies single-page paging via 'one native question page'. However, it never clarifies the page parameter semantics, the max of 1000, or the product_id pattern, leaving roughly half the semantics to the raw schema.

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

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

States a specific verb+resource: reading one page of a product's native questions with their answers. The resource (questions) is clearly distinct from neighboring read tools like get_product_reviews, get_product_ratings, and get_product, though no sibling is named 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 implied — browse questions for a product, optionally sorting by newest or most answers — but there is no explicit when-to-use vs when-not, nor any routing to sibling tools such as get_product_reviews for a different content type.

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 and openWorldHint, so the description correctly goes further by disclosing the 60-second cache-sharing behavior and that absent metrics stay unknown rather than erroring. That is genuine behavioral value beyond the structured fields.

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, front-loaded with the payload contents and followed by the caching caveat. 'Missing metrics remain unknown' is slightly terse but earns its place by flagging partial responses.

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 no prose explanation, and annotations cover the safety profile. The description supplies the caching and partial-data behavior an agent needs, leaving little unaddressed for a single-parameter read tool.

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

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

Schema description coverage is 0% and the single product_id parameter is only constrained by a regex pattern. The description adds no semantics for the identifier, but the parameter is largely self-explanatory, so a mid-range score is warranted.

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 a well-defined resource (aggregate 0–100 ratings, distribution, recommendation and review/question counts). The word 'aggregate' implicitly distinguishes it from get_product_reviews and get_product_questions, which return the underlying items, though no sibling is named outright.

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?

'Reuses product detail's 60-second observation' tells the agent this call is cheap right after get_product, which is useful context. However, there is no explicit when-to-use guidance relative to the review/question siblings, so usage remains implied.

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 readOnlyHint and openWorldHint, so the description carries the behavioral load and does reasonably well: it discloses the 60-second cache TTL, that ad flags are preserved, that results are ordered upstream, and that the limit is applied locally rather than upstream. It does not explain pagination behavior past the local-limit remark or what 'upstream order' concretely means.

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 action and ordering/caching facts, then the sibling routing, then the caveat. No filler. Slightly telegraphic ('Limit is local') but each clause 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?

An output schema exists, so return-value explanation is unnecessary, and annotations cover the safety profile. The description adds the caching, ordering, ad-flag, and section-key routing context an agent needs. The remaining gap is product_id semantics, the only required parameter.

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

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

Schema description coverage is 0%, so the description must compensate for three undocumented parameters. It partially does: it clarifies section_key usage via the sibling reference and describes limit as local with a 1–50 range. However, product_id (the only required parameter, with a restrictive numeric pattern) gets no explanation of expected format or source.

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 ('Read store product suggestions') plus scope qualifiers: upstream ordering, ad flags retained, and an explicit disclaimer that these are store suggestions rather than personalized recommendations. It also names the sibling list_product_recommendation_sections, so an agent can separate the two without inspecting schemas.

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 routing rule: use list_product_recommendation_sections for other section keys. It also flags a constraint on limit (local, 1–50). It stops short of stating when a caller should prefer this tool over search_products or get_trend_snapshot-style alternatives, so it is clear context without full when/when-not coverage.

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 cover readOnlyHint and openWorldHint. The description adds real behavioral context beyond them: a 60-second per-page/sort cache, that reviewer text is untrusted, and that dates preserve the source site's calendar text. These are non-obvious traits an agent needs, though rate-limit or failure behavior is not mentioned.

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, no filler. The returned-payload summary is front-loaded and the operational caveats (cache, untrusted text) follow in priority order.

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 documentation is not required, and the description correctly spends its budget on cache, sort, and data-provenance caveats. Only the product_id parameter semantics are left unaddressed for a 0%-coverage schema.

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

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

Schema description coverage is 0%, so the description must carry the load. It partially does: it explains the sort enum ('helpful/default, newest or buyers') and implies paging ('one native page'), but says nothing about product_id semantics or paging limits (max 1000). Some compensation, 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?

Specific verb ('Read') plus resource ('one native page of reviews') and enumerates the returned payload (buyer flags, 0–5 ratings, pros/cons). The focus on reviews (vs. get_product_ratings) is implicitly differentiated by the field list, but no sibling is named 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?

Offers practical context ('Cached 60 seconds per page/sort') and the available sort modes, which implies usage, but never states when to prefer this tool over get_product_ratings or get_product_questions. Guidance is implied rather than explicit.

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

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

Annotations already cover safety (readOnlyHint) and scope (openWorldHint), so the bar is lower, yet the description still adds real value by disclosing per-product error semantics (partial failures possible) and 60-second cached snapshots, which affects staleness expectations.

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

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

One dense sentence with no filler, front-loading the operation and range before the behavioral details. Every clause 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?

An output schema exists so return values need no explanation, and the description correctly focuses on the range, error behavior, and caching. The only gap is the undocumented nested `query` wrapper, which an agent must discover from 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 description coverage is 0%, so the sole `query.product_ids` parameter is undocumented structurally, and the description never mentions the `query` wrapper object. It does add the useful 'distinct' qualifier and restates the 1–20 bound that the schema already enforces via minItems/maxItems.

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 (product IDs) and explicit batch scope (1–20). It implicitly distinguishes itself from the single-item `get_product` and the discovery-oriented `search_products`, but never names those siblings, so the 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?

The description states a range but gives no when-to-use guidance: it never says to prefer this over repeated `get_product` calls, nor when to fall back to `search_products` for unknown IDs. Usage is only implied by the batch shape.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: a 60-second cache, the warning to preserve exact IDs, the semantics of a variant ID as a seller offer, and the caveat that unknown availability and shipping remain unknown.

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 compact sentences front-load what the tool returns, then give caveats. Every sentence carries useful information, though the structure could be slightly tighter by grouping the ID warnings.

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 explained, and the annotations cover safety. However, the description omits any explanation of the one required input parameter, leaving a notable gap for an agent invoking the 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?

There is one required parameter (product_id) and schema description coverage is 0%, so the schema documents only type and pattern, not meaning. The description does not mention product_id or explain its expected format, failing to compensate for the coverage gap despite the parameter's obvious name.

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

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

The description states a specific verb (List) and resource (offer/variant IDs, attributes, warranty, prices) and mentions the variants endpoint. It is clear what the tool returns, but it does not explicitly name or distinguish itself from close siblings such as get_product_variant_types or list_offers.

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 offers no explicit when-to-use guidance, no when-not-to-use conditions, and no alternatives. The caution about IDs and unknown availability implies care in using results, but not when this tool should be selected over siblings.

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 and openWorldHint, so safety is covered. The description adds genuinely new behavioral facts: results come from the same 60-second variants snapshot (a freshness/staleness bound) and absent dimensions are not invented (a data-fidelity guarantee against fabricated dimensions). Those two clauses are real value beyond the annotations.

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

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

Two short sentences, front-loaded with the output shape before the provenance caveat, with no filler. The phrase 'the same 60-second variants snapshot' is slightly cryptic because the antecedent snapshot is never named in this description.

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 structure need not be explained, and the read-only listing nature is covered by annotations. What is missing for correct selection is the relationship to get_product_variants and any indication of result size or pagination, leaving the agent to infer sibling routing.

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 for the single product_id parameter and says nothing about it. However, the schema supplies the type and a numeric pattern, and the parameter name is fully self-describing for this domain, so the gap is small rather than severe.

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 concrete verb (group) and a concrete resource (observed variation dimensions such as color and size) and states what the output carries (value IDs and offer IDs), so the agent can tell it produces a grouping of variant dimensions rather than raw variants. It never contrasts itself with the very similarly named sibling get_product_variants, which is the one distinction an agent most needs here.

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 at all: nothing says when to call this instead of get_product_variants, get_product, or list_offers, despite the near-identical sibling name. The only contextual hook is the provenance note, which is not usage 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?

The annotations already declare this is a read-only, open-world operation, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it preserves upstream order and is a timestamped popularity signal rather than a historical series. It further clarifies data limitations by saying sales counts and period/category-specific popularity are not supplied.

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

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

The description is three short sentences with no wasted text. It is front-loaded with the core action and resource, then follows with precise limitations. Every sentence adds distinct value for an agent deciding whether to call the tool.

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

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

Given the tool has no parameters and an output schema exists, the description does not need to explain return values. It supplies the essential context: what is read, that upstream order is preserved, and what the result is not. Combined with annotations that cover safety and open-world behavior, this is complete for correct invocation.

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

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

The tool takes zero parameters, so the baseline is 4 per the rubric. The description does not need to explain parameter semantics, and it correctly avoids doing so. The empty schema is consistent with the description.

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

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

The description names a specific verb ('Read') and resource ('current homepage best-selling listing'), then immediately scopes it by saying order is preserved. It also distinguishes its purpose from adjacent concepts by stating it is a timestamped popularity signal, not a historical trend series. An agent can identify exactly what this tool does without opening the 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?

The description gives clear usage context: it is for the current homepage best-selling listing and explicitly not for historical trends. It also states what data is not supplied (sales counts, period or category-specific popularity), which helps avoid incorrect use. It does not, however, name alternative sibling tools for related needs, so it falls short of full when/when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond them: pagination is local over the current upstream tree and is ordered by numeric ID, which tells the agent results are a snapshot rather than a live paged upstream query.

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

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

Five short sentences, zero filler, front-loaded with the purpose and followed by filtering, pagination, then downstream usage. Every sentence earns its place.

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

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

An output schema exists so return values need not be described, and the description covers filtering modes, combination rules, pagination behavior, and cross-tool usage. Only the page/page_size mechanics are left thin for a tool with 0% schema 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 must carry the load, and it explains query, roots_only, and parent_id semantics plus filter combinability. It only weakly covers page/page_size ('page through'), leaving the defaults and 100-item cap to the schema, but the key semantics are 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?

States a specific verb and resource: 'Find live Digikala category IDs' and enumerates the match keys (Persian/English name, code, ID substring). This clearly separates it from siblings like list_markets and get_category_filters, so an agent can select it without opening schemas.

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?

Tells the agent exactly how to use it in every mode: omit query to page all, roots_only for top-level, parent_id for children, and that text and parent filters combine. It also routes onward explicitly: 'Use category_id in search_products, with or without search text.'

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=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context by clarifying that the result reflects implemented markets and verification status rather than a live health check.

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 compact sentence with the primary purpose front-loaded and the key caveat attached efficiently. There is no filler or redundant restatement.

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 zero parameters, read-only annotations, and an existing output schema, the description includes enough to call the tool correctly and avoid one major misuse. It could be slightly richer about what 'markets' means in context, but no essential calling information 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?

The tool has zero parameters, and the schema description coverage is 100%, so there are no parameter semantics for the description to compensate for. The baseline score for a no-parameter tool is appropriate.

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

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

The description gives a specific verb and resource: 'List implemented markets and verification status.' This is clear enough for an agent to know what the tool returns, though it does not explicitly distinguish this tool from any sibling by name or function.

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

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

The clause 'this is not a live health probe' provides a useful usage boundary by ruling out a likely misinterpretation. It does not state positive when-to-use conditions or name alternatives, so it stops short of full 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?

With readOnlyHint and openWorldHint already set, the description adds substantial behavior: 60-second cache, integer rial prices, unknown values remain unknown, out-of-stock offers retained, observed_at semantics, and no login/cart mutation/seller API. This is well beyond annotation coverage and does not contradict them.

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

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

The core operation is front-loaded in the first sentence, and the remaining sentences deliver useful caveats without obvious repetition. It is slightly dense but appropriately sized for the number of behavioral constraints.

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

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

Given an output schema exists, the description need not explain return values. It covers caching, coverage limits, price and stock semantics, timestamp meaning, and side-effect boundaries, leaving no major gap for calling this read-only offer list correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains that variant_id is an optional exact-match filter and that IDs come from get_product/search and should not be substituted, but it does not fully document product_id or format details beyond the schema's pattern.

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 seller offers') plus caching scope and optional variant matching. It distinguishes itself from broader seller tools by limiting coverage to offers in the current product response and warning against substituting sellers or similar variants.

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 clear usage context: IDs must come from get_product/search results, and variant_id must be an exact match, not a seller or similar variant. It also sets a coverage boundary by noting this is not all possible sellers, though it does not explicitly name compare_offers or list_product_sellers as alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact not in the annotations: the 60-second cache TTL, which tells an agent results may be stale. It does not discuss output shape or pagination, but with an output schema present that burden is reduced.

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 naming the action and resource, with the caching caveat appended. No filler, no 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 one-parameter read tool with an output schema, the description covers purpose and the notable caching behavior. The main omission is any routing guidance relative to get_product_recommendations, which would help but is not strictly required.

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

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

Schema description coverage is 0% and the description only gestures at the parameter via 'this product'. The required product_id, its numeric-string pattern, and any format expectations are left entirely to the schema, so the description adds no semantic 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 ('Read') and resource ('recommendation section keys for this product'), which is meaningfully distinct from the sibling get_product_recommendations. The noun 'keys' is slightly ambiguous (keys of a section list vs. section identifiers), keeping it short of a 5.

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 indication of when to use this tool versus get_product_recommendations or get_product_recommendations-adjacent siblings. The only conditional context given is a caching note, which is not usage 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 cover read-only and open-world safety, and the description adds genuinely useful traits beyond them: a 60-second cache, the fact that every variant stays separate, that lead time is not a delivery promise, and that coverage is not exhaustive. These are exactly the caveats an agent needs when interpreting 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?

Purpose is front-loaded in the first sentence, with caveats following compactly in two short sentences. No padding or repetition.

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 fields needn't be explained, and the description's caveats about caching and non-exhaustive coverage round out the picture for a simple one-param read tool. The only real gap is any mention of the required parameter.

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?

There is one required parameter (product_id) with 0% schema description coverage, so the description carries the full burden of explaining it — yet it never mentions the parameter or its numeric string pattern. Only one obvious param keeps this above a 1.

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+output shape: it groups variant offers by seller ID and returns rating, price, warranty and shipment metadata. This is clear enough to distinguish it from compare_product_sellers, though it never names that sibling 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?

The description describes behavior but gives no when-to-use guidance, no alternatives, and no exclusions. An agent is left to infer that compare_product_sellers is the comparison sibling rather than this listing tool.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description carries heavy extra load and delivers: token ephemerality, token scope ('scoped to this MCP process'), cookie handling ('upstream cookies remain private in memory'), and error semantics for OTP accounts. It adds real behavioral context rather than restating the mutation hint.

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

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

Four short sentences, front-loaded with the precondition ('Trusted backend only') before the outcome and the safety warning. Every sentence carries a distinct instruction or constraint with 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?

An output schema exists, so return values need no elaboration, yet the description still supplies the one return case an agent must branch on (challenge_required). Combined with the trust boundary and token-scope notes, an agent has everything needed to call this safely.

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, and it only gestures at parameters via 'password login' and the warning not to expose credentials. It does not clarify the nested credentials object, the writeOnly handling, or why username is formatted as a password. Partial compensation only.

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 ('password login') with a precise outcome ('returning an ephemeral opaque tool-session token') and an explicit audience constraint ('Trusted backend only'). An agent can distinguish it from logout_account and the cart siblings 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 clear when-to-use framing ('Trusted backend only') and a hard usage boundary (never expose credentials or the token to an LLM or user-visible log). It also pre-empts a common failure mode by stating that OTP accounts return challenge_required with no bypass or automatic retry. It does not explicitly name alternatives such as logout_account, so it falls short of a 5.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, a minimal safety profile. The description usefully adds the blast radius ('without affecting other accounts'), but says nothing about whether the session token is invalidated server-side, whether the action is reversible, or what auth state remains.

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 action front-loaded and the scoping caveat immediately after; every word 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?

An output schema exists, so return values need no explanation, and the safety annotations are thin. Still, the undocumented required token and the absence of any session-invalidation or permission detail leave gaps for an agent invoking a state-changing 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?

There is one required parameter (session_token) with 0% schema description coverage, so the schema supplies nothing. The description never mentions the token, where it comes from, or its format, so it fails to compensate for the schema 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 (discard) and resource (this host tool session), and the qualifier 'without affecting other accounts' scopes the effect. It is distinguishable from login_account and the cart siblings, though it does not explicitly name a contrasting 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?

The purpose implies the use case (ending the current host session) but there is no explicit when-to-use guidance, no prerequisites, and no statement of what to do instead if the intent is to log out other accounts.

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 substantial context beyond the annotations: five-minute token lifetime, that this call performs no remote mutation (mutation happens outside it), mandatory human approval of the plan, amount/unit caps, and token privacy including no keyring fallback. These are exactly the kind of constraints annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) cannot express.

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 compact lines, front-loaded with the identity and the safety constraint, then per-action requirements, then approval and token handling. Every clause carries information an agent needs; 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?

Despite a nested-object schema with zero param descriptions and an output schema that covers return values, the description supplies the action-conditional semantics, the approval gate, caps, and token lifetime. Nothing essential for correct invocation appears 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 0%, so the description must carry the load, and it does: it documents the conditional field requirements per action enum value (add/update/remove), which the schema's anyOf/default structure cannot convey. This is meaningfully more than the raw schema.

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

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

States a specific verb (prepare) and resource (token-account cart plan) and explicitly marks it as non-mutating ('no remote mutation'), which separates it from add_to_account_cart/update_account_cart_item siblings. It does not name prepare_cart_change (the likely non-account counterpart), so sibling differentiation is inferential rather than stated.

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 per-action requirements (add needs product_id + offer_id; update needs cart_item_id + final quantity; remove needs cart_item_id) and specifies the host must present and approve the exact plan before execution, implying the two-phase prepare-then-execute flow. It does not name the follow-up tool or explicitly say when to prefer this over the direct mutation tools.

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

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

Beyond the annotations it discloses that no cart mutation occurs, that a host approval gate follows, and that store text must be treated as untrusted display data — meaningful context for a tool in a prepare/approve/write flow. The only weakness is a mild tension with readOnlyHint=false: the description emphasizes 'without changing the store's cart', so an agent could reasonably infer a pure read, and the description never clarifies whether a pending operation record is created.

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 short lines: purpose first, then one line per action, then display/trust/approval rules. No sentence is redundant, and the front-loading means an agent grasps the non-mutating nature before reading the branching rules.

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-shape explanation is correctly omitted, and annotations already cover the safety profile. What remains — action routing, id provenance, quantity semantics, display obligations, untrusted-data handling, and the approval handoff — is all present, making the definition self-sufficient for correct invocation.

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

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

With 0% schema description coverage the description carries the whole burden and does it: it defines which fields belong to each action, where each id comes from (offer_id/product_id from get_product, cart_item_id from read_cart), and the critical semantic that quantity is the desired final value, not a delta. Format limits (patterns, max 999) are the only things left unsaid, and those are already encoded in the schema.

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

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

The opening sentence names a specific verb and resource ('Prepare a ... review plan') and immediately constrains scope ('without changing the store's cart'), which is exactly what separates it from the write siblings add_to_cart/update_cart_item/remove_from_cart. An agent can distinguish it from every sibling without opening a 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?

It routes per action: add needs product_id + offer_id from get_product and defers to update when the item is already in the cart; update needs cart_item_id from read_cart plus a final quantity; remove takes cart_item_id only, and zero quantity is explicitly rejected as a removal. It also states the downstream condition ('the host must approve the matching write tool'), so both when-to-use and when-to-hand-off are explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds genuine value beyond them by disclosing the auth constraint (only the token-bound account) and a forbidden fallback path, but it says nothing about errors, empty carts, or pagination.

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 no filler, and the scoping rule is placed first. It is structurally sound, though brevity shades into under-specification rather than optimal 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?

An output schema exists, so return-value explanation is not required, but the description still omits the resource being read and does not distinguish this tool from read_cart or get_account_cart_operation, leaving the account-scoping model unclear for a one-parameter, zero-coverage schema.

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

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

Schema description coverage is 0% and there is one required parameter, session_token, which the description never explains or characterizes. The baseline 4 for zero-param tools does not apply, and no compensating detail is provided.

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

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

The description implies a read operation scoped to the token's account, but never states the resource: it is the account's cart. With a sibling read_cart present, an agent cannot tell from this text what object is actually returned.

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?

"Never use the desktop keyring fallback" gives a clear negative constraint, which is useful. However, there is no positive when-to-use guidance and no explicit routing against the sibling read_cart, so the agent must infer 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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the auth requirement (local account login) and a privacy guarantee that no address, phone, cookies or payment data are returned.

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, zero waste, with the resource and the returned fields front-loaded and the auth/privacy caveats after. Nothing could be cut without losing 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 documentation is not required in the description. Combined with the annotations and the auth/privacy notes, this is nearly complete for a zero-parameter read tool; only the sibling disambiguation from read_account_cart 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?

The tool takes zero parameters, and the schema is fully described at 100% coverage, so the baseline of 4 applies. There is no parameter semantics the description needs to compensate for.

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 (read the connected account's cart) and enumerates what it returns (cart items, offers, unit prices, quantities). However, it does not distinguish itself from the sibling read_account_cart, which by name sounds like the same operation, leaving a real ambiguity for the agent.

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 states a prerequisite ("Requires local account login"), which is useful context. But it gives no when-to-use/when-not guidance and never clarifies how this differs from read_account_cart or the other cart readers, so selection among siblings is left to inference.

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

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

Annotations declare readOnlyHint=false, and the description correctly matches that by revealing the journal write, while adding genuinely new context annotations cannot express: it does not mutate the remote cart, does not steal an executing operation, and treats a matching cart as confirmation but not causal proof. That is a meaningful disclosure of scope and side effects 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?

The purpose is front-loaded and the three sentences are dense with real information. However, the 'Trusted backend:' prefix is jargon filler that adds no decision value, and the second half reads as terse internal notes rather than agent-directed guidance.

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

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

An output schema exists, so return values need not be described, and the annotations plus the description cover the safety/side-effect profile reasonably well. The remaining gap is parameter documentation at 0% schema coverage and no description of what session_token must contain.

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 two parameters, so the schema documents neither session_token nor operation_id beyond type/pattern. The description supplies no information about either parameter, so it fails to compensate for the coverage gap, leaving an undocumented operation_id format and auth token requirements.

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

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

The description names a specific verb pair (read back an uncertain operation, update its journal) and the resource (account cart operation), which is far more than a restatement of the name. It stops short of explicitly distinguishing itself from the sibling reconcile_cart_operation, relying on the name's 'account' qualifier to carry that differentiation.

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 implies the triggering condition — an 'uncertain account operation' — and gives one conditional branch ('An executing record needs operator investigation'), which is really behavioral guidance more than selection advice. It never says when to prefer this over get_account_cart_operation or reconcile_cart_operation, leaving the agent to infer the situation.

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 supply readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds the crucial side-effect scope (updates only the local journal), the negative guarantees (never replays mutations, never steals executing ownership), and the interpretation limit of matching contents. This is behavioral context the agent cannot get from structured fields.

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

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

Four short, front-loaded sentences; the primary action leads and each subsequent sentence adds a distinct constraint (journal-only write, no replay, matching semantics, operator escalation). Dense but every clause 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?

With an output schema present, return values need not be described, and the annotations plus description cover safety and side effects well. The remaining gap is parameter meaning for operation_id, which neither schema nor description supplies.

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% for the single operation_id parameter (pattern-constrained string), so the schema gives no meaning. The description conveys that an operation record is being reconciled and that 'executing' is a state such records can hold, but it never explains what operation_id identifies or how to obtain it.

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

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

States a specific verb (reconcile) and resource (a cart operation), and clarifies the mechanism: reads the cart but only writes the local journal. This clearly separates it from read-oriented siblings like read_cart and get_cart_operation, though it never names 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?

Establishes the triggering context ('resolve an uncertain operation') and gives a when-not rule ('Executing records need operator investigation'), telling the agent to stop rather than auto-reconcile. It stops short of naming an explicit alternative tool for the operator-investigation case.

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. The description usefully adds that host approval is required before execution, that no payment/checkout occurs, and that retries do not re-send mutations (reinforcing idempotency). This is meaningful context beyond the annotations, though it omits what specifically is destroyed or the effect on the cart state/limits.

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

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

Four short sentences, front-loaded with the action and the key constraint (host approval), then two follow-up facts. Efficient, though sentence fragments ('Trusted backend: DELETE...') reduce readability slightly.

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 explained. But with a destructive, open-world mutation operating on an account cart, the description should clarify the prepare/execute plan workflow, session_token origin, and what removal affects (e.g., cart totals or limits). Key context is left to the sibling tools to convey.

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 neither parameter is described in the description or schema. The description mentions an 'approved remove plan' which hints at plan_id's semantics, but session_token is entirely unexplained. For a mutation tool with two required undocumented parameters, 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 implies a DELETE-style removal from a cart, but the tool name is remove_from_account_cart and the description never explicitly states 'removes an item from the account cart.' It uses vague phrasing ('DELETE the exact item using this account's approved remove plan'), requiring the agent to infer the resource and action from the name. Siblings like remove_from_cart exist, and the description does not distinguish account-cart scoping from the regular-cart variant.

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?

'Requires explicit host approval' implies a prerequisite gating usage, and 'No checkout or payment' rules out a related operation. However, the description never explains when to use this tool versus prepare_account_cart_change, prepare_cart_change, or remove_from_cart, nor does it explain the plan_id lifecycle (prepare → execute → reconcile) that the sibling names strongly suggest.

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 real value beyond the annotations: the user-approval requirement, the over-limit allowance, the idempotency detail ('reusing plan_id never resends the write'), and a clear scope boundary ('does not cancel an order or make a payment'). These go beyond destructiveHint/idempotentHint, though the mutation's reversibility and error behavior remain unstated.

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

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

Four short sentences, front-loaded with the core action, then prerequisites, idempotency, and scope. No filler; each sentence 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?

With an output schema present, return values need no explanation, and the description covers the mutation's prerequisites, permission edge case, idempotency, and scope exclusions. An agent has enough to invoke it correctly.

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

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

Schema coverage is 0% for the single plan_id parameter, so the description carries the load. It does add meaning ('reusing plan_id never resends the write') and ties the id to an approved plan, but it never explains what a plan_id is or how to obtain one, leaving a real 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 and resource ('DELETE the exact cart item in an approved remove plan') and clarifies scope ('only removes from the shopping cart'), which implicitly separates it from remove_from_account_cart. It stops short of naming a sibling explicitly, so it is clear but not fully differentiated.

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 the prerequisite context (an approved remove plan, requires user approval) and a non-obvious permission ('removal is allowed even above the limits'). It does not name prepare_cart_change as the tool that produces the plan, so the workflow routing is inferred rather than 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?

Annotations already declare destructiveHint, idempotentHint and openWorldHint, yet the description adds non-obvious behavior: that it refreshes all offers before any removal, that explicit host authorization is required to clear the cart, and how to handle uncertain/partial write outcomes without blind resends. This is material context an agent could not derive from the structured fields.

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

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

Four sentences, front-loaded with the core action, then authorization, refresh behavior, retry semantics, and scope boundary in descending order of importance. Dense but no filler; each clause 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 values need not be described, and annotations cover the safety profile. The description supplies authorization, refresh, retry and scope context, leaving only the price-related parameter semantics under-explained for a zero-coverage nested schema.

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

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

Schema description coverage is 0% and the schema is nested (replacement.items[].product_id/offer_id/seller_id/expected_price_rial, max_total_rial). The description does explain request_id reuse for retries and implies one-unit-per-item semantics, but says nothing about max_total_rial or expected_price_rial's role as a price guard, so it only partially compensates 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?

States a specific verb and resource with scope ('Replace the connected user's entire cart with selected exact offers, one unit each'), which clearly separates it from add_to_account_cart/update_account_cart_item (incremental edits) and read_account_cart (read). No sibling is named explicitly, so differentiation rests on the phrase 'entire cart' rather than an explicit pointer.

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 real preconditions ('Trusted host must have explicit authorization for clearing this account's cart') and a retry policy ('Reuse request_id for retries; uncertain/partial outcomes never blindly resend writes'), plus an explicit scope exclusion ('No checkout/payment'). It does not, however, say when to prefer prepare_account_cart_change or reconcile_account_cart_operation over calling this directly.

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?

Goes well beyond the readOnly/openWorld annotations: budgets are IRR not toman, sorting is per market/page rather than global, page sizes/totals are upstream, errors are isolated per market, and location is unused by the current adapter. These are exactly the non-obvious traits an agent needs.

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?

Eight short, front-loaded statements with no filler; the most decision-critical facts (market scoping, category_id sourcing, query/category behavior) come first. Slightly list-like but every sentence carries operational value.

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

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

With an output schema present, return values need not be explained, and the description covers the market model, currency, sorting scope, error isolation, and the inert location parameter. Minor gaps remain around sort/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%, so the description must compensate. It clarifies query/category_id interplay, currency for price bounds, markets defaulting to all configured, and that location is inert. However it does not explain sort enum values, page bounds, or the filters structure.

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 ('Search products') and immediately scopes the unit of work ('one native page per market'), which an agent can act on. It also names siblings (list_categories, autocomplete) as the source of category_id, helping distinguish its role.

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

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

Explicitly tells the agent what inputs to supply ('query text, category_id, or both; category alone browses that category') and where to get category_id. Lacks explicit when-to-use-this-vs-get_products_batch routing, but the input-selection guidance is clear and actionable.

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 disclose destructiveness, idempotency, open-world behavior, and non-read-only status. The description adds substantial context beyond those annotations: host approval is required, quantity increases obey both caps, and retries never resend mutations. This directly addresses safe retry and mutation-scope concerns.

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 action and then the key constraints. Every sentence adds a distinct operational fact with no filler or repetition.

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

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

The description covers high-stakes mutation behavior well: approval, caps, retry semantics. But with 0% schema coverage, it is incomplete on parameter meaning, especially session_token and plan_id format, and it does not relate this tool to the prepare/reconcile siblings in the account-cart workflow. Output schema existence means return values need not be described.

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 adds some context for plan_id by calling it an 'approved update plan,' but it never explains session_token, plan_id format/pattern, or how the plan encodes the final quantity. The gap for a two-parameter mutation tool is significant.

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 (PATCH) and resource (final quantity via the account's approved update plan), making the action distinguishable from generic cart tools. It does not explicitly name a sibling tool or say how it differs from prepare_account_cart_change, keeping it short of a 5.

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 an explicit prerequisite: 'Requires explicit host approval' and implies use only with an approved update plan. However, it does not say when to choose this over siblings like prepare_account_cart_change, reconcile_account_cart_operation, or update_cart_item, nor does it state 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?

Annotations already flag this as destructive, idempotent and open-world, and the description adds substantial non-obvious behavior: increases are bound by both limits while decreases may exceed them, and reusing a plan_id suppresses the write even across restarts or timeouts. That idempotency/retry semantics is exactly the kind of context annotations cannot convey.

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

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

Four short sentences, each carrying distinct information (action, precondition, limit rules, idempotency), with the operation and approval gate front-loaded. 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?

An output schema exists so return values need no explanation, and the description covers preconditions, limit behavior and retry semantics. The only real omission is the provenance of plan_id (which sibling issues it), a minor but relevant 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%, so the description carries the burden for the single plan_id parameter. It implicitly characterizes plan_id as an idempotency key via the reuse semantics, but never states its format (32-hex) or where to obtain it, leaving meaningful gaps.

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 operation (PATCH the final quantity) against a specific resource (cart item) executed via an 'approved update plan'. It clearly implies the plan-based workflow, though it never names the sibling that produces the plan (prepare_cart_change) or distinguishes itself from update_account_cart_item.

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 a hard precondition: 'Never call without user approval', plus the requirement of an approved update plan. This is clear usage context, but no explicit when-not or named alternative sibling is provided, so it falls short of a 5.

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