shop

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

The description adds useful behavioral context beyond the annotations: it returns cart_id, cart contents, and a customer link, and it explicitly states that nothing is charged. This partially compensates for the absence of an output schema and for the tool being a mutating operation without an idempotency guarantee.

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 cover the action, the inputs, the return values, and the key non-side-effect. Every sentence adds value and the most important information is front-loaded.

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

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

The description is reasonably complete for a simple cart-building tool: it defines inputs, outputs, and the important 'does not pay' boundary. It does not describe error cases or idempotency, but those are less critical given the simple two-parameter schema and the provided return summary.

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 main parameter, items, has no schema description, but the tool description explains exactly what it expects: a list of variant_id and quantity pairs. The optional cart_id has its own schema description ('Add to existing cart'), so combined coverage is adequate.

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

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

The description states the specific verb and resource: assembling a cart from a list of executions (variant_id + quantity). It also clearly distinguishes the tool from order creation by noting that it does not pay for anything and instead returns a buyer-facing cart link.

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

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

The description makes the core usage clear: build a cart from variant/quantity pairs and get a shareable link. It does not explicitly name sibling alternatives like create_invoice_order or suggest_accessories_for_cart, but the 'does not pay' note helps an agent decide between cart building and order/invoice creation.

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 are all false (readOnlyHint=false, etc.), so the description carries the burden of explaining mutation. It does state it creates an order and returns order number and invoice link. It also notes delivery is pickup or TC upon agreement, which is a conditional behavior. However, it doesn't disclose side effects like cart modification, idempotency, or failure modes, so it's adequate but not comprehensive.

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

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

The description is two sentences with no filler. The purpose is front-loaded, and the return value is stated. It is concise and structured effectively.

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

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

The tool has 11 parameters with 5 required and no output schema. The description covers the basic purpose and return but does not explain any of the required legal/business fields (INN, KPP, legal address), the meaning of dry_run, or any error handling. Given the tool's complexity, the description is under-specified.

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

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

Schema description coverage is only 9%, so the description must explain parameters. It only mentions cart_id (via 'корзине') and delivery (pickup/TC) but leaves the five required fields (company, inn, email, phone, cart_id) and other optional ones (kpp, contact, legal_address, comment) unexplained beyond their names. This is a significant gap given the low coverage.

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

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

The description states a specific action ('Оформить заказ' – place an order) on a specific resource ('корзине' – cart) with payment method and target audience. It clearly distinguishes itself from siblings like build_cart (builds cart) and get_order (reads order) by focusing on creation for legal entities/IE with invoice payment.

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

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

The description provides context: for legal entities/IE without registration, with payment by invoice. This implies the use case and differentiates from other tools that might require registration or other payment methods. However, it doesn't explicitly name alternative tools or state when not to use this tool, so it's clear but not fully explicit.

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

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

Annotations are all false, so the description carries the burden of telling the agent whether the tool has side effects, requires prerequisites, or is safe to call. It only lists delivery options and the conditional availability of carrier tariffs; it does not disclose whether an order or quote record is created, whether pricing is final, or what happens if the cart/city is invalid.

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 efficient sentence that front-loads the main action and then adds the key delivery modes and the carrier condition. No filler is present, though it could be slightly more structured for readability.

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

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

For a tool with three parameters, no output schema, and unhelpful all-false annotations, the description is too sparse: it lacks return-format expectations, side-effect clarity, prerequisites, and parameter details. An agent would likely need to call the tool or inspect external docs to use it confidently.

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

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

With schema description coverage at 0%, the description must compensate. It maps 'корзина' to cart_id and 'город' to city, but adds no format or meaning beyond the schema property names, and postal_code is entirely undocumented in both the schema and 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 opens with a specific verb and resource: assessing delivery of a cart to a city, listing pickup, store delivery, and carrier tariffs. This clearly distinguishes it from order-creation or product-retrieval siblings such as create_invoice_order and get_product.

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

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

The intended use is implied by the phrasing — estimate delivery for a cart to a city — and the conditional note about transport companies adds context. However, there is no explicit statement of when to choose this over alternatives or when not to use it, such as during checkout or before building a cart.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral details beyond annotations: batch limit of 100, exact matching, case insensitivity, and the specific fields returned. This contextual enrichment is valuable and consistent with read-only behavior.

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

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

The description is a single, information-dense sentence without filler. The key capability ('exact search') is front-loaded, followed by constraints and return fields. Every word adds value, achieving high conciseness without sacrificing clarity.

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

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

