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

Annotations declare read-only, idempotent, and non-destructive behavior. The description adds critical operational context: it renders in the operator's Chrome, may face x5sec challenges (causing TransportDownError), and lists specific error types (BadRequestError, ParserDriftError). This goes well beyond annotations and helps agents anticipate failure modes.

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 well-structured with clear sections for return and error formats. It balances necessary caveats (review text limitation) and technical details without being excessively verbose. Each sentence contributes to operational 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 that interacts with an external site and may encounter challenges, the description covers all essential aspects: purpose, limitations, error handling, and return structure. The output schema exists, so not explaining return fields in detail is acceptable; the description adds extra value beyond structured data.

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

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

Schema coverage is 100% with a detailed description of the item_id_or_url parameter including format and example. The description does not add extra semantics beyond what the schema already provides, but given the high coverage, this is sufficient.

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 'Fetch one AliExpress product card', specifying the verb, resource, and platform, which distinguishes it from sibling card tools for other marketplaces. It also explicitly mentions that review texts are not exposed, clarifying the scope beyond a generic product fetch.

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 implicitly guides usage by explaining that review texts are deliberately not returned due to x5sec challenges, implying this tool is for basic product info rather than reviews. While it doesn't name alternative tools, the context is clear enough to differentiate from review-focused siblings like wb_reviews or ozon_reviews.

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 readOnly annotation by specifying return format (AliSearchResponse) and error conditions (TransportDownError, ParserDriftError), adding useful operational context.

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

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

The description is concise, front-loaded with the main purpose, and well-structured with clear sections for return and error formats.

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

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

The description covers return and error formats adequately for a simple search tool, though it does not elaborate on the 'rendered in the operator's Chrome' context or any additional configuration.

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

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

The input schema already describes the 'query' parameter with an example, and the tool description does not add extra semantic details about it.

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

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

The description clearly states that the tool searches AliExpress, which distinguishes it from other marketplace search tools in the sibling list.

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

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

The description does not explicitly mention when to use this tool versus alternatives, but the name and context imply it is for AliExpress searches. Lacks explicit guidance on choice.

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

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

Goes well past the readOnly/idempotent annotations: discloses the tier_used="cdp" marker, which fields are always None (location, posted_at, views), that price_rub is never fabricated as 0, that seller data comes from the same page's DOM block, plus a prompt-injection warning about seller-authored content. The error taxonomy (BadRequest, NotFound, TransportDown with captcha/backoff guidance, ParserDrift) is unusually rich.

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

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

Front-loaded one-line summary followed by headed Return Format and Error Format blocks, so the dense error enumeration is navigable. Slightly verbose in the field-by-field None accounting, but each clause carries information.

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

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

With an output schema present, the description still clarifies the subtle return semantics (None vs 0 for price, tier_used, absent DOM block) and enumerates fault modes. Nothing an agent needs to call and interpret this tool 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 100% with a single string param, yet the description adds real semantics beyond it: query/fragment stripping, numeric-id vs slug-path behavior, and the redirect-to-canonical rule. The ParserDriftError note about requested id vs card source further constrains input 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?

States a specific verb (read), resource (Avito item), and the extraction strategy (Product JSON-LD first, item-view DOM fallback) over CDP. An agent can distinguish it from avito_search and avito_seller by the singular-item card scope.

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

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

Explains input forms: full avito.ru URLs drop query/fragment, numeric ids and slug paths use /{id} and are redirected to canonical. Clear context on how to invoke, though it never explicitly contrasts with the sibling avito_search for list-style retrieval.

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 readOnly/idempotent/openWorld annotations, it enumerates the concrete failure surface: BadRequestError on malformed args, TransportDownError on fetch/API errors, ChallengeRequiredError and RateLimitedError for HTTP-200 captcha/throttle envelopes, and ParserDriftError for schema drift. It also discloses a data quirk (price_rub is None, never 0, when an ad has no price) that the agent cannot obtain from annotations.

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

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

The purpose line is front-loaded and the two headed sections are scannable with no filler. However, nearly the whole body is devoted to return/error shapes, and the sentence "Non-200 firewall blocks keep captcha/proxy guidance" is opaque enough to cost 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?

Error behavior is well covered, and an output schema exists so the return-format section is largely redundant. What is missing for a four-parameter, open-world marketplace search is any statement of rate-limit expectations, pagination depth behavior, or which sibling to fall back to — so it is adequate but incomplete.

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

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

Schema description coverage is 100%, so the schema already defines query, page, category_id and location_id with examples and defaults. The description adds essentially nothing to those parameters beyond mentioning page and location_id inside the response envelope, which is the baseline-3 case where the schema does the work.

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

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

