shop

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

Annotations already mark the tool as non-read-only, non-idempotent, and non-destructive. The description adds genuinely new behavioral context: it guarantees no payment is taken, requires OAuth, and discloses the return payload (cart_id, contents, site link) in the absence of an output schema. This materially helps an agent set accurate expectations with the user. There is no contradiction with the annotations.

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

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

Three short sentences with the core action first, followed by return values and then caveats. Every sentence earns its place; there is no repeated schema content, filler, or redundancy.

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

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

For a moderate-complexity mutation with no output schema, the description covers the essentials: input format, return values, auth requirement, and the non-payment guarantee. Gaps remain around edge-case behavior (invalid variants, stock validation, whether repeated calls produce duplicates), which an agent might need when handling failures, but nothing required to make a correct first call 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 only 50% (cart_id is documented, items is not), and the description compensates in prose by framing the array as 'variant_id + количество' (variant_id + quantity), adding meaning to the otherwise undocumented parameter. Quantity constraints (min 1, default 1) and the merge behavior of cart_id still come only from the schema, and the description doesn't clarify what variant_id references or how quantities accumulate in an existing cart.

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 leads with a specific verb+resource: 'Собрать корзину' (build a cart) from a list of variant IDs and quantities, which precisely captures the operation. The clause 'Ничего не оплачивает' (pays for nothing) implicitly separates it from the payment/order sibling create_invoice_order. However, it never names or explicitly contrasts an alternative sibling, so differentiation from reorder, select_actuator, or suggest_accessories_for_cart 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 OAuth prerequisite and the explicit 'Ничего не оплачивает' caveat imply this is the pre-checkout assembly step, distinct from invoice/order creation. But there is no statement of when to choose this over create_invoice_order, reorder, or cart-adjacent tools, and no explicit exclusion criteria. Guidance is implied at best through the payment caveat.

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 (readOnly=false, idempotent=false, destructive=false, openWorld=false), and the description adds genuinely useful beyond-schema context: the OAuth requirement, the manager-review delay, an explicit 'do not pay before confirmation' warning, and the fact that the order is bound to the account email. This is more than the annotations already say, though it omits pagination/rate/duplicate-submission behavior for a non-idempotent create.

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 in the first sentence, followed by return values, workflow warning, fulfillment modes, and auth requirement. Sentences are dense but each carries a distinct fact; little is wasted.

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 usefully enumerates what is returned (order number, invoice status, page link) and flags the OAuth prerequisite, so return-value understanding is covered. However, given 11 parameters at 18% coverage, the description leaves the caller without enough field-level understanding 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 description coverage is only 18% across 11 parameters, so the description must carry the load, and it largely does not: inn, kpp, company, legal_address, contact, comment, and cart_id are never explained in the description. It adds meaning only for the delivery choice (pickup vs. carrier) and echoes the account-email rule, leaving most required/optional fields 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 and resource ('Оформить заказ и запросить счёт') and narrows the audience to legal entities and sole proprietors (юрлицо или ИП), which distinguishes it from generic cart/order siblings. It does not, however, explicitly name which sibling to use for other flows, so it falls just 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?

It supplies real prerequisites (requires OAuth login, invoice is prepared by a manager after review, do not pay before confirmation, pickup or carrier delivery by arrangement), which tell the agent how the tool behaves. But there is no explicit when-to-use vs. alternative routing (e.g. reorder vs build_cart vs this), so guidance is implied rather than comparative.

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 description goes beyond the annotations by disclosing a concrete side effect: it writes the city into the cart address. It also states the OAuth requirement, which is not present in the annotations. It stops short of describing output, rate limits, or failure behavior, so it is 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?

The description is three short sentences with no filler. It front-loads the purpose, then adds the side effect and auth requirement in logical order, making it easy to scan.

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

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

The description is sufficient for making a basic call with required parameters, but there is no output schema and the description never says what the tool returns, how to interpret the estimate, or how postal_code influences the result. That leaves a meaningful gap for an agent deciding whether the response satisfies the request.

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

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

With 0% schema description coverage, the description must compensate for parameter meaning. It clarifies that cart_id refers to the cart being evaluated and city is the delivery destination, but the optional postal_code parameter is completely unexplained. The agent gets no guidance on its format, purpose, or effect.

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—estimating delivery for a cart to a city—and names concrete delivery modes: pickup, store delivery, and transport-company tariffs. This clearly differentiates it from sibling tools like create_invoice_order or 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 intended use case is implied: call this when a delivery estimate for a cart to a city is needed. However, there are no explicit when-not-to-use instructions or named alternatives, so the agent is left to infer routing from sibling names.

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?

The description discloses non-obvious behavior beyond the annotations: it states that requested.qty is always 1 regardless of the line content, that the result includes variant_id for the cart, price or a 'need to choose variant' mark, and other suitable products. With annotations covering the safety profile, this adds useful operational context. It does not mention rate limits or error handling, but that is minor.

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

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

Three sentences, each with a distinct job: what the tool does, the critical qty caveat, and what the result contains. It is front-loaded and free of 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 no output schema, the description covers input format, a non-obvious behavioral caveat (qty=1), and the shape of the returned data, including the handoff to build_cart. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, so the description carries the full burden. It explains that the single 'text' parameter expects one line per position, with either an article number or a name, and that quantities are not parsed from lines. This compensates for the missing schema descriptions and tells the agent exactly what to supply.

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 — 'parse a specification or estimate' and 'verify against the catalog' — and it clearly distinguishes the tool from siblings like build_cart and search_products by explaining the input format (one line per position) and referencing build_cart as the follow-up. An agent can identify the tool's purpose without inspecting 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?

It explains the input expectation (text, one line per position — SKU or name) and directs the agent to pass quantity separately to build_cart because quantities are not extracted. It does not explicitly state when NOT to use this tool or compare alternatives beyond build_cart, but it provides clear context for its use.

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

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

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.