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?

The description goes beyond the annotations (readOnlyHint, idempotentHint) by detailing the exact error format and conditions (BadRequestError, NotFoundError, TransportDownError, ParserDriftError). It also clarifies an important behavioral nuance: price_rub is None when the ad has no price, never 0. This adds valuable context for handling tool results correctly.

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 well-structured, with a one-sentence summary followed by clearly labeled 'Return Format' and 'Error Format' sections. Every detail earns its place, giving the agent precise information 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?

For a simple single-parameter fetch tool, the description covers all essential aspects: what it does, the exact structure of the response, and all expected error types. The annotations and output schema fill in the remaining details, making this description complete for the tool's complexity.

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

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

The input schema already fully documents the single parameter item_id_or_url with a clear description ('Item id, slug path or full avito.ru URL'), so the schema carries the heavy lifting. The tool description's 'by id or URL' adds no extra meaning beyond the schema; the return-format details are about output, not parameters. Thus, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action ('Fetch one Avito listing') and its input scope ('by id or URL'). This distinguishes it from sibling tools like avito_search (which searches multiple listings) and avito_seller (which fetches seller data), making the purpose explicit and distinct.

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

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

The description gives clear context that this tool is for retrieving a single, specific listing when an id or URL is available. It doesn't explicitly name alternatives or state when not to use it, but the intent is unambiguous enough to guide an agent without additional 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?

Builds on read-only/idempotent annotations by detailing the return envelope (e.g., 'tier_used', 'total_count') and item fields, notably 'price_rub (None when the ad has no price — never 0)' to prevent misinterpretation. The error format section discloses specific failure modes (BadRequestError, TransportDownError with captcha/proxy guidance, ParserDriftError), which is valuable 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 well-structured with a one-line purpose followed by clearly labeled Return Format and Error Format sections, making it scannable. It is slightly verbose due to the return format detail, but each section carries meaningful information, and there is no fluff.

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

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

With a detailed schema, safety annotations, and an output schema, the description still adds critical context about error handling and data semantics (e.g., price None vs 0). It does not mention pagination behavior beyond the page parameter, but the schema already constrains that, so overall the tool is well-specified.

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

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

The input schema already provides 100% parameter coverage with clear descriptions, including defaults and examples. The tool description adds no extra semantic detail for parameters beyond what is in the schema, so it does not go beyond the baseline for high schema 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 'Search Avito listings via the internal js/items API,' which clearly states the verb, resource, and scope. This distinguishes it from sibling tools like avito_card and avito_seller, and from other marketplace search tools.

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

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

The description implies use for searching Avito listings but does not explicitly state when to use this tool versus alternatives like avito_card for details or avito_seller for seller info. There is no exclusion or reference to sibling tools, leaving the choice to the agent's inference.

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

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

Annotations already declare the tool as read-only, idempotent, and open-world. The description adds valuable behavioral context beyond these: specific error conditions (empty input, 404, transport blocks, parser drift) and the return envelope structure. This goes beyond what annotations provide, giving an agent clarity on failure modes and output shape.

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 efficiently structured with clear sections for purpose, return format, and error format. Every sentence contributes meaningful information without fluff. It is slightly longer than the bare minimum but justified by the niche context and error details, making it easy to scan.

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

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

Given the tool's low complexity (one parameter, read-only, output schema present), the description is complete. It covers the purpose, the data content (rating, review count, active listings), the return envelope, and all error cases. The presence of an output schema reduces the need to describe return values in detail, and the description still adds contextual clarity about why this data matters.

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 parameter seller_id_or_url is already fully documented in the input schema with 'Seller id or profile URL from a card/search hit' (100% coverage). The description does not add any additional meaning about the parameter beyond what the schema provides, so it hits the baseline of 3 for adequate schema 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 clearly states 'Fetch an Avito seller profile' and explains what the profile contains (rating, review count, active-listing count). It distinguishes this from per-item review tools by noting that classifieds have no per-item review pool, making the seller profile the definitive reputation signal. This separates it from avito_card and avito_search.

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 strong contextual guidance: it explains that in classifieds, the seller's reputation is what buyers check, implying this tool should be used when evaluating a seller's trustworthiness rather than item reviews. However, it does not explicitly name alternative tools or state 'use this when you need seller reputation, not item details,' which would make the guidance more prescriptive.

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 readOnlyHint annotation by detailing the return format (CitilinkCardResponse) and specific error conditions (BadRequestError, TransportDownError, ParserDriftError). This adds significant behavioral context that annotations do not cover.

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 is slightly verbose but each sentence earns its place by providing necessary operational information.

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

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

