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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds real behavioral context beyond them: content is Persian, images are stripped, long reviews can run to tens of thousands of characters, the response exposes total_chars to drive pagination, and press-release text may be unverified. It does not specify error behavior for bad ids, which keeps it out of the top band.

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 purpose in the first sentence, then a short second paragraph covering sourcing and pagination. The closing advisory on press-release text is mildly editorial but is short and plausibly useful for an agent quoting content.

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, so the description carries the burden of hinting at the return shape, which it does via total_chars and the dropped-images note. Combined with pagination guidance and identifier sourcing, an agent has enough to call the tool correctly, though the full response shape (title, date, author) is left 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 every parameter including the source enum, phone_id conditional requirement, offset and max_chars is already documented. The description reinforces where the identifiers come from and ties offset to the total_chars field, but adds no syntax or format detail beyond the schema. Baseline 3 applies when 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?

States a specific verb and resource ('Read the text of one Mobile.ir news item, expert review or product introduction') and makes the single-item scope explicit, which cleanly separates it from the sibling listing tool mi_articles. An agent can distinguish the two 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?

Gives an explicit prerequisite chain ('Get source, id and phone_id from mi_articles') and tells the agent how to continue when the body is truncated ('call again with offset'). It stops short of stating when NOT to use it (e.g. search or comment retrieval, which belong to mi_search/mi_comments), so it is clear context rather than full routing.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral facts: results are ordered newest first, news search is capped at 100 hits, and reviews are the paged/kind-scoped side of the tool. It does not spell out pagination limits beyond the schema's per-page counts, which keeps it from 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?

Two short blocks, front-loaded with the core listing behavior, then usage examples and the follow-up tool. No filler sentences, though the phrase "passing back its `source`, `id` and (for reviews) `phone_id`" is slightly dense for the amount of information it carries.

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 six optional parameters, no output schema, and rich annotations, the description covers ordering, the 100-hit cap, the news-vs-reviews split, and the key result fields needed for follow-up. A brief note on what a result object otherwise contains would make it fully 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%, so the baseline is 3; the description still earns above baseline by explaining that filtering is "optionally for one phone or brand" and by tying `source`/`id`/`phone_id` to the downstream mi_article call. That cross-tool meaning is not present in 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?

"List the news and the expert reviews on Mobile.ir, newest first, optionally for one phone or brand" gives a specific verb (list), specific resource (news/reviews), scope (one phone or brand) and ordering. It also separates this tool from its closest sibling by pointing at mi_article for reading a single result.

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 supplies concrete trigger phrases ("is there a review of X", "latest news about Samsung", "what is new") and names the follow-up tool mi_article with the exact fields to hand back. It stops short of saying when to prefer the sibling search tools (mi_search, mi_find, mi_used_search), so the routing guidance 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 readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuine context: the tool paginates over a fixed brand-scoped corpus and returns a compact field set including lowest shop price. It does not state how to detect the last page or how many pages exist, which is the one remaining behavioral 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?

Three short sentences, each earning its place: what it does and returns, when to choose it, and where to go instead. The use case is front-loaded with no redundant repetition of schema fields.

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

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

With no output schema, the description usefully enumerates the returned fields, and all six parameters are documented in the schema, so an agent can call this correctly. The only shortfall is that pagination termination (total pages or model count) is never hinted at for a tool explicitly built for paging.

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 each parameter already carries a description, including the brand-name-or-id hint and page size, so the schema does the heavy lifting. The description adds no parameter-level detail such as sort semantics or interaction between only_priced and price sorting. 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 — paging through all models Mobile.ir lists for one brand — and enumerates the returned fields (id, rating, year, screen, camera, lowest shop price). This is clearly distinguishable from sibling listing tools like mi_find and mi_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?

Gives an explicit trigger ('when mi_find's 100-row cap is too small or you want a brand's full line-up') plus explicit exclusions and their replacements ('Narrow by price or camera with mi_find instead'). It also routes single-model and comparison cases to mi_phone and mi_compare respectively.

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 new context — that content is unverified user-generated text and that author names are deliberately omitted. With no output schema, the note about Persian-calendar dates and the `reply_to` threading field is also useful disclosure about what comes back.

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 front-loaded sentences with no padding: purpose first, usage second, content caveats third. The closing `reply_to` sentence is somewhat orphaned since it describes a response field rather than a parameter, which slightly muddies an otherwise tight structure.

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 three-parameter read tool with no output schema, the description covers what matters: the device scope, the fields returned, the unverified nature of the content, and the absence of author names. Pagination/sort behavior and the limit cap are left to the schema, which documents them adequately, so nothing essential 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 all three parameters (id, sort, limit) are fully documented in the schema including the enum meaning for 'helpful' and the id provenance. The description's only parameter-adjacent sentence explains `reply_to`, which is actually a return field rather than an input, so it adds no input-side semantics beyond the schema.

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

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

