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

readOnlyHint=true already establishes the safe-read profile, so the description only needs to add context. It contributes the thread/reply grouping model, but the truncation behavior (400 chars, 3 replies) and the full_text escape hatch live only in the schema. Modest value added beyond 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 short sentences, zero filler, with the core behavior front-loaded and the use-case context second. 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?

No output schema exists, but the description communicates the return shape (threads with replies) and the read-only nature is covered by annotations. An agent has enough to call it correctly; only the response envelope details remain unstated.

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 limit, post_id and full_text are fully documented in-schema including the truncation defaults. The description adds no parameter syntax or format detail beyond that, 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 – reading a blog post's comments as threads with writer replies. Clearly separable from mk_blog_posts (which supplies the post_id) and from other mk_* tools. Lacks an explicit sibling comparison, but the resource distinction 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?

"Useful as a support FAQ: many posts hold readers' product questions answered by MasterKala" gives a concrete scenario for when an agent should reach for this tool. No exclusions or named alternatives are provided, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavior the annotations do not: newest-first ordering and that results carry links, which matters because there is no output schema. It does not disclose the notable default (category defaults to 'buying_guide', so results are filtered unless overridden) or any pagination/rate-limit behavior.

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

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

Two tight sentences: the core listing behavior and ordering are front-loaded, followed by the usage/routing sentence. No filler or repetition of the name.

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, three-parameter list tool with no output schema, the description covers purpose, ordering and result shape ('with links') adequately. The only meaningful omission is the default category filter, which changes what an agent actually receives when it omits that parameter.

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 already documented in the schema, establishing the baseline of 3. The description's parenthetical content types loosely mirror several enum values but adds no syntax or defaulting detail, and it omits the consequential default of category='buying_guide'.

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 blog posts'), the content types covered (buying guides, comparisons, how-tos), the ordering ('newest first') and the return shape ('with links'). It also distinguishes itself from the sibling mk_blog_comments, which handles a different content type.

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 asks which product type to choose or how to use a gadget') and routes reader questions to the sibling mk_blog_comments. It stops short of excluding other plausibly competing siblings such as mk_reviews or mk_search for the same intent, so the routing 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=true, so the safety profile is covered. The description adds genuinely non-obvious operational context: shops stock only part of the catalog and the user should call before visiting, which meaningfully shapes how the agent presents results.

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 sentences with no filler: the what/where/returns statement comes first, then the usage trigger and cross-reference. 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?

With no parameters and no output schema, the description still tells the agent what comes back (address, phone, map location) and the caveat about partial stock. Nothing needed to call or interpret this tool is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline applies. No param-level detail is missing or misleading.

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

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