With an output schema present, the description appropriately focuses on error cases and operational details. It covers all relevant failure modes and return contract, making it complete for a single-parameter fetch 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?

The input schema already provides 100% coverage of the single parameter with a clear description and example. The tool description adds no additional parameter semantics, 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 clearly states 'Fetch one Citilink product card' with a specific verb and resource. It distinguishes itself from siblings like citilink_search by specifying 'one' card fetch, implying a single product URL.

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

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

The description implies usage for fetching a single product card, but it does not explicitly state when to use this tool versus alternatives like citilink_search. No direct exclusions or alternative guidance is provided.

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

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

The description adds significant behavioral detail beyond annotations: it notes the search is rendered in the operator's Chrome, defines the return format (including price_rub None never 0), and specifies error types (TransportDownError on CDP/Qrator failures, ParserDriftError on zero product tiles). This is rich context that annotations do not provide.

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, front-loaded with the core action, and uses clearly labeled sections for return and error formats. Every sentence adds meaningful information with no filler or repetition.

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

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

For a single-parameter search tool, the description covers the core action, rendering context, return shape, and failure modes. The full output schema also exists, so the description is sufficiently complete without needing to list every response field.

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 fully documents the single query parameter with min/max length and an example. The description adds no additional parameter-level semantics, only return/error context. With 100% schema coverage, 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 opens with a specific verb and resource: 'Search Citilink'. The title and schema example ('ноутбук lenovo') confirm it is for product search, clearly distinguishing it from sibling tools like citilink_card. The purpose is unambiguous.

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

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

The description implies use for searching Citilink and states it is rendered in the operator's Chrome, but it never explicitly says when to prefer this tool over alternatives like citilink_card or compare_prices. No exclusions or alternative tool references are provided, so guidance is only implied.

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

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

Annotations already set readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial context beyond that: cheapest excludes Yandex subscription price, source_outcomes indicates partial results, titles are matched loosely, and individual source failures do not raise errors. This is exactly the kind of behavior an agent needs to interpret output correctly.

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 long but every section earns its place: clear purpose, explicit usage guidance, two important output caveats, a note on matching behavior, and structured return/error format. It is front-loaded with the essential purpose and uses formatting (sections, em-dashes) to make scanning easy. No filler.

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

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

For a tool with three parameters, complex behavior (concurrent queries, partial failures, subscription prices), and a rich output schema, this description covers all necessary aspects: what it does, when to use it, how to interpret results, what the return structure looks like, and how errors are handled. It is complete enough for an agent to invoke and use the 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 input schema covers all parameters with descriptions, so the baseline is 3. The description adds some relevant context about loose title matching and 'in Russian' for the query parameter, but it does not significantly extend the schema's parameter explanations. It meets the baseline without exceeding 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 opens with a specific verb and resource: 'Price one product across every configured Russian marketplace at once.' It clearly distinguishes itself from per-marketplace search tools by emphasizing the concurrent comparison and ranking, so an agent immediately knows what this tool uniquely 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 explicitly states when to use this tool: 'This is the tool for "where is X cheapest"' and contrasts it with the slower alternative of running per-marketplace search tools one at a time. It also implicitly tells the agent when NOT to use it (when you need a single marketplace's detailed results, use those sibling 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?

Annotations already declare readOnlyHint, idempotentHint, etc., but the description adds substantial behavioral context beyond that: it never raises ToolError, performs pure introspection, touches no network, and documents the return format including server metadata and per-source notes. This gives the agent a full picture of what the tool does and what to expect.

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 headings for purpose, return format, and error format. Every sentence provides useful information — no filler. The use of bullet-like examples and plain object field listing keeps it compact while being fully informative.

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 no parameters, an output schema, and a clear diagnostic role, the description is complete. It explains return format, error behavior, and usage context. There are no missing pieces that would leave an agent uncertain about invocation or interpretation of results.

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

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