For a tool with one parameter and no output schema, the description covers essential expectations: input constraints (up to 100, case insensitive), matching behavior (exact), and output fields (variant_id, product, price). Missing details like pagination or error formats are minor given the batch cap and read-only nature. It is sufficiently complete for correct invocation and interpretation.

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 must fully explain the single `skus` parameter. It does: lists of SKUs, up to 100, case insensitive, and the exact-match semantics. It also explains what the result will include, giving the agent a clear understanding of input and output. While it doesn't detail SKU format, it sufficiently compensates 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?

The description clearly states the tool performs an exact search for variants by SKUs, and explicitly lists the returned fields (variant_id, product, price). This distinguishes it from sibling tools like search_products (likely fuzzy) and get_product (single item). The resource and operation are specific and unambiguous.

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

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

The phrase 'exact search' implies this is for precise batch lookups, contrasting with broader search tools, but it does not explicitly name alternatives or state when not to use it. The sibling list includes search_products, which suggests an alternative, but no direct guidance is given. Context is clear, but exclusions are absent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it requires OAuth login and restricts access to the logged-in customer's own order. No contradiction found.

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

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

The description is two short sentences, front-loaded with the core purpose and followed by a required authentication caveat. No filler or redundancy.

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

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

Given a single parameter, no output schema, and annotations covering safety, the description provides sufficient call context: authentication, scope, and a preview of returned fields. It omits error-handling details (e.g., not found or unauthorized), but these are minor for a straightforward read operation.

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

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

With 0% schema description coverage, the description compensates well by explaining the order_id format ('order_…') and its semantic role (id of the order). This is essential for the agent to construct valid requests.

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

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

The description clearly states the resource (an order), the action (get status), the scope (logged-in customer), and the content returned (composition, amount, payment, shipment). It specifies the id format ('order_…'), which helps distinguish it from order-listing tools, though it does not explicitly name sibling tools.

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

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

The description implies usage when you have a specific order id and are logged in via OAuth. It does not explicitly contrast with alternatives like my_orders (listing orders) or provide when-not-to-use guidance. The 'by id' phrasing gives context, but no direct 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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds some return-value context (characteristics, variants, prices, SKUs) but does not mention response shape, errors, or any other behavioral details.

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

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

One compact sentence, front-loaded with the tool's purpose and contents. The opening 'Карточка товара:' partly repeats the title, but the rest of the sentence earns its place by listing what the response includes.

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, read-only lookup, the schema plus annotations cover the call contract and safety profile, and the description covers the return scope. The only missing element is explicit routing guidance relative to find_by_sku and search_products, which is more of a usage concern.

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

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

The input schema has 100% coverage for the single 'id' parameter, documenting it as 'id товара (prod_…) или handle'. The description does not add extra parameter semantics, but the baseline of 3 applies because the schema already carries the full meaning.

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

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

The description states the resource (product card) and its key contents: characteristics, variants, prices, and article numbers. This is specific enough to distinguish it from search/recommendation tools, though it never explicitots the 'get' verb and does not name a sibling 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?

Usage is only implied: the tool name and the required 'id' parameter suggest it is used when you already have a product id or handle. The description gives no explicit guidance about when to prefer get_product over find_by_sku or search_products, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scoping context about 'same diameter' and example accessory types, but says nothing about empty results, product-id handling, pagination, or response shape. No contradiction with annotations.

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

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

The description is one compact sentence with useful parenthetical examples and no filler. It is slightly fragmentary in Russian, but it is appropriately brief for a one-parameter read-only 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?

For a low-complexity tool, the description covers the broad return content and identifies the target product. However, it omits usage-selection guidance and any output-structure detail, and there is no output schema to compensate. Adequate but with clear gaps.

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

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

The schema has 0% description coverage for product_id, and the description only refers to the parameter obliquely as 'к товару' (to the product). It conveys that recommendations are anchored to a product, but it does not explain the expected format, how to obtain a valid product_id, or any 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?

The description states the resource clearly: similar products and same-diameter accessories (flanges, filters, actuators) for a product. The operation is implied by the tool name 'get_recommendations' and is understandable, but the description does not explicitly differentiate it from siblings like suggest_accessories_for_cart.

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

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

No guidance is given about when to use this tool versus alternatives such as suggest_accessories_for_cart or search_products. The description only implies 'for a product' as the trigger, but no exclusions or decision rules are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the result is a tree and includes addresses, which gives some behavioral/return-shape context beyond the annotations, but it does not disclose pagination, depth limits, or language/locale behavior.

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

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

The description is a single short sentence with no filler. It communicates the core concept and the key return characteristic (tree with addresses) without wasting words.

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

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

