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 new behavior: long articles are cut, a truncation flag signals it, and a url gives the full page — practical details an agent needs before deciding whether to increase max_chars.

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

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

Two short sentences with the purpose first and the truncation caveat second; nothing is repeated from the schema and every clause carries information the agent needs.

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

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

Though there is no output schema, the description sketches the return shape (plain text, truncated flag, url) and the truncation semantics, which is everything needed to call a two-parameter read tool correctly. Nothing material 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 coverage is 100%, so this is already baseline 3, but the description adds meaning beyond the schema: the consequence of max_chars (text is cut) and where the untruncated content lives (url). The id's provenance from kn_articles is also reinforced in prose.

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?

"Read one article of the Karnameh car magazine as plain text" states a specific verb (read), a single resource (one article), and the output format (plain text). The follow-up sentence anchors it against the sibling kn_articles, so an agent can tell list-vs-fetch apart without inspecting schemas.

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 after kn_articles" gives explicit sequencing guidance and implicitly names the alternative that produces the id. No when-not-to-use condition, but for a simple fetch tool the ordering hint is the essential guidance and it is stated plainly.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a genuine behavioral trait not in annotations: results are returned 'Newest first'. It does not describe pagination behavior (e.g., whether a total count is returned), which is a modest gap for a list tool.

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

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

Two sentences, zero filler, with the resource and scope front-loaded and the follow-up read tool as the final clause. Every sentence carries information an agent needs.

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

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

For a read-only list/search tool with fully documented parameters, four safety annotations and no output schema requirement, the description covers what it does, what it returns in what order, and what to call next. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 100% – page, limit, query and category all carry their own descriptions including Persian example terms and the enum meanings. The description's mention of content types loosely maps to the category enum but adds no format or semantics beyond what the schema already says. 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 pair and resource ('Search or list articles') and scopes it to the Karnameh car magazine blog, naming the content it covers (news, reviews, maintenance, laws). It also distinguishes itself from its sibling kn_article by positioning itself as the discovery step.

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

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

Gives clear context: 'Use to find a review, a buying guide or a rule explanation', and explicitly routes the agent to kn_article(id) as the follow-up read step. It stops short of exclusion criteria (e.g., when to prefer kn_specs_search or kn_cars instead), but the when-to-use condition 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context beyond that: this is the canonical-name resolution step, and kn_price_list expects different variant names than kn_cars. It stops short of describing the returned structure (e.g. whether brand/model are nested), which keeps it off a 5 given there is no output schema.

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 carrying distinct information: purpose, ordering/prerequisite, and the cross-tool naming caveat. The most decision-relevant instruction ('Use first') is front-loaded in the second sentence with zero filler.

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

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

For a one-parameter read-only lookup with no output schema, the description covers purpose, sequencing, and the downstream handoff adequately. The only gap is that it does not sketch the shape of the result (brand/model pairs), which an agent must infer, though the tool's purpose makes that low-risk.

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 query parameter is fully documented there, including substring matching and the empty-string-lists-all behavior, so the baseline of 3 applies. The description reinforces the Persian/English dual-name intent but adds no syntax or matching details 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 ('Look up ... car brands and models'), plus the key attribute that it returns both Persian and English names. It is clearly distinguishable from kn_cars (which consumes the results) and kn_price_list (which uses different variant names), so an agent can tell the tools apart 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 ordering rule ('Use first when you only have a Persian name or are unsure of the spelling'), names the downstream consumer ('Pass the English brand and model values to kn_cars'), and flags the exception ('Zero-km price lists (kn_price_list) use their own English variant names'). When-to-use, what-to-do-next, and an exclusion are all present.

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

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

Beyond the readOnly/idempotent annotations, the description discloses real data-availability constraints: the full inspection report requires a Karnameh login, so only date, link and a one-line verdict are returned, and seller phone numbers are unavailable. These are exactly the gaps that would otherwise cause an agent to promise data the tool cannot deliver.

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 is returned, then when to use it, then the data limitations. No redundant restatement of the name or annotations.

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 describing return contents and does so field by field, plus flags the login-gated inspection report. Nothing needed to call this correctly on a single required UUID parameter 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 itself explains that id is the UUID taken from kn_cars, including a format example. The description adds nothing beyond that, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ("Get one Karnameh used-car ad") and enumerates the payload (price, specs, seller description, strengths, inspection summary). It also contrasts with the sibling kn_cars, so an agent can distinguish single-ad retrieval from list retrieval without inspecting 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 after kn_cars to read an ad in full" gives clear sequencing and names the alternative tool that supplies the required id. It stops short of an explicit when-not or error guidance, but the usage context is unambiguous.

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, so safety is covered. The description adds genuinely useful context beyond them: prices are asking prices in Toman, and the corpus is limited to Karnameh's own few hundred listings rather than the whole Iranian market — a real coverage caveat that prevents over-generalizing 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?