The tool has zero parameters, so there is no parameter semantics to clarify. Per the baseline, a 0-parameter tool with full schema coverage earns a 4; the description adds value by explaining the return structure, which compensates for the lack of parameters.

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 'Report which marketplaces this installation can actually query' — a specific verb and resource that clearly states the tool's function. It also distinguishes this from sibling marketplace tools by framing it as a diagnostic first call for partial comparison results, which uniquely positions it among 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 explicitly states when to use it: 'Call this first when a comparison comes back partial' and explains the key distinction between 'connector isn't installed' and 'marketplace refused us', which require different fixes. This directly answers when and why to use this tool versus alternatives.

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

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

Annotations 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, and non-destructive. The description adds specific error behaviors (BadRequestError, TransportDownError, ParserDriftError) and a condition for parser drift, providing context 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 well-structured with clear sections and no wasted words. The Return Format section may duplicate what the output schema already provides, but it is brief and doesn't bloat the description.

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

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

For a scraping tool with potential failures, the description covers purpose, input requirements, return format, and all relevant error modes. Since an output schema exists, the return format section is a bonus rather than a gap.

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

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

The schema already documents product_url with an example and full coverage. The description adds semantic value by explaining that a BadRequestError occurs when the URL carries no product id, reinforcing the expected URL structure.

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

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

The description opens with 'Fetch one DNS-Shop product card', which clearly states a specific verb and resource. This distinguishes it from sibling tools like dns_search (search) and other marketplace card tools, making the purpose unambiguous.

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

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

The description clearly implies this tool is used when you need a single product card by URL, and the input requirement for a product URL provides context. However, it does not explicitly mention alternatives or when-not-to-use, 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations, including the rendering environment, return format (price_rub is None not 0), and specific error conditions (TransportDownError, ParserDriftError). This is useful operational detail without contradicting 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 well-structured, opening with a clear purpose then using labeled sections for return and error formats. Each line adds meaningful information, avoiding fluff. Slightly verbose due to formatting details but appropriate for the tool.

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

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

For a simple one-parameter search tool, the description is highly complete. It covers purpose, return structure, and failure modes, and is backed by strong annotations and schema coverage. The tool is fully specified for an agent to select and invoke it correctly.

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

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

The input schema already provides 100% coverage with a description and example for 'query'. The tool description does not add further parameter-level detail, so the baseline of 3 is appropriate; the schema carries the semantic burden.

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

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

The description clearly states 'Search DNS-Shop' with a specific verb and resource, making it distinct from sibling tools that target other marketplaces. It also adds context about being rendered in the operator's Chrome, further clarifying the tool's role.

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

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

No explicit guidance is provided on when to use this tool versus alternatives like ozon_search or wb_search. The description does not mention exclusions or selection criteria, leaving the agent to infer that it should be used for DNS-Shop searches based solely on the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by revealing the anonymous endpoint (no auth needed), the tier 1 designation, that Lamoda exposes no ratings, and enumerating specific error types, which helps agents anticipate failures.

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 with Return Format and Error Format sections, using concise bullet-like notation. It includes essential details without extensive prose, though the return field listing may be somewhat redundant if an output schema is available.

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 single simple parameter and strong annotations, the description covers the essential behavior, return shape, and error cases. It is complete enough for an agent to invoke the tool correctly, though it leaves terms like 'tier_used' and 'meta' 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 schema fully documents the single parameter with an example format. The description's error format mentions 'when no SKU can be extracted', which reinforces that the input must contain a SKU, but adds little 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?

The description opens with 'Fetch one Lamoda product card via the anonymous GraphQL endpoint (tier 1)', providing a specific verb and resource. It clarifies it fetches a single card, distinguishing it from search tools like lamoda_search, though it does not explicitly name alternatives.

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 state explicit when-to-use vs alternatives. The context of requiring a SKU or URL is implied by the parameter, and the 'one product card' phrasing suggests not for searching, but this is left to inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructiveness, so the safety profile is covered. The description adds valuable context: the tool renders in the operator's Chrome, mentions tier-1 discovery blocking, and explains error semantics (ParserDriftError on zero SKUs, price_rub never 0 when absent). This goes beyond the structured 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 and error formats, and every sentence provides useful information. It is slightly verbose for a one-parameter search tool, but the added detail on errors and return fields earns its place.

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

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