For a zero-parameter, read-only, idempotent tool, the description is mostly sufficient: it names the resource and indicates the response shape as a tree. The main gap is ambiguity around what 'addresses' means and lack of detail about response formatting, but the tool's simplicity lowers the 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 tool has zero parameters, so parameter-level ambiguity is not a concern. With no parameters, the description does not need to explain parameter semantics, and the schema already documents an empty property set.

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 describes a catalog section tree with addresses, clearly indicating the resource and its hierarchical structure. The verb 'list' appears in the tool name, and the title reinforces the resource, so purpose is unambiguous. It does not explicitly differentiate from siblings, but none of the siblings obviously overlap with listing catalog categories.

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

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

There is no guidance about when to use this tool versus alternatives, no context about browsing/catalog workflows, and no mention of exclusions or prerequisites. The agent must infer usage solely from the name and title.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the OAuth requirement, which is an important behavioral constraint not present in the annotations. It does not contradict any annotation, and it clarifies the read-only nature by describing returned information.

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

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

Two sentences with zero wasted words. The most important information (what is returned) is front-loaded, and the OAuth requirement is stated succinctly at the end. 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?

With no output schema, the description appropriately lists all the return aspects (balance, status, level progress, available write-off) and states the auth prerequisite. The optional parameter is documented in the schema, and the tool is simple enough that no further behavioral details are needed 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 coverage is 100% and the schema description for cart_total_rub already explains it as the order amount to calculate available write-off. The tool description mentions the parameter indirectly but adds no new meaning beyond the schema. Baseline 3 is appropriate since the schema carries the semantic load.

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

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

The description clearly enumerates the specific data returned (bonus balance, customer status, progress to next level, and available discount for a given order amount), making it unambiguous that this is a read-only loyalty query. It is easily distinguished from siblings like my_orders or build_cart, which deal with orders or cart operations.

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

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

The description clearly states what the tool does and that OAuth login is required, which gives an agent strong context for when to invoke it. It does not explicitly name alternatives or say 'use this instead of X', but the purpose is so distinct from the sibling tools that the usage context is clear without exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral context: it requires OAuth authentication and reveals the output fields returned. No contradictory or misleading behavior is stated.

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

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

The description is two short clauses with no filler. The core purpose is front-loaded, followed by the auth requirement and field list – 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?

For a simple read-only list tool, the description explains who the data belongs to, what fields are returned, and the auth precondition. It doesn't mention limit semantics, but the schema provides type/range and the tool is otherwise simple enough that no major context is missing.

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

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

Schema description coverage is 0%, so the description should compensate for parameter semantics, but it never mentions the `limit` parameter or its effect. The schema's type/constraints are not enough on their own; the description adds zero value here.

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

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

The description clearly identifies the resource (orders of the logged-in customer) and enumerates the returned fields (number, date, amount, payment, shipment, invoice link). This distinguishes it from siblings like get_order (single order) and my_loyalty.

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

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

The phrase 'вошедшего покупателя' sets the usage context: this is for the current authenticated user's order list. It also mentions the OAuth requirement. However, it does not explicitly name alternative tools or state when not to use it, 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral detail: it cross-checks against the catalog, returns per-line matches, provides variant_id and price, and signals items that still require an execution/option to be chosen. No contradiction with annotations was found.

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 dense sentence conveys the input format, the catalog-matching behavior, and the output semantics without wasted words. The purpose is front-loaded, and every clause adds necessary 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?

There is no output schema, so the description reasonably carries the burden of explaining results: per-line found items, variant_id for cart, price, or the 'need to choose execution' marker. It is complete enough for an agent to call the tool and understand the response, though exact JSON shape and not-found behavior are not spelled out.

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

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

The input schema has no description for the required 'text' parameter, and schema coverage is 0%. The description compensates by explaining the expected text structure: one line per position with article or name and quantity. While it doesn't give separator or formatting examples, it provides the essential meaning that the schema itself lacks.

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

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

The description uses a specific verb ('parse') and clear resource ('specification or estimate'), and explains exactly what happens: each line is matched against the catalog and returns per-line findings. This distinguishes it from related tools like find_by_sku and search_products, which operate on single items rather than full spec text.

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

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

The description gives clear context for when to use this tool: when the user provides a specification or estimate as multi-line text with article/name and quantity per line. It also implies the result feeds cart selection via variant_id. However, it does not explicitly mention when not to use it or name alternative tools for single-item lookup.

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

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

Beyond the generic annotations, the description discloses that the action returns a cart link, does not trigger payment, and requires OAuth authentication. It does not mention whether multiple calls create multiple carts or how the current cart is affected, but it does add meaningful 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?