Four short sentences, front-loaded with the resource and filters, then usage, then the handoff to kn_car, then the coverage caveat. No redundant restatement of the tool title and nothing that could be cut without losing 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?

For a 14-parameter search tool with no output schema, the description covers purpose, currency, scope limits and the follow-up tool, which is most of what an agent needs. It does not indicate what a result record contains or how paging behaves in practice, though limit/offset are documented in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still contributes meaning by clarifying that price filters operate on asking prices and that all parameters are optional filters rather than a required pipeline, which sharpens how the 14 parameters should be combined.

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 Karnameh's used-car ads' — and enumerates the filter dimensions (brand, model, city, price, year, mileage) so an agent knows exactly what the tool retrieves. It also disambiguates from sibling tools by naming kn_car for detail and referencing kn_brands/kn_cities for slugs.

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

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

Gives clear positive contexts ('find cars for sale or to see what a model costs on the market') and a routing rule: pass an ad's id to kn_car for full description and inspection summary. It does not state exclusions — e.g. that this is not the tool for specs comparison (kn_compare_specs) or price history (kn_price_history).

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 the one thing annotations cannot convey: that results are identifier mappings (slug and id) rather than free-form text, which matters with no output schema. It does not mention whether the list is complete, cached, or paginated, leaving a small 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?

A single sentence that front-loads the action and then spends its remaining words on the highest-value detail, the cross-tool identifier mapping. No filler, no restatement of the 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?

For a zero-parameter list tool with no output schema, the description covers the essentials: what is listed and what identifiers come back. It leaves the remaining return fields (e.g., a display name) unstated, which is a minor omission rather than a blocker.

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 the schema baseline is 4 and there is nothing further for the description to disambiguate. The mention of `city` and id refers to how returned values feed sibling tools, not to inputs, so it does not create schema confusion.

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 cities Karnameh serves') and immediately disambiguates the returned identifiers by naming the exact field names used by two siblings ('the slug kn_cars takes as `city` and the id kn_inspection_centers takes'). An agent can distinguish this lookup tool from kn_city_stats or kn_inspection_centers 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?