For a simple one-parameter search tool with a full output schema and strong annotations, the description covers the key behavioral aspects: rendering environment, tier status, response shape, and failure modes. It does not mention pagination or rate limits, but these are not critical given the tool's simplicity and the schema presence.

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 100% coverage for the single 'query' parameter, including an example. The description does not add any new parameter semantics beyond what the schema gives, so it lands at the baseline of 3.

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

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

The description states the tool 'Search Lamoda' with a specific verb and resource, and the return format makes its role as a marketplace search tool clear. It is implicitly distinguished from sibling tools like lamoda_card by name and output shape, but it does not explicitly call out the distinction.

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 context is implied by the name ('Lamoda Search') and the fact that sibling tools cover other marketplaces, but the description provides no explicit guidance on when to choose this tool over alternatives, nor does it mention a complementary tool like lamoda_card for item details.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context beyond these: defensive importing behavior, that failed imports are recorded in ``skipped`` rather than raised, and that it never raises ToolError. This explains the observable behavior and error semantics.

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?

Although the description is longer than average, it is well-structured with clear sections ("Why this exists", "Return Format", "Error Format") and every paragraph adds value. The length is justified by the need to explain the invisible failure mode and the return format.

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 zero parameters and the presence of an output schema, the description fully covers the tool's purpose, usage context, return semantics, and error behavior. It addresses the complex diagnostic case where a missing source looks like an empty one, which is essential for an agent to use the tool 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 has 0 parameters, so the baseline for this dimension is 4. The description appropriately focuses on the return format and error behavior, adding meaning beyond the parameterless schema. No parameter documentation is needed.

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

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

The description clearly states the verb+resource: "List which connectors this unified server actually mounted." It distinguishes itself from sibling tools by explaining the diagnostic purpose: distinguishing missing marketplaces from empty ones, which is unique among the available 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?

Provides explicit when-to-use guidance: "Call this before concluding a marketplace has no results — if it is in ``skipped``, it was never queried at all." This tells the agent exactly when to invoke this tool versus assuming a marketplace is empty, effectively differentiating it from comparison tools like compare_sources.

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, non-destructive behavior. The description goes further by specifying the exact return fields and error types (BadRequestError, NotFoundError, TransportDownError, ParserDriftError), which provides concrete behavioral expectations 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 concise and front-loaded with the core purpose. The return format and error format sections are clearly structured and add necessary value without redundancy.

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

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

For a simple single-fetch tool, the description is complete. It specifies the output schema, error behavior, and is supplemented by strong annotations. An agent can correctly invoke the tool and interpret results without additional context.

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 parameter ('Goods id or megamarket.ru product URL'). The description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states the operation: 'Fetch one Megamarket product card.' It uses a specific verb ('Fetch') and resource ('Megamarket product card'), and the word 'one' distinguishes it from search tools. The marketplace name distinguishes it from 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?

No guidance is given on when to use this tool versus alternatives. The description does not mention that 'megamarket_search' should be used for discovery or that an item ID/URL is required. The input schema carries this information, but the description itself omits usage context.

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 provides substantial behavioral context beyond the annotations: it details the exact return format (MegamarketSearchResponse with fields status, query, tier_used, count, total_count, items, meta), explains the price_rub behavior (None when absent, never 0), and documents error formats (TransportDownError, ParserDriftError). This goes beyond the read-only and idempotent hints from annotations, offering valuable transparency about operational behavior.

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

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

