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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds structural context about threaded comments and writer replies, but does not disclose auth requirements, rate limits, or edge-case 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 two short sentences, front-loading the core action and following with a concise usage note. Every sentence earns its place, and there is no filler or redundancy.

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

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

Given the simplicity of the tool (two parameters), the rich annotations, the 100% schema coverage, and the presence of an output schema, the description provides sufficient purpose and usage context. Neither return values nor parameter details need repeating here.

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

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

Schema description coverage is 100%, so both parameters (limit, post_id) are fully documented in the schema itself. The description adds no additional parameter syntax, format, or meaning beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description states a specific verb ('Read'), a precise resource ('comments of a blog post'), and the return structure ('as threads, with the store writer's answers as replies'). This clearly distinguishes it from sibling tools like mk_blog_posts, which deals with posts rather than their comments.

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

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

It offers a clear usage context: 'Useful as a support FAQ: many posts hold readers' product questions answered by MasterKala.' However, it does not name alternative tools or specify when not to use this one, so it falls short of the explicit when/when-not/alternatives rubric.

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, non-destructive and openWorld, so the safety profile is covered. The description adds ordering ('newest first') and that entries include links, but does not disclose that the schema default category='buying_guide' means a bare call returns only buying guides, not all posts. Useful but incomplete 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?

Two tight sentences: the capability first, then the usage routing. Nothing is padded, though the trailing fragment about mk_blog_comments reads slightly like an afterthought rather than being fully integrated.

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

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

With an output schema present, return values need not be explained, and the annotations carry the safety profile; the description covers purpose, ordering and usage routing. The main omission is flagging that the default category filters results to buying guides only, which an agent could misread as 'all posts'.

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 page, limit and category are all documented in the schema, including the enum values with Persian glosses. The description adds nothing about parameter behavior (e.g. that category defaults to buying_guide), so the baseline 3 applies.

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

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

States a specific verb and resource (list blog posts), enumerates the content types (buying guides, comparisons, how-tos), and adds ordering ('newest first, with links'). It also names the sibling it is not (mk_blog_comments) so the agent can separate it from the reader-question tool without opening either schema.

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

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

Explicitly states when to use it ('when the user asks which product type to choose or how to use a gadget') and what to do with the result ('point them to the matching guide'). It also routes the adjacent need (readers' questions answered by the store) to mk_blog_comments, giving a clear alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description adds one genuinely useful behavioral fact — shops stock only part of the catalog — but says nothing about result count, pagination, or freshness of the listing. With annotations doing the heavy lifting, this is a modest value-add.

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

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

The purpose is front-loaded in one sentence, followed by a compact usage block; the warning about partial stock is the only 'extra' and it earns its place by preventing a bad user outcome. No filler or restated title.

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

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

With zero parameters and an output schema present, the description need not document return values. It covers what the tool is, when to pick it, and the one operational caveat, which is everything an agent needs for a no-arg listing call.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies a no-argument, list-everything call and introduces no phantom inputs, but there is no parameter semantics to enrich.

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

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

The first sentence states a specific verb and resource ('List MasterKala's physical shops in Tehran') and even enumerates the returned fields (address, phone, map location). It is immediately separable from siblings like mk_brands or mk_categories, which are also enumerations but of different resources.

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

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

Explicitly gives the selecting condition ('Use when the user wants to buy in person') and names the related sibling field (mk_product's `branches`) that covers the per-product variant of the question. It also supplies the follow-up behavior (call the shop before going) that an agent would otherwise have to invent.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered structurally. The description adds genuinely new context: the result set is a bounded catalog (~135 entries) whose values are slugs intended as inputs to other tools, which tells the agent how to use the output.

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

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

Two short sentences, zero filler, with the core purpose and scope front-loaded before the usage pointer. Every clause earns its place.

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

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

An output schema exists, so return values need not be spelled out, and the description still conveys the shape (names plus slugs) and cardinality. For a zero-required-parameter read tool with full schema coverage and annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the single optional 'query' parameter is fully documented in the schema, so the baseline is 3. The description adds nothing about filtering semantics (e.g., that omitting query returns everything), so it neither compensates nor detracts.

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

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

States a specific verb and resource ('List the brands MasterKala sells') plus the payload ('with their slugs'), and even quantifies scope ('about 135'). An agent can distinguish this catalog-listing tool from siblings like mk_categories, mk_filters, and mk_browse without opening any schema.

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

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

Explicitly names the downstream consumers ('Use to get the brand slug for mk_browse / mk_filters') and gives concrete example values ('anker-fa', 'mcdodo'), which is strong routing guidance. It stops short of stating when NOT to use it (e.g., when you already hold a slug), so it is not fully exhaustive.

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=true, idempotent=true, destructive=false and openWorld=true, so the safety profile is covered. The description adds non-obvious behavioral facts: the exactly-one-of selector constraint and the quirk that the site ignores sorting on keyword listings. It stops short of discussing pagination limits or result-count behavior, so it is strong rather than exhaustive.

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

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

The core capability and the selector constraint are front-loaded in the first two sentences, and the remaining routing guidance is dense but each clause carries actionable information. It is slightly run-on across the routing sentences, which keeps it from a 5.

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

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

An output schema exists, so return-value documentation is unnecessary; the description instead covers everything needed to call the tool correctly: the selector rule, id provenance for all three selector types, price/filter sourcing, and fallbacks for keyword and rating needs. Nothing material is missing for a read-only 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 description coverage is 100%, so the baseline is 3. The description goes beyond the per-field descriptions by establishing the cross-parameter invariant (exactly one of category_id/brand/tag_id) and by telling the agent where each id family is sourced (mk_categories, mk_brands, mk_filters), which is not derivable from the schema alone.

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

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

The first sentence names a specific verb (List) and resource (products of a category, brand or tag) plus the supported refinement dimensions (sorting, price range, filters). It is immediately distinguishable from mk_search (keyword) and mk_product (details) without opening either schema.

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

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

It gives concrete use cases ("cheapest Bluetooth earbuds", price-bounded power banks), states the exclusivity rule (pass exactly one of category_id/brand/tag_id), routes keyword queries to mk_search/mk_find_cheapest, and notes that rating sort is unavailable so mk_reviews should be consulted instead. Alternatives are named with the condition that selects them.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds context the annotations cannot: the approximate result size (~100 entries) and the fact that the payload contains ids meant to be threaded into other calls. No auth or rate-limit disclosure, but nothing is contradicted.

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

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

Two short sentences with no filler. The primary purpose and scope are front-loaded, and the routing/alternative information follows immediately.

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-optional-param read tool with an output schema, the definition covers purpose, result shape (ids, ~100 categories) and sibling routing. Return-value details are delegated to the output schema, which the rubric permits, so nothing an agent needs is missing.

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

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

Schema description coverage is 100% and the single optional `query` parameter is well documented in the schema, including Persian/English examples and a minLength constraint. The description never mentions the filter at all, so it adds no meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ("List MasterKala's product categories with their ids") plus a scope estimate ("about 100 main categories"), which tells the agent both what it returns and roughly how much. Combined with the sibling set (mk_brands, mk_filters), the wording makes clear this is the category taxonomy enumerator rather than a product or brand lookup.

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

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

Explicitly states the downstream use ("Use to get a category_id for mk_browse / mk_filters") and names the alternative for a different need ("mk_search also returns the categories matching a keyword"). The agent knows both when to call this and when a sibling is a better fit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive). The description adds non-obvious behavior beyond that: the result ordering (biggest discount first) and the meaning of the ends_in_seconds field. It does not discuss pagination or the limit's interaction with total result count, so it stops short of full coverage.

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

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

Front-loaded with the core purpose and efficient overall. The sentence explaining ends_in_seconds is slightly orphaned since that field does not appear in the input schema, adding minor noise to an otherwise tight 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?

Purpose, usage, and ordering are complete, and an output schema exists so return values need not be enumerated. The only mild gap is that pagination/result-count behavior is unstated, which matters for a listing tool with a capped limit.

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

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

Only one parameter (limit) and schema description coverage is 100%, so the schema fully documents it. The description adds no syntax, bounds, or default information beyond what the schema already provides; baseline 3 applies.

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

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

Specific verb + resource + scope ('List every product on MasterKala's discount page right now') plus an ordering guarantee ('biggest discount first'). It also explicitly separates itself from mk_search and mk_browse, which cover keyword/category discounts.

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?

States the triggering intents ('what's on sale' / 'best discounts today') and names the alternatives for a different scope (keyword or category discounts → mk_search / mk_browse). Both when-to-use and when-to-use-something-else are present.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context on top: long non-brand groups are cut to 40 options with an `omitted` count, and max_price is the most expensive item in Toman. These are non-obvious behaviors an agent must know to interpret the response 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?

Front-loaded with the core purpose, then a second paragraph covering the workflow and truncation caveat; every sentence carries information. The first sentence is slightly compressed ('with their ids, and its price range'), but nothing is wasted.

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

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

With an output schema present, the description needn't explain return shapes, and it correctly focuses on workflow (use before mk_browse), the id->filter_ids handoff, truncation limits, and price units. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100%, so each parameter is already documented (brand slug, group, tag_id, category_id). The description goes slightly beyond by explaining the output contract that connects parameters to results — group options map filter id -> name and those ids are what you pass as filter_ids. That cross-tool linkage adds value over the schema alone.

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

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

States a specific verb ('List') and resource ('the filters of a category, brand or tag page') plus what is returned (filter ids/names and price range). It is clearly distinguishable from siblings like mk_categories or mk_brands, which return different resources.

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

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

Explicitly says 'Use before mk_browse when the user wants a brand, color or feature inside a category', naming both the alternative tool and the selecting condition. It also tells the agent how to recover from truncated groups by asking for that group explicitly.

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

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

Annotations only cover the safety profile (read-only, idempotent, non-destructive); the description adds substantial behavior beyond them: it scans search results and stops early, filters to online-purchasable items, sorts by final_price after discount in Toman, explains the free-shipping threshold and bulky-item exception, and interprets complete=false as a signal to raise `scan`.

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

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

Front-loaded purpose, then usage trigger, then mechanics; every sentence adds information about scanning, sorting, or shipping. Slightly long but no waste.

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

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

An output schema exists so return shape need not be explained, yet the description still clarifies the one return value an agent must act on (complete=false) plus pricing and shipping semantics. Combined with the named mk_shipping alternative, nothing needed to call this correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3. The description earns an extra point by linking the output flag to the `scan` parameter ('complete=false ... raise scan') and by defining the sort key (final_price, after discount, Toman), which the schema does not state.

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

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

States a specific verb (find) plus resource and a tight qualifier ('cheapest in-stock products for a keyword'), and the sorting key ('payable price') makes it immediately distinguishable from generic siblings like mk_search or mk_deals without opening any schema.

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

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

Gives an explicit trigger ('Use when the user wants the lowest price for X') and routes the shipping-fee question to mk_shipping, which is a genuine alternative. It stops short of naming when NOT to use it (e.g. broad browsing vs. exact-price comparison), so it is clear but not exhaustive.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context about what the record contains (including which colors are buyable and which branches stock it), though some of that overlaps the output schema and it says nothing about auth or rate limits.

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

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

Front-loaded verb and scope in the first clause, then a compact field inventory, then a routing block. Every sentence earns its place and there is no filler.

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

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

For a single-parameter read tool with a full annotation set and an output schema, the description covers purpose, sequencing, and sibling handoffs. Return-value detail is not required given the output schema, so nothing an agent needs is missing.

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

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

Only one parameter, and the schema documents it at 100% coverage including the origin ('from mk_search / mk_browse') and a concrete example id. The description adds no additional meaning about product_id, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one product's full record') and enumerates the returned facets: price/discount in Toman, stock, colors, brand, category path, rating, and branches. This cleanly separates it from discovery siblings (mk_search, mk_browse) and from the drill-down siblings that cover adjacent data (mk_specs, mk_reviews, mk_shipping).

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

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

Explicit sequencing: 'Use after mk_search / mk_browse when the user picks a product' tells the agent exactly when to reach for this tool. It also routes four related needs to named alternatives, so there is no ambiguity about which sibling handles specs, reviews, or delivery.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds genuinely useful behavior: results are sorted newest first and include the store's replies plus a star breakdown. It does not cover pagination or result-size behavior, keeping it just short of fully transparent.

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

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

Two compact paragraphs with the resource and ordering constraint front-loaded. The trailing sentence on aggregate-field semantics is slightly output-schema territory given an output schema exists, but it earns its place by disambiguating count vs. the filter.

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

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

For a read-only, well-annotated tool with full schema coverage and an output schema, the description supplies everything an agent needs: the resource, sort order, what is included, and the intended use case. No material gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the final sentence adds meaning the schema does not: average and star_counts span ALL reviews while count reflects only those matching `stars`. That resolves a real ambiguity in how the aggregate fields relate to the `stars` filter.

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

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

The description names a specific verb and resource ('Read customer reviews of a product') and scopes it precisely with ordering (1-5 stars, newest first) and included data (store replies, star breakdown). An agent can distinguish this from mk_product, mk_specs, or mk_blog_comments without opening any schema.

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

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

'Use as a quality check before recommending a product' gives a clear when-to-use scenario, which is more than most read tools provide. It stops short of naming when not to use it or pointing to sibling tools for related data (e.g., mk_product for the product itself).

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: in-stock items are ranked first, and the result set also contains matching categories (usable as ids for mk_browse) plus brand/tag pages. It does not discuss rate limits or result-size caps, so it stops short of a 5.

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

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

Front-loaded with purpose and the returned fields in the first sentence, then routing rules in the second paragraph. Dense but every clause carries information; the sibling-routing list is the longest part and is justified by the number of overlapping siblings.

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 full-coverage schema, an output schema, and annotations covering the safety profile, the description only needs to supply routing and ordering semantics — which it does completely. An agent can select and call this tool without consulting any other definition.

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 page, limit, query and in_stock_only are already documented, including the Persian/English keyword examples and the empty-page semantics. The description reinforces the in-stock ordering but adds no new syntax or format detail, making the baseline 3 correct.

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

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

States a specific verb and resource ('Search MasterKala products by keyword') and names the returned fields (price, discount, stock), which is more than the title 'Search products' conveys. It is immediately distinguishable from mk_browse (category sorting/filtering) and mk_product (single-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?

Gives an explicit entry-point rule ('Use first for "price of X" / "do you have X"') and then routes to three named alternatives with the condition that selects each: mk_find_cheapest for the cheapest in-stock match, mk_browse for sorting/filtering a category, mk_product for full details of one product. Nothing 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavioral context beyond that: fees are in Toman with 0 = free, null means the item never ships free (bulky goods), same_day_seconds_left > 0 signals same-day delivery is still possible, and estimates assume a default Tehran address.

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 primary purpose and the usage trigger are front-loaded, followed by compact field-semantics notes. Every sentence carries information an agent needs (units, free-shipping condition, null meaning, same-day flag) with no filler.

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

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

With an output schema present, the description need not describe the return shape, and it correctly focuses on interpreting the returned values. Combined with rich annotations and a fully documented single parameter, nothing an agent needs to call this tool correctly is missing.

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

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

There is a single parameter and schema coverage is 100%; the schema already documents product_id, including where to obtain it ('from mk_search / mk_browse'). The description only reinforces the per-product scope and adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Get the nearest delivery slot and shipping fee for one product') and immediately scopes the geography ('Tehran courier and post to other cities'). No sibling tool (mk_search, mk_deals, mk_product, etc.) covers shipping, so the agent can route to this tool unambiguously.

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

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

It gives a concrete trigger phrase — 'Use for "when will it arrive / how much is shipping"' — and implies the per-product scope ('for one product'). It does not name an alternative or exclusion (e.g. how to get basket-level shipping for many items), so it stops short of explicit when-not 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: how spec rows align one value per product id, that a missing id yields no value, and that invalid ids surface in not_found.

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

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

Three tight sentences, zero filler. The core action and cardinality lead, followed by use cases, then edge-case behavior — well front-loaded and appropriately sized for a single-parameter 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?

With an output schema present, return formatting need not be explained, yet the description still covers the two things an agent would otherwise guess wrong: row alignment and not_found handling. Annotations carry the safety profile, so nothing material is missing.

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

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

Schema coverage is 100% and the schema already documents the 1-4 id array with an example, so the baseline is 3. The description adds real semantics on top: the positional contract between product ids and each spec row, and the silent-omission behavior for ids lacking a value.

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

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

States a specific verb and resource: 'Get the specification table of 1-4 products side by side, with each product's stock count.' The '1-4 products side by side' framing implicitly separates it from the single-product sibling mk_product, but no sibling is named explicitly, so it falls short of the 5 benchmark.

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

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

Gives concrete trigger phrasings: 'Use for "battery life / Bluetooth version of X" or to compare products row by row.' That is clear when-to-use context, but there is no when-not-to-use guidance or explicit routing to alternatives such as mk_product or mk_filters.

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