States a specific verb and resource ('Read what Mobile.ir users wrote about a phone, tablet or watch') and enumerates the returned content, so the agent knows exactly what this tool produces. It also positions itself against the sibling mi_phone by framing itself as the qualitative counterpart to that tool's rating.

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 to use it 'for real-world opinions (battery, camera, durability) next to mi_phone's rating', which gives a clear situational trigger and names the complementary sibling. It stops short of stating exclusions (e.g., when to prefer mi_articles or mi_used_ad for opinion content), so it is clear context rather than a full when/when-not matrix.

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 open-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: result values follow the order of the input ids, and by default only differing rows are returned so output stays short. It does not describe pagination or response size limits, but for a bounded 2–4 item comparison that is minor.

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

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

Two short paragraphs with the capability stated first and the workflow/behavior second; no filler sentences. The dangling reference to `phones` is the one element that costs the reader a moment of confusion.

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, yet the description characterizes the return well enough (price range, rating, per-spec rows, difference-only filtering, input-ordered values). Combined with full schema coverage and read-only annotations, an agent has what it needs to call this correctly; only the stale `phones` reference is 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?

Schema coverage is 100%, so all three parameters are already documented, making 3 the baseline. The description reinforces the intent of `only_differences` (short answers by default) and the focusing role of `sections`, but it also refers to `phones` when the actual parameter is `ids`, a naming mismatch that slightly muddies rather than clarifies.

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 (compare) with a bounded resource set (2 to 4 phones, tablets or watches) and names exactly what the output contains: price range, rating and each spec row side by side. An agent can distinguish this from mi_phone (single product) or mi_search (discovery) 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 sequences the tool after mi_search or mi_find and gives the triggering condition ('when the user is choosing between models'). It stops short of naming the negative case — e.g. that a single-model question should go to mi_phone — so it is clear but not fully routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real behavioral content: the returned fields, the side effect that a price filter silently drops unpriced phones, and the hard 100-row ceiling with a corrective action when results overflow. The only soft spot is the mention of `found`, which is neither a schema parameter nor in the listed return fields, leaving its meaning slightly ambiguous.

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 sentence is front-loaded and the second paragraph packs return shape, alternatives and the limit escape hatch without filler. Slight density (many clauses per sentence) and the unexplained `found` token cost a point.

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 14-parameter, zero-required discovery tool with no output schema, the description supplies what the schema cannot: the shape of returned cards and truncation behavior. Adding a clarifying note on `found` and on recursion into mi_options('brands') would make it fully 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 description coverage is 100%, so every parameter is already documented with enums, defaults and boundaries; the description only paraphrases the filter facets. The one genuine addition is the note that price filtering excludes phones without a shop price, which duplicates rather than extends the min_price description. 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 ('Filter Mobile.ir's phone database') and enumerates the filterable facets (brand, shop price range, OS, camera, weight, name). It also names what it is not, pointing to mi_phone and mi_shop_prices, so an agent can place it among the 16 siblings without opening the schema.

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

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

It gives explicit follow-up routing ('Use mi_phone for the full spec of one result and mi_shop_prices to see who sells it') and a recovery instruction when `found` exceeds `limit`. It does not, however, distinguish this tool from the other search siblings (mi_search, mi_used_search, mi_sim_search), so the when-to-use story is incomplete against the full sibling set.

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 open-world, so the safety profile is covered. The description adds non-obvious behavior beyond them: result de-duplication (one row per shop and model), the price currency (Toman), and the fact that memory/RAM variants live in `note` on the model page. It stops short of describing pagination limits or how far back the index goes, which keeps it from 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?

Three short sentences, front-loaded with what the tool returns and its row granularity, then routing guidance, then units/caveats. No filler or restatement of the name beyond the necessary scope detail.

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 12-parameter, all-optional read tool with strong annotations and no output schema, the description covers purpose, alternative routing, units and dedup semantics. It leaves minor gaps: nothing about result volume or how 'newest' interacts with sort/descending, and no hint that page/page_size bound the response size.

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 every parameter with defaults, enums and even province id examples, so the baseline is 3. The description adds marginal but real meaning: prices are Toman 'as posted by the shop' and variant distinctions are not separate filters but a `note` field, which prevents an agent from hunting for a memory/RAM parameter.

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

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

States a specific verb and resource ('List the newest price rows that shops posted on Mobile.ir') plus the crucial granularity rule 'one row per shop and model'. It explicitly distinguishes itself from the sibling mi_shop_prices, so an agent can choose between them 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?

'Use it for "cheapest/newest Xiaomi prices in Isfahan" type questions' gives a concrete trigger scenario that maps onto the actual filter parameters (price, date, province). 'For one model's full offer list use mi_shop_prices' names the alternative and the condition that selects 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is fully covered. The description adds the useful behavioral fact that this is an id-lookup dependency for other tools, but says nothing about response size, ordering, or whether names accompany ids; with annotations carrying the safety burden, a 3 is appropriate.

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 paragraphs, front-loaded with the core purpose and followed by the trigger condition and one caveat. No filler, and the most actionable guidance (when to call it) is not buried.

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, and the description does communicate the return shape ('list the ids'), which is the key thing an agent needs. It leaves open whether the response pairs ids with display names or how long the lists are, a minor gap for a single-enum lookup 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 0% and there is one parameter, but the description supplies meaning beyond the bare enum: 'shops' is qualified as 'price-listing shops' and 'operators' as 'SIM operator prefixes', which disambiguates what those enum values actually enumerate. The `what` parameter name itself is never explained, but the four values are.

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 ids') and enumerates exactly which id families it covers, while framing itself as the dependency resolver for the other Mobile.ir tools. An agent can immediately tell it apart from siblings like mi_brand_models or mi_shop_prices because it returns ids rather than data.

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

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

'Call it when a tool needs a brand, province or shop id you do not have' gives an explicit trigger condition. It also carves out an exception — brand names are accepted directly by `brand` arguments — which implicitly says when this tool is NOT needed for brands, though that carve-out is stated as a note rather than a clear exclusion.

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 openWorld, so the safety profile is covered. The description contributes a genuine caveat beyond that — values come back in Persian/English as the site has them — which warns the agent about mixed-language output. It says nothing about response size limits, pagination, or failure behavior for an invalid id.

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 leading sentence delivers purpose, scope and source immediately, followed by a data-fidelity caveat and a routing hint — no filler. The parenthetical field list is slightly redundant given the sections enum, but it still helps set expectations for what 'full specification' means.

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 two-parameter lookup with a fully documented schema, the description covers identity, source, output shape at a field level, and downstream tool sequencing. With no output schema, slightly more on the actual return structure (single object, units, truncation with sections) would have completed it.

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%, with the id sourced from mi_search/mi_find/mi_market_prices and the sections enum fully documented, so the baseline is 3. The description's field list (display, chipset, RAM/storage, cameras, battery, launch date, SIM, network bands) loosely maps to the section values but adds no rules about combining sections or the cost of requesting all.

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 full specification sheet of one phone, tablet or smartwatch') plus the data source (Mobile.ir) and what is bundled in (rating and price range). The enumerations of spec areas make it unambiguous how this differs from retrieval siblings like mi_search or mi_compare.

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 routes the agent onward: 'Call mi_shop_prices next for who sells it and mi_price_history for the trend,' which defines the boundary between this tool and the pricing siblings. It stops short of stating when to prefer mi_compare instead of pulling raw specs, so no full 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 establish that this is a read-only, idempotent, non-destructive, open-world tool. Beyond that, the description adds useful behavioral context: the data source, the specific aggregations returned, the currency unit, and the caveat that shops may quote different variants. It still does not describe data freshness, coverage gaps, or rate limits, but the added context is meaningful.

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 paragraphs with the purpose front-loaded and the interpretive guidance following immediately. Every sentence contributes either scope or usage guidance, and there is 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?

For a simple read-only tool with three fully documented parameters, safety annotations, and no output schema, the description does the remaining work: it explains what the returned price history contains, the unit, and how to interpret the daily lowest figure. Nothing critical for correct invocation appears to be 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 all three parameters are already documented in the schema, including the product id source, the period enum, and shop_id filtering. The description does not add parameter-specific meaning beyond what the schema provides, 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: getting a phone's shop-price history from Mobile.ir. It also names the returned aggregates (per-shop first/last/min/max and daily lowest price), making the scope clear. It does not explicitly distinguish itself from siblings such as mi_market_prices or mi_shop_prices, so it falls short of a 5.

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

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

The description gives a clear use context: answering whether a price is rising, falling or fair, and it advises using the daily lowest rather than a single shop for market trend. It does not explicitly name alternative tools or state when-not-to-use conditions, so it is strong but not a full alternatives-based 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 readOnly, idempotent, and non-destructive, so safety is covered. The description adds useful context beyond that: this is an autocomplete-style lookup returning up to about 20 ids rather than full records, which implies the agent must chain follow-up calls. It stops short of saying how ambiguity or zero results are handled.

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

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

Three short sentences, each earning its place: what it returns, what to call next, and which sibling to use instead. The scoping and result-limit information is front-loaded.

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

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

For a single-parameter lookup without an output schema, the description supplies what the schema cannot: the return shape (ids, ~20 max) and the downstream tools. Nothing an agent needs to invoke it correctly in a chain 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 query string with English/Persian examples and length bounds. The description adds little beyond confirming name-based matching; the baseline of 3 applies when 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?

States a specific verb (find), resource (phones, tablets, smartwatches), source (Mobile.ir), and output (ids), plus a result-count bound. It also names the sibling that handles the other case (mi_find), 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?

Explicit sequencing: call this first when the user names a model, then mi_phone for specs or mi_shop_prices for prices. It also gives an exclusion with a named alternative — mi_find for price range, brand, or camera filters — so there is no ambiguity about when not 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?

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description's job is to add context — and it does, disclosing that phone numbers and e-mail are withheld and that `shop_url` exposes them on the site. That is a real, non-obvious output limitation. It doesn't discuss pagination limits or error behavior, keeping it just 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?

Three tight sentences: what it does first, usage triggers second, caveat last. No filler, no restatement of the title, and the sibling routing is placed where an agent will read it.

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 4-parameter read-only lookup with no output schema, the definition covers purpose, selection criteria, the alternative tool, and the notable omission of contact details. A brief note on result ordering or typical volume would make it fully 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%, so page, brand, shop_id and name_contains are already documented in the schema. The description adds only the currency unit (Toman) and a hint that shop_id comes from mi_options('shops') or mi_shop_prices — useful but marginal. 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: 'Show one Mobile.ir shop's profile and the phones it lists with their current prices in Toman.' The scope ('one shop') is explicit and immediately distinguishes it from the sibling mi_shop_prices, which is named.

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 when-to-use triggers ('what does shop X sell', comparing a shop's prices for a brand) and an explicit routing rule: 'For one model across all shops use mi_shop_prices.' That is the when/when-not/alternative pattern at full strength.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is to add context, and it does: prices are in Toman, the result is sorted cheapest-first, per-shop notes explain price differences, and shops are advertisers the site does not vouch for — a meaningful trust caveat. It omits any statement about result caps or what happens when no shop currently lists the product.

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 that front-load the outcome, then the caveat that makes the numbers interpretable, then the trust warning. Every sentence earns its place; the only weakness is the slightly awkward mid-sentence break around 'read the note. Cheapest first.'

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

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

With no output schema, the description usefully compensates by naming the returned fields and the sort order, and annotations cover the safety profile. It is nearly complete for a simple read-only list tool, missing only edge-case behavior (empty results, stale vs. current pricing beyond the include_old flag).

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 `id` even pointing at the sibling tools that produce it and `include_old` fully explained, so the baseline is 3. The description adds no parameter-level meaning of its own and never mentions include_old or how expired prices affect the cheapest-first ordering.

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 — listing per-shop current prices for a given phone on Mobile.ir — and enumerates the returned fields (price in Toman, shop, city, note, warranty). It does not explicitly contrast itself with the closest siblings (mi_market_prices, mi_price_history), so an agent must infer the distinction from the name alone.

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

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

Implied usage is clear (you want shop-by-shop offers for a known product id) and it adds a reading instruction ('read the note') plus an ordering guarantee ('Cheapest first'). However, it never says when to prefer this over mi_market_prices or mi_price_history, and there are no explicit 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?

The annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the description only needs to add context. It does: it discloses that seller names and phone numbers are absent from results and that contact happens outside the tool via `url`, which is exactly the kind of privacy/return-shape fact annotations cannot convey.

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 paragraphs, front-loaded with the resource and destination site before the filter list. The second paragraph packs several unrelated facts (filters, contact rules, number format) into one block without bullets, but no sentence is padding.

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

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

For a 14-parameter, no-output-schema search tool with strong annotations, the description covers the essentials: what is searched, what can be filtered, and what is deliberately withheld from results. Pagination and price-sorting edge cases live in the schema, and with no output schema present the absence of a fuller return-value description is a minor gap rather than a blocking one.

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; every one of the 14 parameters is already documented, including the operator ranges and the `prefix` overrides `operator` rule. The description's filter recap adds only the 'endswith 1111' framing, and its line that '`number` is the full 11-digit number as sold' is ambiguous against the schema's `number` parameter (the 7-digit subscriber part), which could mislead rather than clarify.

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 — searching SIM card numbers listed for sale on Mobile.ir — and names the domain (Iran's numbered-SIM market) and the fields carried (operator, number, price). It does not differentiate itself from siblings such as mi_sim_summary or mi_used_search, so an agent must infer the split between listing search and summary.

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 second paragraph gives clear operating context: which facets can be filtered, that seller identities are withheld, and that `url` must be opened on the site to make contact. It stops short of explicit when-not or alternative-tool routing (e.g. when to use mi_sim_summary instead), so it lands just under the top band.

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

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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, and the description still adds real behavioral context: prices are in Toman and many ads are price-less (negotiable) and counted only in `ads`. It doesn't cover freshness guarantees, caching, or result limits, 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?

Three short sentences, output shape front-loaded, followed by use cases and then the sibling routing hint. No filler and no repetition of the tool name or 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 five optional params and no output schema, the description reasonably carries the return-value burden by specifying ad counts plus three cheapest prices per operator, and it flags the price-less-ad caveat that affects how those cheapest slots are populated. Minor gaps remain: whether counts span all operators in one response and how many operators are returned.

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% with three enums, so the schema already documents all five parameters. The description's only parameter-relevant contribution is that prices are Toman, which the schema itself states for min_price, so this is baseline 3 with no meaningful added semantics.

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 gives a specific verb (summarise), a specific resource (numbered-SIM market on Mobile.ir), and the exact output shape: per-operator ad counts and the three cheapest priced numbers. It also explicitly contrasts itself with mi_sim_search for drill-down, so an agent can choose between them 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?

Concrete trigger phrases ('how many Irancell numbers are for sale', 'cheapest Rightel number') make the when-to-use case unambiguous, and the alternative path is named: drill into one operator with mi_sim_search. It doesn't state explicit exclusions, but the sibling pointer effectively covers the main branch point.

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 read-only, idempotent and non-destructive behavior, and the description adds genuinely non-obvious context beyond them: seller name and phone are withheld as personal data, the url is where those appear to signed-in visitors, and market_price_toman is the site's own estimate rather than an observed price. That is real disclosure of data quirks an agent could otherwise misread.

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 field enumeration is front-loaded and earns its place because there is no output schema; the two trailing caveat sentences are short and purposeful. Slightly list-like phrasing but no wasted prose.

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 one required parameter, no output schema, and full annotation coverage, the description does what it must: it previews the return fields and flags the two data caveats (missing contact info, estimated market price). Only the lack of guidance on follow-up tools or error behavior keeps it from the top score.

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 documented as an ad_id sourced from mi_used_search, which is the key semantic link an agent needs. The description adds nothing further on the parameter, so it sits at the baseline-plus level rather than above 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 ("Read one used/new phone ad on Mobile.ir") and enumerates the returned fields, so an agent knows exactly what it gets. It does not explicitly name the sibling it complements (mi_used_search), but the singular "one ad" framing makes the search-vs-fetch distinction fairly 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?

Usage is only implied: this is the detail lookup that follows a listing search, reinforced by the schema note that ad_id comes from mi_used_search. There is no explicit "use this when..." statement or exclusion of alternatives such as mi_used_search or mi_phone.

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/openWorld/idempotent/non-destructive, so the safety profile is covered. The description still adds non-inferable behavior: seller names and phone numbers are stripped from results, and listings are unverified user content that should not be treated as ground truth. It stops short of describing result volume, total counts, or pagination end 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?

The purpose and scope lead, followed by the privacy caveat, the price_note quirk, and the sibling hand-off — a sensible order with no filler sentences. The price_note aside is slightly parenthetical and interrupts the flow, and the parenthetical field list is ambiguous about whether those are filters or returned fields.

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 12-parameter tool with no output schema, the description does meaningful work: it sketches the ad record contents, flags stripped contact data, and explains the non-numeric price field an agent would otherwise misread. It still omits the shape of the list response (items, totals, page bounds), which matters more here precisely because no output schema exists.

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%, with enums and defaults documented for days, kind, sort, condition, prices and name_contains, so the schema carries the parameter burden. The description only echoes the filterable dimensions (price, condition, city) and explains price_note values, which is marginal added meaning over 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 (search) and resource (used and new phone ads posted by users on Mobile.ir), and names the concrete content domain with the filterable/returned attributes in parentheses. It also routes to the sibling mi_used_ad for the single-ad case, so an agent can distinguish this from the detail tool 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?

"Open one ad with mi_used_ad" gives an explicit alternative for the drill-down case, and "Ads are unverified user content" tells the agent how to treat results. However, with 16 siblings including mi_search, mi_find and mi_shop_prices, the description never says when to prefer this classified-ads search over retail shop prices or the general search tools, leaving the most likely confusion unresolved.

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