The description is well-structured with clear headings for the main purpose, return format, and error format. It is appropriately sized, front-loaded with the core description, and every sentence provides useful information without unnecessary fluff.

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 is simple (one parameter), and the description covers the purpose, return structure, and error cases. Given the annotations and output schema presence, the description is complete for an agent to invoke the tool and interpret results. It even specifies the execution environment (inside the operator's Chrome) which may be relevant for the agent's decision-making.

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 fully covers the single parameter 'query' with a description and length constraints, so the schema coverage is 100%. The tool description does not add additional meaning to the parameter beyond what is already in the schema, which places it at the baseline score of 3.

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

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

The description clearly states the tool's function: 'Search the Megamarket catalog via the mobile API' using a specific verb ('Search') and resource ('Megamarket catalog'). It distinguishes itself from sibling tools like megamarket_card and other marketplace searches by explicitly naming Magamarket as the target.

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 a clear context for when to use this tool: when searching the Megamarket catalog. However, it does not explicitly exclude alternatives or recommend other tools for different scenarios (e.g., using megamarket_card for detailed product info). No explicit when-not-to-use guidance is provided.

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

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

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 readOnlyHint, idempotentHint, and destructiveHint=false, but the description goes far beyond by detailing the tier-1/tier-2 fallback, 30-per-page walking, hard 10-page cap, dedup by uuid, and nuanced partial-success/error handling. This is exemplary disclosure of behavioral traits.

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 (introduction, behavior, return format, error format). Every sentence carries useful information—no filler. While longer than a one-liner, the density and organization keep it efficient and scannable.

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, partial failures, and multiple error modes, the description is remarkably complete. It covers the success return shape, partial-success semantics, and the exact conditions for each error type. Combined with a rich output schema and annotations, an agent has everything needed to invoke and 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining how 'limit' interacts with automatic page walking (30/page until limit collected) and the hard cap, which is not fully captured in the schema alone. This pushes it to a 4.

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

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

The description opens with a specific verb and resource: 'Fetch Ozon product review texts + star distribution'. It clearly distinguishes this tool from sibling tools by focusing on reviews (vs. search, card, etc.) and even references the sibling ozon_card for implementation context. This is unambiguous.

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

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

The description does not explicitly state 'use this when X, use Y when Z', but it provides clear context about the return format, pagination behavior, and partial-success semantics, which helps an agent understand when this tool is appropriate. It lacks explicit exclusions or alternatives, so it falls just 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?

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?

Beyond the annotations (readOnly, idempotent, etc.), the description adds concrete behavioral details: price_cny is None when hidden or variant-based, description_images degrades to 0 with a meta warning, and specific error types for different failure modes. This is rich, non-obvious 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 well-organized with Return Format and Error Format sections. It is longer than the bare minimum but each section adds necessary detail without excessive 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?

The description covers return format, edge-case behavior, and error handling. Given the output schema exists and the tool is a simple fetch-only operation, it is sufficiently complete. It does not discuss prerequisites like URL formatting, but the schema covers parameter constraints.

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 parameter item_id_or_url is fully documented in the schema (100% coverage). The description adds no additional parameter semantics, 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 opens with 'Fetch one Taobao item card,' using a specific verb (fetch) and resource (one Taobao item card). It clearly distinguishes itself from sibling tools like taobao_search and other marketplace 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 phrasing 'one Taobao item card' makes clear it is for retrieving a single item's card, not searching. However, it does not explicitly state when to prefer this over taobao_search or other card tools, so it stops short of full explicit 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 annotations by disclosing dependency on Chrome/CDP, login wall behavior, and the significant 'price_cny None when hidden — never 0' output nuance. Also details error conditions (TransportDownError, ParserDriftError) that are not in 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?

Well-structured and concise. The core purpose is stated in the opening sentence, followed by organized return format and error format sections. Every sentence contributes useful information without 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?

Despite having a full output schema and strong annotations, the description adds crucial operational context: Chrome rendering dependency, login requirements, error conditions, and output quirks. This makes the tool safe and correctly invocable even with the schema and annotations present.

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 clear descriptions for both parameters, so the description need not add parameter-level detail. The return format section adds output context but does not enhance parameter semantics 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?

The description clearly states the tool's purpose: 'Search Taobao listings' with the distinctive detail that it is 'rendered in the operator's Chrome.' This distinguishes it from sibling tools like taobao_card and other marketplace searches.

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 for use (searching Taobao, requires operator's Chrome, login wall handling) but does not explicitly mention alternatives or when-not-to-use. The error section implies prerequisites (log into taobao.com) and retry guidance.

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

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

The description adds valuable behavioral details beyond the readOnly/idempotent annotations: price_rub is None (never 0), unknown SKUs are silently omitted, and error classes are mapped to specific conditions (rate limit, transport, parser drift). This goes well beyond the annotation 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?

The description is front-loaded with the purpose sentence and structured into Return/Error sections, making it scannable. It is slightly repetitive in listing fields (brand, supplier, ratings appear both in the intro and in the return format) but remains efficient overall.

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 return format, edge cases (unknown SKUs, None price), and all error classes, while annotations cover safety. The 100-SKU limit and dest behavior are captured in the schema. No critical information is missing for a batch-read tool.

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

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

The input schema already provides 100% parameter coverage, documenting dest (with default and examples) and nm_ids (with count/type constraints). The description only restates 'up to 100 SKUs' and adds no new parameter-level meaning beyond the schema.

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

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

The description opens with 'Fetch product card data from WB v4 API,' clearly stating the action and resource. It enumerates the returned fields (prices, brand, supplier, ratings, etc.) and the 100-SKU limit, which distinguishes it from sibling tools like wb_reviews or wb_search.

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 no explicit guidance on when to use this tool versus alternatives such as wb_search or wb_reviews. It only states functionality and limits, leaving the agent to infer appropriate use cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: responses are bounded slices of an ~800 KB menu, and it documents the error format. 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 clear sections, front-loaded with the primary purpose, and every sentence earns its place. It is concise (~150 words) yet informative, with no redundant wording.

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 still adds value by clarifying the node fields (id, name, url, shard, query, depth, children_count, children) and the relationship to wb_category_products. It also covers return format and error behavior, making it complete for a catalog browsing tool.

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

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

Schema coverage is 100% with descriptive parameter definitions, so the baseline is 3. The description adds context about starting at 'top' and expanding branches, but this largely overlaps with the schema's parameter descriptions rather than providing new semantic depth.

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

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

The description uses the specific verb 'Browse' with the resource 'Wildberries catalog tree', clearly stating what the tool does. It explicitly distinguishes itself from siblings by contrasting with wb_search and mentioning wb_category_products.

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 ('Use this to discover what exists before searching') and names an alternative (wb_search) that requires a query string. It also gives a navigation pattern ('start at top, then expand') and implies the role of wb_category_products.

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?

Despite annotations already declaring readOnly, idempotent, and non-destructive hints, the description adds substantial behavioral context: the return shape matches wb_card, has_more is inferred from a full page rather than a reported total, blackhole shards raise errors instead of empty lists, and a complete error taxonomy is provided (BadRequest, NotFound, RateLimited, TransportDown, ParserDrift). This goes well beyond the structured 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 long but well-structured with clear sections for purpose, caveats, return format, and error format. The opening sentence is a crisp summary, and subsequent paragraphs add necessary context about the blackhole limitation and error behavior. It is not overly terse for the complexity involved, though some sentences could be tightened without losing meaning.

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

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

For a tool with a moderately complex relationship to a sibling tool and several failure modes, the description is remarkably complete. It explains the integration with wb_categories, the blackhole exception, the exact return shape, and all anticipated error types. Even with an output schema present, the description independently lists the response fields, ensuring the agent fully understands what to expect.

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 covers all parameters with detailed descriptions, so the baseline is 3. The description adds contextual meaning by explaining that shard and query are handed back by wb_categories, that 'blackhole' is a special unlistable value, and that prices/stock are region-specific via dest. This extra provenance and edge-case info justifies a 4.

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

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

The description opens with a specific verb and resource: 'List the products in a catalog category' and immediately references the shard/query selectors from wb_categories. It also distinguishes itself from sibling tools by noting the items come back in the same shape as wb_search and wb_card, making its role in the category-vs-search workflow clear.

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

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

The description clearly states when to use this tool: after wb_categories provides shard and query selectors, for category-based browsing without inventing search phrases. It also warns that not every category has a feed and blackhole shards raise an explicit error. However, it does not explicitly name alternative tools like wb_search for text-based scenarios, so it falls slightly 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, idempotentHint, and destructiveHint=false. The description adds substantial behavioral details beyond those: an empty pool is not an error, pagination happens in pages of 30 (upstream cap), and a full error format section covers BadRequestError, RateLimitedError, TransportDownError, and ParserDriftError. It also explains the pooling behavior across variants and the nmId empty-pool consequence.

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 longer than average but well-structured with sections for main purpose, context, return format, and error format. It is front-loaded with the essential purpose and keying detail. No sentence is redundant; each adds value, but the error format section could arguably be summarized since the output schema exists. Still, it is appropriately scoped for the tool's complexity.

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

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

Given the tool's complexity (imt_id vs nmId, shared pool, pagination, empty pools, error cases), the description covers all necessary context: return format, error format, parameter semantics, and behavioral expectations. The output schema handles return structure details, and the description compensates for the schema's lack of runtime behavior. An agent can confidently invoke this tool correctly without additional lookups.

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. The description adds meaningful context beyond the schema: imt_id is the root ID from wb_root_info and must not be an nmId; limit is 'Fetched in pages of 30'; answered_only is framed as a filter for product-relevant questions ('Unanswered questions carry no product information'). These clarifications help the agent select and construct correct calls.

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 starts with a clear verb and resource: 'Fetch buyer questions and seller answers by imt_id (root_id from wb_root_info).' It explicitly distinguishes this tool from wb_reviews: 'Reviews describe the experience of owning the product; questions clarify what it actually is.' The scoping to imt_id and the relationship to wb_root_info further solidify its unique role among siblings.

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

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

The description provides explicit when-to-use context: buyers ask about listing omissions, and seller answers are often the only public statement. It names an alternative (wb_reviews) and contrasts them. It also gives a clear prerequisite: 'resolve the root id via wb_root_info first' because passing an nmId returns an empty pool. The answered_only parameter guidance ('Unanswered questions carry no product information') tells the user 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description reveals important non-obvious behaviors: the fixed ~1000-review pool, that server-side order params are ignored (verified Nov 2026), and that sort is applied client-side. It also discloses that an empty pool is not an error and details error types (BadRequestError, ParserDriftError, TransportDownError). This is substantial added behavioral context beyond what annotations provide.

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 main description, return format, and error format. It is dense but every sentence provides useful information: the pool limitation, the sort caveat, the empty-pool behavior, and error handling. It stays within reasonable length and is front-loaded with the core purpose, making it easy to scan.

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

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

With an output schema present, the description does not need to exhaustively list return fields, but it still summarizes the key fields and covers critical edge cases (empty pool not an error). It also explains error semantics and the source of the required id. For a tool with these annotations and schema richness, the description is fully complete for reliable invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'why' behind sort behavior: the endpoint ignores server-side order params, making the client-side reordering meaningful. It also reinforces the imt_id vs nmId distinction for the required parameter. This deepens understanding beyond the schema descriptions, warranting a 4.

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

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

The description opens with a clear imperative 'Fetch reviews by imt_id', specifying the resource (reviews), the identifier (imt_id), and explicitly distinguishes from siblings by noting 'All product variants share one review pool, indexed by imt_id NOT nmId.' This disambiguates from wb_card and wb_root_info that use nmId, giving strong purpose clarity with a specific verb+resource+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?

The description provides clear context on when to use the tool: it tells users to obtain imt_id from wb_root_info, warns against using nmId, and explains the 'worst' sort for surfacing complaints. However, it does not explicitly name alternative tools (e.g., wb_questions) or state when-not-to-use conditions, stopping short of full exclusionary guidance. The prerequisite and sort usage are clear, so it earns a 4.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context: error format (ToolError with JSON message and retryable flag), validation/transport failure handling, and details about the response structure. 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 front-loaded and uses clear section headers (Return Format, Error Format), but it repeats the imt_id concept multiple times: 'Returns imt_id', 'All variants of one product share imt_id', and 'imt_id is the root product id shared by every variant'. This redundancy could be trimmed without losing meaning.

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

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

For a single-parameter tool with an output schema, the description is complete: it explains the return format (WbRootInfoResponse fields), error format, the relationship to wb_reviews, and the purpose of imt_id. No significant gaps remain.

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 provides 100% coverage, describing nm_id as 'nmId (positive integer). The SKU whose basket CDN card.json is fetched for imt_id resolution.' The description does not add additional parameter semantics beyond this, so it meets the baseline but does not exceed 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 the action ('Fetch full card metadata from basket CDN') and the specific resource/outcome ('Returns imt_id (root_id) for review pool'). It distinguishes from sibling tools by explicitly noting that reviews are indexed by imt_id, not nmId, and referencing wb_reviews.

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?

Clear context is provided: the description explains that reviews are indexed by imt_id rather than nmId, implying this tool should be used to resolve imt_id before querying wb_reviews. However, it does not explicitly name alternative tools or provide when-not-to-use exclusions, so it stops short of full 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 and idempotentHint, so the description adds significant context beyond that: it explains the two-stage process (ID search then enrichment), error semantics (BadRequestError, RateLimitedError, TransportDownError), and that transport failures degrade to no_results. This is substantial 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?

The description is well-structured with headers for purpose, return format, and error format. Each sentence earns its place, and it is front-loaded with a one-sentence summary. No fluff or redundancy.

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