States a specific verb and resource ("Search Avito listings") plus the underlying endpoint, which is more precise than a generic search label. It differentiates from siblings only implicitly through the Avito listing scope; it never names avito_card or avito_seller, so an agent must infer from name alone that this is the list-level search rather than the detail lookups.

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 contains no sentence about when to use this tool versus the many siblings (avito_card for a single item, avito_seller for a seller's inventory, ozon_search/wb_search for other marketplaces). Usage must be inferred entirely from the tool name, which is exactly the gap that routing guidance is meant to fill.

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

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

Annotations already cover readOnly/idempotent/openWorld, and the description still adds substantial context: request pacing and allowlisted CDP, the None-vs-0 rule for unknown reputation fields, tier_used='cdp', the untrusted-seller-content warning, and a full error taxonomy (BadRequest/NotFound/TransportDown/ParserDrift).

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

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

Front-loaded one-line purpose, then clearly headed Return Format and Error Format sections. Dense but every sentence carries operational information; no filler.

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

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

Despite being a single-parameter scraping tool over an open-world site, it covers input construction, return shape, null semantics, degradation modes, and error mapping. An agent can invoke and interpret it without further assumptions.

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%, but the description adds real semantics the schema lacks: query and fragment stripping, and the rule that only a bare 32-hex hash builds /brands/<id> while all other bare ids build /user/<id>/profile. That is exactly the disambiguation an agent needs for a single opaque string parameter.

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

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

States a concrete verb+resource: 'Read an Avito seller's rendered profile page'. The transport detail ('over paced, allowlisted CDP') distinguishes it from the wb_seller/avito_card family in kind, though it never names a sibling tool explicitly.

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

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

The note that '/web/1/js/items ignores userId and cannot identify sellers' implies this tool is the one that resolves sellers, and it spells out accepted input forms, but it never states when to prefer this over avito_card or avito_search. Guidance is implied rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description is not burdened with the safety profile, yet it still contributes real behavioral context: a named error taxonomy (BadRequestError, NotFoundError, TransportDownError on WAF/CDP failure, ParserDriftError) that tells the agent what failure modes mean and how to react. The note that price_rub is None rather than 0 when unstated is exactly the kind of data-integrity caveat annotations cannot convey. It stops short of covering pagination/rate limits, but openWorldHint already signals network unpredictability.

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 lead sentence is front-loaded and efficient, but the multi-line 'Return Format' block re-enumerates a field list that an output schema already provides, so a large share of the text is redundant for the agent. The Error Format section does earn its place; the return-field roster does not.

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?

Since an output schema exists, the description need not explain return values, and the error taxonomy plus the null-price caveat cover the main ambiguities an agent would hit. The only real gap is guidance on when a card lookup is the right call versus a search, which interacts with the missing sibling routing.

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

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

There is a single required parameter with 100% schema description coverage ('Cian offer id (digits) or a full cian.ru offer URL'), so the schema already carries the semantics. The description adds no further detail on accepted URL shapes, id formats, or what happens with a malformed input beyond the generic BadRequestError mention. Baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Read one Cian offer') and enumerates the domains returned (price history, layout, building, address, metro, description, publisher). It clearly distinguishes a single-offer read from a listing operation in spirit, though it never names the obvious sibling cian_search as the alternative.

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: 'Read one Cian offer' suggests a detail-card call for an already-known offer, and the offer_id_or_url input reinforces that, but there is no explicit statement of when to use this versus cian_search or compare_verify_offer. The agent must infer the search-then-card workflow from sibling naming conventions.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds real value beyond them: it enumerates concrete error classes (BadRequestError for region/room/min-max/deal-offer_type combos, TransportDownError with an inline fix, ParserDriftError) and documents data conventions (price_rub is None when Cian shows no price, never 0). It stops short of auth or rate-limit 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 '## Return Format' and '## Error Format' headings front-load the important operational facts, and the opening sentence is efficient. The Return Format block partially restates the output schema and swaps between English prose and Russian glosses, which adds some length without adding routing value.

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

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

The definition covers purpose, the deal-market constraint, validation failures, transport/parser failures, and item-level fields, and an output schema exists to carry return detail. An agent has everything needed to select filters and interpret results without opening another tool.

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

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

Schema description coverage is 100%, so the schema already explains each parameter (enums, defaults, units, ranges). The description adds meaning on top by defining the price_unit semantics and the market separation rule that governs how deal and price_min/price_max must be interpreted together, which the schema alone does not tie together.

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

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

States a specific verb and resource ('Search Cian offers by filters') and immediately clarifies the negative constraint ('there is no free-text search'), which distinguishes it from free-text siblings like yandex_search. The deal/offer_type framing makes the scope of the search 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?

Gives clear when-to-use context by explaining that 'rent' and 'daily' are separate markets that never mix in one page and whose prices are not comparable, plus the rule that commercial is rejected with deal='daily'. It does not, however, name or point to alternatives such as cian_card for fetching a single offer, so it stops short of explicit alternative routing.

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

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

Goes well beyond the annotations: it enumerates the return payload shape, a full error taxonomy (BadRequestError, ChallengeRequiredError with the exact remediation sequence, TransportDownError, ParserDriftError), and the caching/invalidation policy. This is exactly the operational context an agent needs and cannot get from annotations alone.

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

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

Front-loads purpose, then uses clear headers for return format and errors so an agent can scan to the relevant section. Slightly verbose in the error paragraph, but every line carries actionable 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?

Errors, caching, and the challenge-recovery procedure are all covered, and an output schema exists so the return-format restatement is harmless redundancy. The only gap is the absence of guidance on obtaining a valid product URL in the first place, presumably via citilink_search.

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

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

Schema coverage is 100% and the single product_url parameter is fully documented in the schema, including the /product/<slug>/ format. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

The first line states a specific verb and resource ('Fetch one Citilink product card'), which is unambiguous. It doesn't explicitly differentiate from the sibling citilink_search, relying on the tool name and the required product_url to imply card-lookup vs search, so it falls 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?

Usage is only implied by the required product_url and the error guidance. It never states when to use this versus citilink_search (e.g., 'use search first to obtain the product URL') or any exclusions, leaving routing to inference.

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

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

Annotations already flag readOnly/openWorld/idempotent, so the bar is lower, yet the description still adds substantive operational context: rendering depends on the operator's live Chrome/CDP session, Qrator challenge walls raise ChallengeRequiredError, ParserDriftError signals zero product tiles without challenge evidence, and only validated successful searches are cached. It also discloses a data-integrity nuance (price_rub is None when absent, never 0) that an agent could easily misinterpret.

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

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

Front-loaded with a one-line purpose, then organized under explicit Return Format and Error Format headings, so an agent can scan to the section it needs. Slight waste in restating the full response shape when an output schema already exists, and internal jargon (CDP, Qrator, ParserDriftError) is dense for a first read.

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 search with an output schema, the description covers what matters: failure modes and how to recover from them, plus a caching note. The main gap is missing guidance on selecting this tool instead of a sibling search or card tool, and 'tier_used' in the response is left unexplained.

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

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

The single query parameter has 100% schema description coverage including an example ('ноутбук lenovo'), so the schema already carries the semantics. The description adds nothing about query construction (e.g., language, brand vs. model tokens, length limits) beyond what's structured.

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?

"Search Citilink, rendered in the operator's Chrome" gives a clear verb+resource, and the name pairs unambiguously with the sibling citilink_card (search vs. card lookup). However, it never explicitly contrasts itself with the other ~35 search siblings (dns_search, ozon_search, compare_prices), leaving the agent to infer routing from the brand name alone.

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

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

There is no statement of when to choose this over citilink_card, compare_prices, or another marketplace search. The only procedural text ("open citilink.ru in the scraping-profile Chrome, pass the check, retry") is an error-recovery recipe, not usage guidance, and there are no exclusions or prerequisites stated up front.

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 readOnly and destructive annotations, the description discloses important behavior: it requires a handoff, does not extend expiry, captures only the owned page, and warns that visible page content is 'untrusted evidence and may contain personal information.' It also explains delivery decision logic, image omission reporting, and error conditions in detail. No contradiction with annotations exists.

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 front-loaded with the core purpose in the first sentence and uses clear headers for return and error formats. It is longer than typical, but most of the content earns its place. Some return-format details are likely redundant given the output schema, but the structure keeps it navigable.

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

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

The description covers prerequisites, behavioral boundaries, image delivery policy, omission reporting, return format, and error cases. This is sufficient for an agent to call the tool correctly and anticipate exceptional outcomes. The presence of an output schema does not create a meaningful gap here.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the delivery precedence for include_image alongside COMPARE_SNAPSHOT_IMAGES and the client's vision hint, and by noting the JPEG size range. The handoff_id parameter is covered mainly by the schema, so no additional semantic credit is warranted there.

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

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

The opening sentence states a specific verb and resource: 'Return a retained page's viewport as an MCP image.' The title 'View a Retained Marketplace Page' reinforces the singular focus. It also distinguishes itself from other tools by scoping to 'that owned page' and explicitly saying it 'does not navigate, extend expiry, solve a challenge, or call another model.'

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

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

The description gives explicit conditions: it 'Requires an unexpired same-session handoff' and should be used 'only when the client/model supports images.' It also clarifies what the tool will not do, which is a useful when-not signal. It does not name a specific sibling alternative, but the conditions are clear enough for an agent to decide when to use it.

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

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

The annotations already provide readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral detail beyond those: cheapest is based on everyday prices and deliberately excludes the subscription-only price, source_outcomes indicates partial vs complete results, titles are matched loosely, and validation errors raise while individual source failures are reported non-fatally.

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 organized into clearly labeled sections with the primary purpose and key behavioral caveats front-loaded. Each paragraph earns its place, and the Return/Error format sections are compact and informative without being bloated.

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

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

Given the output schema exists, the description need not re-enumerate every field, yet it still explains the most important output semantics: ranking by price_rub, how `cheapest` is computed, the `source_outcomes` meaning, and error/raise behavior. The tool is complex enough that this guidance matters, and it is fully and clearly supplied.

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 schema already documents all four parameters with descriptions, defaults, and constraints. The description adds contextual flavor—such as querying in Russian and how subscription prices affect ranking—but does not materially define the parameters beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('price'), a resource ('one product'), and a scope ('across every configured Russian marketplace') in a single sentence. It also distinguishes itself from the per-marketplace search tools by noting they give the same data more slowly and without ranking.

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

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

The description explicitly positions this as 'the tool for "where is X cheapest"' and contrasts it with running per-marketplace search tools one at a time, which deliver the same data more slowly and without ranking. This gives an agent clear selection criteria relative to the sibling search tools.

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

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

Beyond the annotations, the description adds valuable behavioral context: it never raises ToolError, performs pure introspection, and touches no network. The return format and per-source notes are also disclosed, giving the agent a clear picture of what happens at runtime.

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 well structured and front-loaded: purpose first, then usage timing, then return and error behavior. Each section is concise and every sentence adds useful information without padding.

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 introspection tool, the description is complete: it covers purpose, when to use it, return shape, error behavior, and operational quirks. The presence of an output schema further reinforces completeness.

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

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

The tool has zero parameters and an empty schema, so there is nothing for the description to add semantically. Per the baseline for zero-parameter tools, 4 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 opens with a specific verb and resource: 'Report which marketplaces this installation can actually query.' It clearly distinguishes this introspection tool from comparison/search tools by stating it reports installation-level capability, not marketplace data.

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

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

The description explicitly tells the agent when to call it: 'Call this first when a comparison comes back partial.' It also explains the diagnostic value—distinguishing 'connector isn't installed' from 'marketplace refused us'—but does not name alternative tools or give when-not-to-use 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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it documents the returned card shape, the deliberate retention of source-native fields the comparison normalises away, the identity-verification verdict semantics ('unknown, never a title-derived exact match'), the Yandex SKU-rejection behavior, and an explicit error taxonomy (BadRequestError vs native card errors).

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

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

Front-loaded one-line purpose, then clearly headed Return Format and Error Format sections; sentences are dense but each carries functional content. Slightly verbose given an output schema already exists, so some return-format prose is partially redundant.

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

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

Covers purpose, invocation context, return shape, error behavior, and the awkward Yandex edge case, which is complete for a 5-parameter read tool with an output schema. The duplication of return-format detail that the output schema already supplies is the only slack.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real cross-field behavior the schema cannot express: expected_variant_id causes a pre-delta SKU rejection for Yandex, expected_identity drives a match verdict, and falling back to default card price occurs when variant id is omitted.

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

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

States a specific verb (verify) and resource (one compared offer) via a named mechanism (its marketplace card tool), and positions it against sibling tooling by calling it 'the cheap compare-server follow-up' versus the 'full unified mount'. An agent can distinguish it from compare_prices and the individual *_card tools without opening any schema.

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

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

Gives clear context for when this tool applies: after a comparison, to confirm raw search price, stock and seller cheaply. It implies the alternative (the full unified mount) but never states explicit when-not/exclusion conditions, and the Yandex-specific guidance is scoped to one parameter rather than the tool's overall usage boundary.

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 establish read-only and idempotent behavior, so the description correctly focuses on additional behavioral traits: region override semantics ('overrides DETMIR_REGION for this call only'), store_count's dependence on city, and the price_rub representation (None, never 0). It also discloses the error format, going beyond annotation hints.

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

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

Well-structured with front-loaded purpose, bolded sections for return and error formats, and each sentence provides distinct information. Despite length, nothing seems superfluous.

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 rich annotations, a complete input schema, and an output schema. The description additionally explains the most important operational nuance (region-dependent store_count) and error behavior, making the tool fully invokable without further research.

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

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

The schema already provides full descriptions for both parameters (product_id with URL example, region with default). The description adds behavioral context about how region affects store_count and the session-level override, which helps the agent choose values, but does not add new syntactic detail.

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

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

The description opens with 'Fetch price, rating, stock and seller for one Detsky Mir product,' a specific verb+resource that clearly distinguishes this from sibling card tools for other marketplaces. It further differentiates by noting its coverage of the kids-and-baby category and its ability to distinguish Detsky Mir's own stock from marketplace sellers.

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

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

The description clearly implies this is for querying Detsky Mir product details, and contrasts with general marketplaces ('covers the kids-and-baby category that the general marketplaces cover unevenly'). However, it does not explicitly name alternative tools or provide exclusion criteria, so it falls short of full usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by explaining that each node carries products_count to assess inventory before fetching, and by disclosing the error format including retryability. It does not add rate limits or other potential side effects, but the existing disclosures are solid and no contradiction exists.

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 well-structured with headers for overview, return format, and error format. It is informative without being bloated; each section serves a purpose. The module docstring reference is slightly tangential but useful context. Overall, it is efficient and 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 covers the tool's role in the workflow, why it exists (no text search), what the return format looks like, and how errors are surfaced. Since an output schema is present, it need not explain each field; the description provides enough context for an agent to select and invoke the tool correctly in most situations.

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

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

The input schema covers all three parameters (limit, parent, region) with descriptive comments, so schema coverage is 100%. The description does not add new semantic information about these parameters beyond what the schema already provides. It does contextualize the returned alias for detmir_category, but that is about output, not parameter meaning. Thus baseline 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 opens with a specific verb+resource+outcome: 'Browse the Detsky Mir catalog tree and get the aliases detmir_category needs.' It clearly distinguishes from the sibling detmir_category by positioning this as the discovery step, and mentions the catalog tree and aliases, leaving no ambiguity about what the tool does.

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

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

The description provides clear context: 'This is the discovery step' and explains that Detsky Mir has no working text search, so walking the tree is the way to find products. It even names the dependent sibling (detmir_category) and how the output feeds into it. It does not explicitly state when not to use the tool, but the context is strong enough that an agent can infer appropriate usage.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: it is a 'real JSON endpoint with proper pagination and an upstream total', empty pages are reported via meta.warnings, and error format includes retryable indication. 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 well-structured with a clear purpose statement, a 'why' paragraph, and dedicated Return Format / Error Format sections. Every sentence adds value; it is detailed without being bloated. It is front-loaded with the core action.

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 pagination, region handling, and error reporting, the description covers all essentials: return format with key fields, relationship to detmir_card, empty-page behavior, and error format with retryable indicator. An output schema exists, so the description does not need to enumerate every field, but it provides enough context for correct usage.

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?

Input schema has 100% description coverage for all four parameters, so the schema already documents each parameter. The description adds only minor context (e.g., alias example 'pups', region default to DETMIR_REGION) but does not significantly enhance parameter meaning beyond what the schema provides. Baseline 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 opens with 'List products in a Detsky Mir category, with the total match count' — a specific verb+resource+scope. It further distinguishes itself from text search by calling itself 'the reliable way to enumerate the catalog', separating it from sibling tools like detmir_categories (category listing) and detmir_card (product details).

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

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

The description explicitly states when to use this tool: 'This is the reliable way to enumerate the catalog' and contrasts with text search. It also clarifies pagination behavior and that an empty page is not an error, guiding the caller on how to interpret results.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine value beyond that by enumerating failure modes (BadRequestError, ChallengeRequiredError, TransportDownError, ParserDriftError) and noting challenge responses are never cached, which tells the agent what to expect on retries.

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 single-sentence purpose is front-loaded, and the return/error sections are tightly formatted with no filler. Slightly more structure than strictly needed given an output schema exists, but every line is scannable and earns roughly its space.

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

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

For a one-parameter read tool with full annotation coverage, the definition gives everything needed to call it correctly: input format, response shape, and a useful taxonomy of error conditions. Redundancy with the existing output schema is minor; the only real gap is the missing routing guidance versus dns_search.

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

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

Schema description coverage is 100%, so product_url is fully documented with format and an example in the schema. The description only adds a small amount of semantics ('BadRequestError when the URL carries no product id'), which reinforces the required format but does not go beyond the schema.

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

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

States a specific verb and resource: 'Fetch one DNS-Shop product card', making clear it is a single-item retrieval scoped to dns-shop.ru. It does not explicitly contrast with the nearby dns_search sibling, so an agent must infer the search-vs-fetch split from the tool name alone.

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 required product_url parameter and the 'one card' phrasing suggest it is for a known product URL, while dns_search would be for discovery. No sentence states when to prefer this over dns_search, avito_card, ozon_card, or compare_prices, and no prerequisites 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?

The annotations already establish read-only, open-world, idempotent behavior, and the description adds useful operational context: rendering in the operator's Chrome, Qrator challenge handling, transport failures, parser drift, and the fact that challenge results are never cached. It does not cover rate limits or pagination behavior, but it discloses substantial behavior beyond the annotations.

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

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

The description is compact and front-loads the purpose, then uses clear headings for return and error behavior. The return-format section partially overlaps with the output schema, though the price_rub note adds real value.

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

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

Given the simple one-parameter schema, annotations, and output schema, the description covers purpose, return shape, and important error modes. It is mostly complete, though it lacks explicit guidance on when to choose this search over sibling tools.

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

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

There is one parameter with 100% schema description coverage, including an example query. The description does not add syntax or filtering semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Search DNS-Shop.' This distinguishes it from most marketplace tools by source, though it does not explicitly distinguish it from the sibling dns_card tool.

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

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

The description does not explain when to use this tool versus alternatives such as dns_card or other marketplace search tools. It implies a DNS-Shop search context but gives no explicit usage conditions or 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?

Beyond the annotations, the description discloses the HTTPS GraphQL path, the in-page Chrome POST fallback, anti-bot challenge behavior requiring manual completion and retry, and specific failure modes. This is rich behavioral context for an agent invoking the tool.

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

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

The description is front-loaded with the core fetch behavior and uses clear headings for return and error formats. It is mostly efficient, though the Return Format section partially duplicates what the output schema already provides.

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

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

Given the annotations, output schema, and single-parameter input, the description is largely complete: it covers fallback behavior, error conditions, and return shape. The main remaining gap is explicit routing guidance among sibling search and card tools.

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

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

Schema description coverage is 100%, and the single parameter is already documented as a SKU or lamoda.ru product URL. The description adds little parameter-level detail beyond implying that a SKU is extracted from the input, so it meets the baseline for a fully documented schema.

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

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

The description states a specific operation and resource: fetching a Lamoda product card via GraphQL over HTTPS with a Chrome fallback. It is clear enough to identify the tool, but it does not explicitly differentiate itself from sibling tools like lamoda_search or other *_card 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 explains the fallback mechanics and error cases, but it does not say when to use this tool versus alternatives such as lamoda_search for discovery or other marketplace card tools. Usage is only implied by the sku_or_url parameter and error conditions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description goes meaningfully further: it names the concrete failure modes (challenge_required on a visible challenge, TransportDownError on CDP/nav failures, ParserDriftError on zero-SKU renders) and the Chrome-rendering dependency. It stops short of stating auth, rate limits, or pagination 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?

Front-loaded with the one-line purpose, then clearly sectioned Return Format and Error Format blocks. Each sentence carries information; the only minor waste is re-listing the return envelope despite an output schema existing.

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

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

For a single-parameter search with a full output schema and rich annotations, the description covers the operation, the execution mechanism, the response shape, and the error taxonomy — enough for correct invocation. The missing piece is routing guidance versus the many sibling search tools.

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

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

Only one parameter (query) and schema description coverage is 100%, with the schema supplying the format example ('кроссовки nike'), so the baseline of 3 applies. The description adds nothing about query syntax, locale, or length limits beyond the schema.

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

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

States a specific verb+resource ("Search Lamoda") and adds execution context — it runs through the operator's Chrome. It is clearly distinguishable from non-search siblings by name, but it never differentiates itself from sibling searches (wb_search, ozon_search, etc.) or from lamoda_card, so the agent must infer the routing.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of when to prefer lamoda_card or another marketplace search. The phrase "discovery is blocked tier 1" hints at an internal tier constraint but is unexplained and does not tell the agent which conditions select this tool.

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

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

Annotations already carry the read-only/idempotent/no-destructive profile, but the description adds genuinely non-obvious behavior: the defensive import model, the existence of the 'skipped' set, and the explicit guarantee that it never raises ToolError. It stops short of the annotation-free ideal but goes well beyond the safety hints.

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

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

Front-loaded with the one-line purpose, then organized under 'Return Format' and 'Error Format' headings. Slightly verbose in the 'Why this exists' rationale, but every sentence carries information an agent needs.

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

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

Despite an output schema existing, the description still summarizes the response shape and, more importantly, explains the semantics of 'skipped' (import error vs. explicit deselection). It also covers the error contract, so an agent has everything needed to interpret results correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly implies a parameterless introspection call without inventing or misrepresenting inputs.

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

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

States a specific verb and resource ('list which connectors this unified server actually mounted') and is unmistakably distinct from every sibling search/card tool. An agent can tell it apart without opening the schema.

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

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

Explicit when-to-use: 'Call this before concluding a marketplace has no results.' It also names the failure mode that makes that necessary (absent tools look the same as an empty source), which is exactly the routing guidance an agent needs.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower. The description adds genuinely new context by enumerating failure modes (BadRequestError, NotFoundError, TransportDownError, ParserDriftError), which tells the agent how this tool can fail and why.

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 opening sentence is front-loaded and tight, and the error-format block earns its place. The Return Format block largely restates the output schema fields, which the description need not duplicate, adding mild 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?

With an output schema present, the description need not explain return values, and safety behavior is covered by annotations; the added error taxonomy makes it complete enough for a one-parameter lookup tool. Only the missing when-to-use routing against sibling search/card tools keeps it from a 5.

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

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

Schema description coverage is 100% and the single parameter (item_id_or_url) is already documented in the schema as a goods id or megamarket.ru URL. The description adds no syntax, format, or constraint detail beyond that, so baseline 3 applies.

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

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

States a specific verb ('Fetch'), a specific resource ('Megamarket product card'), and scope ('one'), so an agent can tell it apart from megamarket_search. It does not, however, explicitly differentiate itself from the many sibling *_card tools beyond the marketplace name.

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

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

The description gives no guidance on when to use this card lookup versus megamarket_search, compare_prices, or the other marketplace card tools. Usage context is implied only by the tool name.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds meaningful beyond-annotation detail: address sourcing, the private-account read caveat, _meta.warnings semantics, healthy=false conditions, and auth/runtime prerequisites (operator's Chrome). This is unusually rich behavioral disclosure.

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

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

Front-loaded opening sentence is efficient, but the description then dives into dense _meta/address_source detail that reads more like internal notes than task-relevant guidance for an agent. Structured headers help, but the middle paragraph is heavy relative to a single-parameter search 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?

Output schema exists, so return values needn't be explained, yet the description summarizes return format and error format anyway. Combined with address-resolution behavioral notes, it is largely complete for a one-parameter search, though it omits pagination/limit behavior and when the operator's Chrome is assumed available.

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

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

Schema description coverage is 100% and there is only one parameter (query), so the schema already carries the semantics. The description adds nothing about query syntax, length, or localization beyond what the schema provides.

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

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

States a specific verb+resource: search the Megamarket catalog via the mobile API inside the operator's Chrome. It is clearly distinguishable from siblings like ozon_search by naming the Megamarket catalog, though it doesn't explicitly differentiate itself from other marketplace *_search tools beyond the store name.

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

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

No explicit when-to-use or when-not-to-use guidance. There is deep context about address resolution behavior, but no routing advice such as when to prefer megamarket_search over compare_prices or marketplace_sources. Usage is implied by the tool name, not stated.

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

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

The description extensively discloses behavior beyond the annotations: rolling averages, per-day graph semantics, zero-cell meaning, auth failure modes, and a full error taxonomy. It also clarifies missing values are None, never 0, which is a subtle but crucial behavioral detail. No contradictions with the read-only/idempotent 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 well-structured with clear sections (overview, return format, error format) and every sentence carries meaningful information. It is length-appropriate for the tool's complexity and front-loads the core purpose.

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

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

Despite the tool's moderate complexity, the description covers the full usage context: what the tool returns, the exact structure, all error cases, and prerequisites. The output schema and annotations are supplemented effectively, leaving little room for agent confusion.

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

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

The schema already has 100% coverage with detailed parameter descriptions, so the baseline is 3. The tool description adds useful context about what the data represents (e.g., 'per-SKU', '30-day') but does not add significant new meaning beyond the schema's parameter descriptions.

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

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

The description opens with a specific, actionable verb ('Fetch') and identifies both the resource (MPStats) and scope (per-SKU 30-day sales analytics, Ozon or Wildberries). It clearly distinguishes this from sibling tools via the per-SKU granularity and explicit marketplace focus.

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 establishes when to use the tool: for per-SKU analytics on MPStats data. It also gives a key prerequisite (MPSTATS_MP_AUTH env var). However, it does not explicitly state when NOT to use this tool or name an alternative, 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, openWorldHint, and idempotentHint, but the description adds substantial behavioral context: auth requirements, specific error types (BadRequestError, AuthMissingError, RateLimitedError, etc.), and data semantics like "Missing stock counts are None, never 0." No contradictions 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 well-structured with clear sections for return format and error format. It is appropriately detailed without redundancy. Every sentence adds helpful information, from the auth requirement to the behavior of missing data (None, never 0). The use of formatting (code highlights, headings) enhances 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?

Despite having an output schema, the description thoroughly explains the return structure and also enumerates all relevant error scenarios. It covers prerequisites (paid MPStats account), parameter scope, and edge cases. For a tool with two parameters and a moderate complexity, this is complete and self-sufficient.

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

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

Schema coverage is 100%, with descriptions for both skus and place. The tool description adds a bit of context, such as "place determines which MPStats dataset the SKUs resolve against," but this is also present in the schema. The description does not significantly enrich parameter understanding beyond the schema's existing 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 opens with a specific verb and resource: "Fetch per-SKU warehouse stock split from MPStats (Ozon or Wildberries)." It clearly distinguishes this tool from siblings by focusing on warehouse stock split, a niche capability. The return fields (FBS, FBO, etc.) further solidify a distinct purpose.

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 implicitly communicates when to use this tool by stating what it returns and the required environment variable (MPSTATS_MP_AUTH). It does not explicitly name alternatives or exclusions, but the context of fetching per-SKU stock split from MPStats is clear. The presence of sibling tools like mpstats_item suggests different use cases, but that contrast is not explicitly stated.

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

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

Goes well beyond the annotations by detailing the tiered fetch mechanism, Chrome CDP prerequisite, return format fields, error taxonomy, and no-result handling. This is rich behavioral context that helps an agent anticipate side effects and operational requirements.

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?

Well-structured with a clear first sentence and dedicated sections for return format and error format. Every section earns its place without unnecessary verbosity.

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

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

Covers purpose, transport strategy, prerequisites, return schema, error taxonomy, and no-result semantics. For a single-parameter read-only tool with existing annotations, this description is fully sufficient for an agent to invoke correctly.

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

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

Input schema already documents the single parameter at 100% coverage, including accepted forms (SKU, URL, path) and SSRF prevention. Description adds no parameter-level details, 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?

Description opens with 'Fetch Ozon product card data via composer-api.bx', a specific verb+resource statement. It clearly distinguishes the tool from sibling tools like ozon_search and ozon_reviews by focusing on product card retrieval.

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

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

Provides clear context on when to use: fetching product card data, with explicit fallback behavior from Tier-1 to Tier-2 on Cloudflare 403. Does not explicitly name alternative tools or when-not-to-use, so it stops short of a 5.

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

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

Annotations already declare read-only/idempotent/open-world, and the description adds substantial context beyond them: two-tier fetch with Chrome CDP fallback, automatic page walking at 30/page, uuid dedup, a hard 10-page cap, and the crucial pool-vs-SKU caveat. It also spells out partial-success semantics (partial=True, stop_reason set) vs. ToolError-only-when-nothing-collected, which an agent cannot infer from 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?

Despite its length, it is well front-loaded and sectioned (pool caveat, return format, error format), and every section carries actionable content. The Return Format block partly restates the output schema, which slightly dilutes conciseness.

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

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

Covers everything needed for correct invocation and interpretation: transport strategy, pagination and truncation behaviour, partial-success vs. hard-error boundary, and the pooled-rating trap that would otherwise cause a wrong product conclusion. With an output schema present, the description need not explain return values further and doesn't over-reach.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `limit` is described as a count of collected texts driven by 30-per-page walking with a 10-page hard cap, which explains how the parameter actually behaves in practice. It adds little on `sort` or `sku_or_path` beyond what the schema already states.

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?

Opens with a specific verb+resource+source ("Fetch Ozon product review texts + star distribution via composer-api.bx"), which unambiguously separates it from ozon_card (product data) and wb_reviews (other marketplace). The scope is further pinned down by naming exactly which fields are returned and that the pool is per card-family rather than per SKU.

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

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

Gives strong operational guidance: filter by `item_id` before concluding anything about a product, and flag when `own_reviews` is 0 because the headline rating may belong to neighbouring variants. It does not, however, explicitly route the agent to sibling tools (e.g. ozon_card for specs, wb_reviews for other marketplaces), so it lacks true when-not/alternative statements.

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

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

With annotations already declaring readOnly, idempotent, and non-destructive behavior, the description adds valuable context: the tiered transport (curl_cffi to CDP), the specific widget parsing, the healthy response with zero items, and the raised error types. 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 structured into clear sections (Return Format, Error Format) and is front-loaded with the core purpose. A few sentences could be tightened, but the details are useful and not wasteful.

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 explains the return format (OzonSearchResponse), the error model (ToolError subclasses), and the zero-match behavior, making it self-sufficient. Output schema exists, but the description adds operational context that is not redundant.

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

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

The input schema covers both parameters (query and page) with descriptions, so schema coverage is 100%. The description adds no additional parameter semantics beyond the schema; it mentions page and query only implicitly. Baseline 3 applies because the schema does the heavy lifting.

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 'Search Ozon catalog,' a specific verb+resource pair that clearly distinguishes this tool from sibling tools like ozon_card or wb_search. It further specifies the return fields (sku/title/price/rating) and the search tier architecture, leaving no ambiguity about what the tool does.

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

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

Usage is implied by the tool name and description, but there is no explicit guidance on when to prefer this tool over alternatives (e.g., ozon_card for detailed product info). It does mention fallback behavior as a technical detail, but not usage context or 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?

Goes well beyond the annotations by disclosing caching policy ('Only successful cards are cached'), degradation behavior (description_images falling back to 0 with meta.warnings), and a full error taxonomy including challenge_required and ParserDriftError. It also explains evaluation order ('Positive challenge evidence is checked before item mapping') and that hidden widget text is excluded, which an agent could not infer from readOnly/idempotent hints alone.

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?

Headered sections (Return Format, Error Format) with the action front-loaded in the first line make it easy to scan. A few sentences are dense to the point of opacity, notably 'Positive challenge evidence is checked before item mapping regardless of title/price', which costs some 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?

Despite an output schema existing, the description gives the agent the shape of TaobaoCardResponse and the important sentinel semantics (price_cny is None, never 0) plus the complete failure-mode list, so an agent knows both what a success and a failure look like. Nothing critical for a one-parameter read tool is missing.

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

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

Schema description coverage is 100% for the single item_id_or_url parameter, so the schema already carries the semantics. The description adds only indirect meaning via error cases ('BadRequestError when no id can be extracted'), implying the value may be a URL from which an id is parsed, but it never states accepted formats, length limits, or whether URL variants other than item.taobao.com are valid.

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

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

The opening line names a specific verb and resource ('Fetch one Taobao item card'), which clearly distinguishes a single-item fetch from the search-oriented siblings like taobao_search and aliexpress_search. It stops short of naming those siblings explicitly, so the differentiation is implied rather than stated.

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

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

Usage is only implied: you call it when you have a single item id or URL. There is no explicit statement of when to prefer taobao_search, aliexpress_card, or compare_prices over this tool, and no mention of prerequisites such as needing a resolved item id before calling.

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