Usage is strongly implied by tying the outputs to kn_cars' `city` parameter and kn_inspection_centers' expected id, which tells the agent this is a prerequisite lookup. There is no explicit 'use this before X' statement or any when-not guidance, so it stops just short of full routing instructions.

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 value beyond them by disclosing the execution model — one request per city, 9 issued together, hence slower than kn_cars — and by describing the return payload (counts plus each city's cheapest ad) in the absence of an output schema.

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 blocks, front-loaded with the verb and scope, then usage, then the cost caveat. Nearly every sentence earns its place. Minor weakness: '9, run together' introduces an unexplained figure — the city count — that a reader must infer.

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 correctly compensates by naming both return elements (per-city counts and cheapest ad) and warns about latency, which an agent needs for planning. Small gaps remain: whether cities with zero matching ads are included, and what the magic number 9 refers to.

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 brand, model and max_price are already documented with formats and units (Toman, English or Persian). The description only restates that these filters are optional and calls max_price a 'price ceiling', adding little beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('count used-car ads') plus the aggregation unit ('in every city') and the optional narrowing ('one brand, model or price ceiling'). It also discloses a secondary payload, each city's cheapest ad, which no sibling tool provides, so an agent can distinguish it from kn_cars and kn_price_list 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 use case ('Use to see where a car is for sale') and routes the agent to the right alternative for per-city drilling: kn_cars(city=...). It also flags that it is slower than kn_cars, which is a real selection criterion. It stops short of stating exclusions, e.g. that it should not be used when individual listings are needed, but the routing guidance is clear.

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 needs no restating. The description adds one genuinely useful behavioral fact — result values follow the `cars`/input order — but says nothing about cost, response size for four-variant comparisons, or how missing variants are handled. Credit for the ordering note, but it is thin 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 paragraphs, front-loaded with what the tool returns, followed by workflow and sibling routing. No filler sentences and no repetition of schema 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?

With no output schema, the description correctly shoulders the burden of describing the return shape (score, pros, cons, spec rows) and the input source. The one loose end is the ambiguous reference to `cars` when the parameter is `slugs`, which could briefly puzzle an agent mapping order semantics.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema (including the slug pattern and only_differences default). The only added meaning is the output-ordering guarantee tied to input order, which is modest. Baseline 3 is appropriate.

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

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

"Compare two to four car variants side by side" gives a specific verb (compare), resource (car variants) and explicit arity bound, then enumerates what comes back (review score, pros, cons, spec rows). That cleanly separates it from kn_specs_search (slug lookup) and kn_specs (single-variant detail) 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?

It names the triggering question shape ("A or B?") and the required precondition (slugs found via kn_specs_search), then routes adjacent needs to siblings: kn_price_list for new prices and kn_cars for used-market asking prices. When-to-use, prerequisite and alternatives are all present.

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

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

Annotations already declare readOnly, idempotent, open-world and non-destructive, so safety is covered. The description adds real context beyond them: results are per-city, include address and coordinates, and deliberately exclude booking or pricing, which sets agent/user expectations. Pagination and empty-result 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 capability, followed by the usage condition and the boundary note. Nothing is repetitive or padded.

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

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

For a single-parameter read tool this covers purpose, trigger, and the shape of the result (address plus coordinates) without an output schema. A small gap remains around whether the list is complete per city or paginated, but nothing essential to calling 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 already documents that it is the city id from kn_cities with Tehran as 1. The description adds no additional guidance on the argument, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ('List Karnameh's walk-in car inspection and paint-check centers in a city') and states what comes back ('address and map coordinates'). No sibling tool in the list covers inspection centers, so the agent can route here without ambiguity.

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 an explicit trigger ('Use when the user wants to get a car inspected') plus a negative boundary: booking and prices are not available here and the site handles booking. It stops short of naming a concrete alternative tool, but the exclusion is clear enough to redirect the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: each row carries the date of its last quote and a day-over-day percent change, and the result set is limited to recent quotes. It does not state sort order, whether results are truncated by the limit, or what happens when query matches nothing.

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, zero filler, with the core purpose front-loaded before the sibling comparison and the use cases. Every sentence carries distinct 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?

For a three-parameter read tool with no output schema, the description says enough: it names the returned fields (percent change, last-quote date), the breadth of coverage, and the intended follow-up tool. Missing only ordering and empty-result behavior, which are minor for this complexity.

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

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

Schema description coverage is 100%, so year, limit and query are all documented with ranges, defaults and examples in the schema itself. The description adds no parameter-level detail beyond implying recency, which puts it at the baseline for a fully documented schema.

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

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

States a specific verb and resource ('List the most recent price quotes of new cars') plus the payload detail ('with the day's percent change'). It also distinguishes itself from two named siblings, kn_price_list (broader variant coverage, including older models) and kn_price_history, so an agent can separate it 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 two concrete use cases ('see what moved lately' and 'find a variant's exact English name for kn_price_history') and explicitly routes comparison with kn_price_list. The gap is the sibling kn_price_movers, which appears to overlap with the 'what moved lately' case and is never mentioned or excluded.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds the valuable part not in the annotations: the result granularity (daily averages, one series per production year) and the side effect of passing `year`, which also returns each source's current quote for that year.

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?

Purpose is front-loaded in the first sentence, followed by usage routing and then parameter caveats in descending priority. No filler, no restatement of the 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?

No output schema exists, so the description must carry the return shape, and it does: daily averages per production year plus per-source quotes when `year` is set. It says nothing about response size limits or gaps in the history, but nothing essential for calling the tool correctly is missing.

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

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

Schema description coverage is 100%, so `days`, `name`, and `year` are already documented, and the description largely restates the `name` exactness rule the schema states. Its only added meaning is the behavioral consequence of `year` (per-source current quotes), which is useful but thin against a fully documented schema.

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

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

States a specific verb and resource: 'daily average market price history of one new-car variant, per production year.' It also names the sibling tools (kn_price_list, kn_latest_prices) this one sits downstream of, so an agent can place it in the workflow 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?

Explicit sequencing guidance: 'Use after kn_price_list or kn_latest_prices for a trend' with the concrete question it answers ('is it going up?'). It lacks an exclusion clause — e.g., when kn_price_movers would be the better choice for change detection — so it stops short of full when/when-not coverage.

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

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

Annotations already declare read-only, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real context beyond that: currency (Toman), daily refresh cadence, and a coverage caveat that only variants Karnameh currently prices appear. It stops short of describing how results are ordered or how the price-source field looks, 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 short sentences, front-loaded with the resource and source URL, then usage, then routing to alternatives. No filler and no restatement of the 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 nine optional params, no output schema and no required fields, the description supplies what the schema cannot: what a row represents, units, freshness, and coverage limits. Pagination is left to the schema's `page` description, so the remaining gap is minor.

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 one of the nine parameters is already documented in the schema and the baseline of 3 applies. The description adds only the unit confirmation (Toman) and the note that rows carry a `name` usable with kn_price_history, without new syntax or filter-interaction guidance.

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 today's market prices of new zero-km cars") and names the data source (karnameh.com/car-price). It also scopes the output shape (each row is a variant plus production year with price sources), which lets an agent distinguish it from kn_latest_prices and kn_price_history 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 explicit when-to-use phrasing ("how much is a new X", compare models) and names both alternatives with the condition that selects each: kn_latest_prices for discontinued/older models, kn_price_history for movement over time. It also states an exclusion (no Peugeot Pars or 405), which prevents a wrong call.

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 and side-effect profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuine value by defining 'change_percent' as change against the previous quote and by explaining how to drill into the trend, which an agent could not infer from annotations alone.

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

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

Three short sentences, front-loaded with the core operation, then the usage trigger, then the follow-up path. No redundant restatement of the tool name or 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 names change_percent and a row's name field, and 'rank' implies ordering. It omits the actual row shape and whether results are sorted descending, a minor gap for an otherwise simple, fully documented read tool.

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

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

Schema description coverage is 100%, including per-parameter descriptions for days, year, limit, and direction, so the schema already carries parameter meaning. The description only loosely reinforces the freshness window through 'latest price quote' and adds no format or interaction detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Rank new (zero-km) car variants') plus the exact ranking metric ('percent change of their latest price quote'). This cleanly separates it from sibling price tools such as kn_latest_prices and kn_price_history.

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 a concrete user-intent trigger ('which cars got more expensive lately') and routes follow-up work to kn_price_history by name. It does not state when to prefer kn_latest_prices or kn_price_list instead, so it stops short of full when/when-not coverage.

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 this a safe, idempotent, read-only lookup, so the bar is lower. The description still adds real behavioral context the annotations cannot: specs come back grouped into four named categories, and the review score/summary are AI-generated from web reviews and should be treated as opinion rather than fact. It stops short of describing response shape or size, which keeps it at a 4 rather than 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?

Purpose is front-loaded in the first sentence, followed by the prerequisite, then the caveat and the sibling routing. Every sentence carries distinct information, and the grouping list is compact enough to earn its space by telling the agent what to expect in the payload.

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 return-value burden and does so by enumerating the spec groups, the score, pros/cons, and web reviews. Combined with the single-parameter schema and the explicit prerequisite, nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% and the slug property already carries the pattern, the example, and the instruction to source it from kn_specs_search. The description only reinforces the 'one variant' framing and the search-first dependency, adding no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one car variant's technical specs') plus the exact payload (expert review score, pros and cons, web reviews), scoped to a single variant. That scope word 'one' implicitly separates it from the list-oriented kn_specs_search, and the description names that sibling explicitly.

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

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

Gives an explicit sequencing rule ('Use after kn_specs_search') and routes two adjacent intents elsewhere: prices to kn_price_list and used ads to kn_cars. An agent knows both when to call this and which sibling to pick instead for the neighboring tasks.

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

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive, so the safety profile is settled. The description adds real behavioral detail beyond that: results are flagged `variant: true` only when specs exist, and brand/model matches are group nodes rather than variants — a non-obvious result-shape rule. It stops short of describing the full result shape or max-result behavior, keeping it below 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 sentences, front-loaded with purpose and the downstream slug contract, then usage ordering, then the result-flag caveat. No filler, and the most decision-relevant information (use first, returns slug) comes 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 carries the return-value burden and does explain the key output (slug) and the `variant: true` marker. It does not describe the remaining fields of a match (name, brand/model grouping labels) or default limit behavior, leaving a small gap for a search tool whose output drives chained calls.

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

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

Schema description coverage is 100%, so both `query` (with Persian/English examples) and `limit` (1-30) are already documented. The description adds no format, syntax, or matching-behavior guidance for the query beyond what the schema states, 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?

"Find car variants in Karnameh's specs catalog and return the `slug` that kn_specs and kn_compare_specs take" gives a specific verb, resource, and output, and explicitly positions itself upstream of two named siblings. An agent can tell exactly what this tool produces and what consumes it.

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 first when you want the technical specs, expert review summary or a comparison" states the triggering conditions and implicitly routes to kn_specs / kn_compare_specs as the follow-on calls. The closing sentence adds an explicit recovery rule: if a match is only a brand/model group, refine the query with more words.

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