Three short sentences, each earning its place: the core action, the return/non-payment behavior, and the authentication prerequisite. The most important information is front-loaded.

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

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

With a single parameter fully documented in the schema and no output schema, the description supplies the missing behavioral and return-value information (cart link, no payment, OAuth). No critical detail needed for invoking the tool correctly is absent.

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

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

Schema coverage is 100% and the sole parameter is already well documented in the schema as an order ID from my_orders. The description adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description states a specific action (assembling a new cart) and a precise source (items from a previous order), and clarifies the non-payment outcome. This distinguishes it from siblings like build_cart (building from scratch) and create_invoice_order (payment-focused).

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 intended context is clear: use this when a user wants to rebuild a cart from an earlier order. It does not explicitly name sibling alternatives or state when not to use it, but the phrase 'из позиций прошлого заказа' provides enough contextual 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 mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by scoping the catalog domain and by disclosing the parser's understanding of DN/PN expressions, which is not visible in the schema or annotations.

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

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

A single sentence delivers both the domain scope and an illustrative query example with no filler. Every part earns its place, and the most distinctive capability, natural-language search with Ду/Ру, is presented clearly.

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

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

For a two-parameter search tool with strong annotations, the description supplies enough domain and query-language context for an agent to invoke it correctly. It does not describe result format or pagination, but with no output schema this is a minor gap rather than a blocker.

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 query parameter already has a Russian-language description in the schema, and the description extends it with a concrete DN/PN example («затвор ду 50 ру 16»). The limit parameter has no schema description, but its name, default, and bounds make its meaning sufficiently self-evident.

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 action (поиск по каталогу) and a concrete resource (инженерная сантехника) with product categories, clearly distinguishing it from exact-lookup siblings like find_by_sku or get_product. The DN/PN example further pins down what kind of search tool this is.

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

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

The description implies use for natural-language Russian catalog queries, especially with Ду/Ру specifications, but never explicitly says when to choose search_products over siblings such as find_by_sku, list_categories, or get_product. No exclusions or alternative routing 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 mark the tool read-only, idempotent, and non-destructive. The description adds value by disclosing the output characteristic ('returns actuators with torque margin') and the fallback behavior when torque is missing. No contradiction with annotations.

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

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

Two sentences, front-loaded with the purpose, with zero filler. The conditional is placed as the closing sentence. Efficient.

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

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

Given no output schema, the description adequately describes the return (suitable actuators with torque margin, or typical variants). It covers the primary input conditions and the fallback. Minor gap: no mention of how results are formatted or whether filtering by voltage/flange is required, but these are in the schema. Complete enough for the tool's complexity.

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 80%, so the schema documents most parameters. The description adds cross-parameter guidance: diameter is the key fallback parameter when torque is unknown, and it clarifies that torque is optional in practice. This is meaningful but modest, so 4.

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 action ('подобрать привод' – select an actuator) and the exact resource class (electric/pneumatic actuators for valves, gates, and sluices) plus the selection criteria (DN, torque, ISO flange). This clearly distinguishes it from the broader product-search and recommendation siblings.

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

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

The description implies usage: when the user needs an actuator matched to a valve. It adds a conditional workflow (if torque unknown, provide DN only) which is guidance on how to use it. However, it does not explicitly exclude sibling tools or say when to prefer this over get_recommendations/suggest_accessories_for_cart, so it earns 4 rather than 5.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds important behavior: it returns ready-made strings with quantities (not just recommendations), and it details a specific counting rule for flanged fittings. This adds value beyond the annotations, though it doesn't mention any side effects (none expected given annotations).

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

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

The description is two sentences with no fluff. It front-loads the purpose, then adds a crucial counting rule that affects output. 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?

For a read-only, idempotent tool with one well-documented parameter and no output schema, the description provides enough context: what it does, how to use the output, and a special rule. It lacks examples of output format, but given the simplicity and annotations, it's sufficiently complete.

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

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

Schema coverage is 100%, so the single parameter 'cart_id' is well-documented. The description references cart_id indirectly by mentioning 'позициям корзины' and 'build_cart', but it doesn't add new information about the parameter beyond the schema. Thus, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: suggesting add-on items for cart positions, with a specific verb 'suggest' and resource 'accessories_for_cart'. It distinguishes itself from siblings like 'get_recommendations' and 'select_actuator' by focusing on cart-specific accessories and providing ready-to-use strings for 'build_cart'.

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

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

The description implies usage: it should be used when the user has a cart built via 'build_cart', and the output can be directly fed back into 'build_cart'. It also gives a specific rule for flanged fittings, which acts as a usage guideline. However, it does not explicitly say when NOT to use it or mention alternatives.

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