States a specific verb+resource ('List MasterKala's physical shops') and scopes it to Tehran while enumerating the returned fields (address, phone, map location). It also positions itself relative to mk_product, so an agent can distinguish it from sibling lookup tools without opening a 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 to buy in person') and points at the complementary tool for a different question (mk_product's `branches` for per-product availability). It stops short of naming when NOT to use this list, but the routing guidance is concrete.

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?

readOnlyHint=true already covers the safety profile, so the description only needs to add context. It adds the result size (~135) and the value format (slugs), but says nothing about pagination, ordering, or what non-matching queries return.

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 front-loaded and the consumption guidance second. Nothing could be removed without losing signal.

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

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

For a simple read-only listing with no output schema, the description supplies enough: what it returns, roughly how many, and the identifier format that downstream tools need. Return shape and pagination are left implicit, which is a minor gap given the tool's simplicity.

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

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

The single 'query' parameter already has a full schema description (100% coverage) covering its optionality, min length and English-only constraint. The description adds no further parameter detail, 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?

Specific verb+resource: 'List the brands MasterKala sells with their slugs', and it quantifies scope ('about 135') and gives concrete slug examples ('anker-fa', 'mcdodo'). This clearly separates it from siblings like mk_categories or mk_filters.

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 a use case and names the downstream siblings that consume its output ('Use to get the brand slug for mk_browse / mk_filters'). It does not state when not to use it or compare against other discovery tools, so it stops short of the top score.

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?

readOnlyHint=true already establishes this as a safe read, so the bar is lower; the description still adds a real behavioral constraint the schema does not enforce — mutual exclusivity of category_id, brand and tag_id. It does not describe return shape or pagination semantics, which is the remaining gap.

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?

Four tight sentences: purpose and scope first, worked examples second, the exclusivity constraint and id sources third, exclusions last. No filler and the most decision-relevant content is front-loaded.

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

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

For a 9-parameter, zero-required, no-output-schema browse tool with only a readOnlyHint, the description covers selection rules, id provenance and alternatives to siblings. It omits result/pagination behavior, but with the schema carrying full parameter documentation the definition is largely sufficient to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, and the schema already documents every parameter with examples. The description goes slightly beyond by stating where each id family comes from (mk_categories, mk_brands, mk_search, mk_filters) and imposing the exactly-one-of relationship among the three selector 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?

States a specific verb (List) and resource (products of a category, brand or tag) plus the facets it supports (sorting, price range, filters). It also explicitly separates itself from siblings by noting there is no keyword or rating sort here, pointing to mk_search / mk_reviews instead.

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 triggering queries ("cheapest Bluetooth earbuds", "Xiaomi power banks between 1 and 2 million Toman") and states the hard selection rule: pass exactly one of category_id / brand / tag_id. It names the alternatives for id lookups and for keyword/rating sorting, leaving nothing 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?

The readOnlyHint=true annotation already establishes this as a safe read, so the bar is lower. The description adds useful context (the catalog size, the return of ids), but says nothing about ordering, pagination, or completeness beyond the ~100 figure.

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 resource and the downstream use (category_id) front-loaded. 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?

For a simple read-only list tool with a fully documented single param and no output schema, this covers what an agent needs: what it returns (ids), how many, and why to call it. Only the optional query filter goes unmentioned in prose.

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' param is fully documented in the schema (Persian name / English slug, examples). The description does not mention the filter at all, so it adds nothing on this dimension; 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 precise verb+resource ('List MasterKala's product categories with their ids') and adds scale ('about 100 main categories'). It also distinguishes itself from the sibling mk_search, which returns categories by keyword.

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 when to use it: to obtain a category_id for mk_browse / mk_filters. It also names the alternative (mk_search) and the condition that selects it, so the agent can route without opening other schemas.

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 declare readOnlyHint=true; the description adds the result ordering (biggest discount first) and explains that ends_in_seconds is the remaining time in the current offer period, which is real behavioral context with no output schema to carry it. It doesn't mention pagination or result-count behavior, so it stops short of full transparency.

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

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

Three short sentences, front-loaded with the core action and ordering, then trigger phrases, then sibling routing. Every sentence carries information and there is no padding.

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

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

With no output schema, the description helpfully clarifies one return field (ends_in_seconds) and the sort order, which is enough for an agent to call and interpret results. Minor gaps remain around pagination or whether the list is capped beyond the limit parameter.

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 (limit) whose schema coverage is 100%, so the schema already documents it fully. The description adds nothing about limit usage, which is the expected baseline for a fully-covered schema.

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

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

States a specific verb and resource (list products on the discount page), plus scope ('right now') and ordering ('biggest discount first'). It explicitly separates itself from mk_search/mk_browse for keyword- or category-scoped discounts, so an agent can distinguish it 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 direct trigger phrases ('what's on sale' / 'best discounts today') and names the alternative tools with the condition that selects them (discounts inside a keyword or category). It covers both when to use it and when to route elsewhere.

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?

readOnlyHint=true already establishes the safety profile, but the description adds real behavioral detail beyond it: non-brand groups are truncated to 40 options, `omitted` holds the remainder, and `group` returns the full set. It stops short of return format or any rate/ordering notes, so it is strong but not 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?

Three tight sentences, front-loaded with the core purpose and then the routing/workflow guidance. The back-half is somewhat dialect-specific and elliptical ('`omitted` = the rest', 'max_price = ... (Toman)'), 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?

For a read-only discovery tool with no output schema, the description adequately conveys what comes back (filter ids with names, price range) and the truncation caveat. An agent has enough to call it correctly and interpret the result, though exact response shape is only implied.

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 each parameter is already documented in the schema; the baseline is 3. The description reinforces usage (max_price = most expensive item in Toman, `group` semantics, filter_ids linking) but does not add syntax or format detail the schema lacks.

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

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

States a specific verb ('List the filters') and resource ('of a category, brand or tag page') with concrete examples of what filters are returned (brands, colors, attributes) plus the price range. An agent can distinguish this from mk_categories, mk_brands, 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 alternative and the condition: 'Use before mk_browse for a brand, color or feature filter.' It also explains the workflow contract ('options map filter id -> name; pass the ids as filter_ids') and the workaround for truncation ('pass `group` for all'), leaving little 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 only declare readOnlyHint=true, so the description carries the rest: it discloses the free-shipping threshold (5,000,000 Toman), the bulky-item exception, and the early-stop/`complete=false` scanning behavior with a remedy ('raise scan'). That is meaningful behavioral context beyond the annotation, though return format details remain unstated.

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 usage in the first two lines, then dense terse fragments for edge rules. Efficient, though the telegraphic 'complete=false: ... raise scan' phrasing is slightly compressed at the cost of 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?

With no output schema, the description fortunately explains key return semantics (flat list, payable-price sort, complete flag, scanned boundary) and the shipping caveat. A short note on result fields or pagination would make it fully complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by tying the `scan` parameter to output behavior ('in-stock items go past scanned, raise scan') and clarifying that free_shipping for bulky items behaves differently. It goes beyond restating the schema.

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

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

States a precise verb+resource+scope: cheapest in-stock products for a keyword, returned as one flat list sorted by payable price. This clearly distinguishes it from siblings like mk_search or mk_deals, which do not promise price-sorted stock filtering.

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 'Use when the user wants the lowest price for X' and names an alternative destination for adjacent needs (exact fee and date -> mk_shipping). The agent can route correctly without opening any schema.

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

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

The annotations only provide readOnlyHint=true, so the description must carry most behavioral weight. It discloses the rich payload structure (price/discount in Toman, stock status/count, colors and buyable status, brand, category path, rating, physical branches) and the default truncation of product descriptions at 300 chars, but doesn't mention pagination, rate limits, or error conditions.

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 action and payload summary, then two efficient sentences for usage and cross-references. The 300-char truncation detail in the schema is complemented by 'Return the description uncut' in the description, keeping the body tight 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 read-only single-record fetch tool with two simple parameters and full schema coverage, the description covers purpose, usage routing, and returned data structure. It would benefit from a note on behavior when product_id is invalid, but overall it is 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 description coverage is 100%, so the schema already documents both parameters (product_id and full_text). The description adds no parameter-level details beyond the schema, which matches the baseline 3 for full 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 ('Get one product's full record') and then enumerates the returned fields, leaving no ambiguity about what the tool does. This is clearly distinct from siblings like mk_search (search) and mk_specs (specifications).

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 ('Use after mk_search / mk_browse when the user picks a product') and routes three related concerns to their proper tools (mk_specs, mk_reviews, mk_shipping). This is textbook 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?

readOnlyHint=true already establishes the safe-read profile, so the description builds on that by disclosing ordering (newest first), that replies are included, and that text is uncut by default. It also discloses non-obvious semantics: 'average and star_counts cover all reviews; count is the number matching stars' — a subtle aggregate-vs-filter distinction an agent would otherwise get wrong. Pagination and rate-limit behavior remain unstated.

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, front-loaded with the core capability and followed by a crisp behavioral footnote. No filler or redundant restatement of the schema.

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

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

With no output schema, the description carries the return-value burden and does reasonably well: it names the aggregate fields (average, star_counts, count), notes replies and the star breakdown, and clarifies their scope. The full response shape (field names/types beyond the three named) is still implicit, keeping it just short of complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot: the interaction between the stars filter and the aggregate fields (average/star_counts unfiltered vs count filtered). The 400-char default cut is repeated from the schema, but the aggregate semantics is genuine added 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 (read) and resource (customer reviews of a product) plus scope details: 1-5 stars, newest first, includes store replies and star breakdown. An agent can immediately distinguish this from siblings like mk_product, mk_specs, or mk_search without opening a 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 frames usage: 'Use as a quality check before recommending a product,' which gives the agent a clear decision context. It stops short of naming alternatives or when-not conditions (e.g., when mk_product's rating summary is enough), so it is clear context without exclusion 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?

With readOnlyHint=true already covering the safety profile, the description adds genuine behavioral context beyond annotations: in-stock results are ordered first, and the response also contains matching categories (with ids for mk_browse) and brand/tag pages. It does not mention pagination limits or result-size constraints, so it stops short of full 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?

Three short sentences, front-loaded with purpose then routing, with zero filler. Every clause carries information an agent needs for selection.

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

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

There is no output schema, yet the description enumerates the return payload (price, discount, stock, categories, brand/tag pages) and the ordering rule, while parameters are fully covered by the schema. An agent has everything needed to call and interpret this 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 query, page, limit and in_stock_only are all documented in the schema itself, including the empty-page semantics. The description only gestures at keyword search and stock ordering, adding no syntax or format detail beyond the structured fields; 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 ('Search MasterKala products by keyword') plus the payload returned (price, discount, stock per match), which is exactly what an agent needs to distinguish this from siblings like mk_browse or mk_product.

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

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

Gives an explicit trigger ('Use first for "price of X" / "do you have X"') and names both routing alternatives with their conditions: mk_find_cheapest for cheapest and mk_product for a single 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 only supply readOnlyHint=true, but the description discloses real operational semantics: fees are Toman with 0 = free, the free_shipping_from threshold (null = never free), the same_day_seconds_left > 0 cutoff for same-day Tehran delivery, and that estimates assume a default Tehran address. These caveats materially affect how the agent should interpret and present results.

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, then usage trigger, then output semantics in compact form; every sentence carries information. The dense field-name shorthand (same_day_seconds_left, free_shipping_from) is slightly cryptic but defensible for an agent-facing spec.

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

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

With no output schema and only one parameter, the description compensates well by explaining the return values' meaning and the Tehran-default assumption. It leaves the shape of the 'delivery slot' itself and behavior on an invalid product_id unaddressed, so not fully complete.

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

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

Schema description coverage is 100% and the single parameter is documented ('MasterKala product id from mk_search / mk_browse, e.g. 24855'), so the schema does the heavy lifting. The description adds no syntax or format detail beyond it, making the baseline 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?

Specific verb+resource: 'Get the nearest delivery slot and shipping fee for one product', with scope narrowed to Tehran courier vs. post elsewhere. No sibling tool covers shipping, so it is uniquely identifiable in the toolset.

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?

Routes the agent by user intent: 'Use for "when will it arrive / how much is shipping"'. That is clear when-to-use guidance, though it names no alternatives or exclusions (none of the siblings overlap, so this is a minor gap).

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, so the safety profile is covered; the description adds genuinely new behavioral detail: the 1-4 product cap, that a missing product id in a row means no value, and that nonexistent ids are surfaced in not_found. These edge-case and error-handling semantics are exactly the kind of context structured fields don't carry.

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 is front-loaded in sentence one, followed by usage triggers and then response-shape caveats. No filler, no repetition of the schema, and every sentence adds 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 no output schema, the description carries the burden of explaining the return shape, and it does: a spec table with per-product values and a not_found list. Minor gaps remain around value formatting/units and whether stock count is always present, but nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented, so baseline would be 3. The description earns the extra point by extending product_ids semantics into the response: one value per id, absent ids produce no value, invalid ids land in not_found.

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 (get) and resource (specification table) with explicit scope: 1-4 products side by side plus stock count. This cleanly distinguishes it from generic siblings like mk_product or mk_search, which would not return a comparative row-per-spec table.

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 triggering use cases ('battery life / Bluetooth version of X', row-by-row comparison), which is clear contextual guidance. It stops short of naming an alternative sibling (e.g., when to prefer mk_product for a single product), so it is not a full when/when-not treatment.

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