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

Annotations already cover read-only, idempotent, open-world behavior, and the description adds genuinely new context beyond them: phone numbers are masked by Bama and unavailable, and it explains what the related/similar counts actually represent on the ad page. No mention of what happens when the code is invalid or the ad is delisted, which keeps it short of a 5.

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

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

Front-loaded with the core action and return contents, followed by when-to-use, then caveats — a sensible order with little filler. The middle sentence about ads_of_same_model/similar_total is dense and slightly opaque, referencing labels the agent may not otherwise recognize, which costs 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?

With no output schema, the description correctly takes on the burden of describing returned fields (price, specs, condition, seller, description, photos) plus the masking limitation and the meaning of related-ad counts. Combined with a fully documented three-parameter schema, an agent has everything needed to call and interpret 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 coverage is 100%, with the code format, kind enum/fallback and similar cap all documented in-schema, so the baseline applies. The description adds only a thin layer of meaning ('similar adds comparable car ads' vs. the wider similar pool), and the sentences about ads_of_same_model/ads_of_same_trim describe returned data rather than the three input parameters.

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

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

States a specific verb and resource ('Get one Bama ad') and enumerates the returned content (price, specs, condition, seller, description, photos). It also scopes the tool to ad types (car, motorcycle, truck), making it clearly distinguishable from the ba_search / ba_search_bikes_trucks siblings.

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

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

Explicitly prescribes the workflow: 'Use it after ba_search or ba_search_bikes_trucks for a promising ad,' which tells the agent it is a detail fetch, not a discovery tool. It does not state when not to use it (e.g., batching many ads), but the sequencing 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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered; the description adds useful behavior beyond that by enumerating the returned payload (power, torque, dimensions, rating, pros and cons, trims, other generations) and describing the mode switch when model is omitted. It doesn't mention rate limits, pagination, or failure behavior for unknown brands/models.

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-loads the resource definition in the first sentence, then usage examples, then the omitted-model behavior, then sibling routing. Dense but every clause carries information, including a concrete sample query that anchors interpretation.

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 parameters, one required, and no output schema, the description carries the return-value burden and handles it by listing the main fields returned. It's nearly complete for a read-only lookup tool; the only gap is not stating the dependency on ba_vehicles for a valid brand key.

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 baseline is 3. The description reinforces only the model-omitted case ('lists the brand's models') and hints at review text via 'editorial review score'; it adds no meaning about trim keys, vehicle_type sections, or what full_equipment/description_chars actually toggle beyond what the schema already says.

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: 'Technical specifications and the editorial review score of a car or motorcycle model'. It immediately distinguishes itself from siblings by naming ba_ad (what's for sale) and ba_new_prices (new cost), and the example question ('what engine, power and consumption does a Samand Soren have') makes the intended use concrete.

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 usage context: use it for a specific model's specs, to compare models, or omit 'model' to list a brand's models. It also routes the agent away to ba_ad and ba_new_prices. What's missing is any note that the 'brand' key comes from ba_vehicles first, which is implied only in the schema, not the description.

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, non-destructive and open-world, and the description adds real behavior: a 100-ad ceiling on inventory and the important detail that 'Filters and sorting run on the fetched list', implying results are a post-fetch slice, not a server-wide filtered set. It also discloses the return payload (address/location plus compact ads) despite 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?

Four short sentences, front-loaded with what is listed and how much, then sequencing, then filtering behavior, then return shape. Nothing is redundant, though the final return-shape sentence could sit earlier for faster scanning.

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 7-parameter read tool with no output schema, the description supplies the missing pieces: the cap on results, where filters are applied, and the shape of the response. Remaining gaps (pagination beyond the 100-ad ceiling, whether the cap is fixed or limit-driven) are minor but real.

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 86%, so the schema already documents sort, limit, query, year and price bounds. The description adds only one semantic point — that filtering/sorting applies to the fetched list — and says nothing about how the 100-ad cap interacts with limit or that price filters exclude ads without a price.

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 ads of one dealer (showroom)') plus a hard scope ('the dealer's whole inventory, up to the first 100 ads'). It explicitly contrasts with siblings ba_dealers (which yields the id) and ba_ad (single ad), so an agent can pick 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 a clear sequence ('use it after ba_dealers when the user wants to browse one showroom') and an alternative for detail ('call ba_ad for one'). It doesn't say when to prefer buyer-side browsing across dealers (ba_search) over a single showroom, so the exclusion side is only partially covered.

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/openWorld, so the safety profile is covered. The description adds genuinely new behavioral context: it scans only the first pages of dealer-only ads, dealer ids and names are derived from ads rather than a canonical dealer directory, and each dealer's own listing is at the returned url — an important provenance and coverage caveat that the annotations cannot express.

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 resource and return fields, then use-case, then follow-up call — a sensible ordering with no filler. The second paragraph is slightly run-on ('dealer ids and names come from the ads, and each dealer's own listing is at the returned url'), but every clause carries 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 read-only discovery tool with no output schema, the description still tells the agent what comes back (address, rating, matching ad count, url), how complete the scan is, and which tool to chain into. Nothing needed to call or interpret it 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 the schema already explains pages, region and vehicle in detail. The description only echoes the 'model or city' axis and does not add format or interaction details (e.g. how region and vehicle combine, or that pages bounds runtime). 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 ('List car dealers (showrooms) with ads for a model or city') plus the returned fields (address, rating, matching ad count). This clearly separates it from sibling ba_dealer_ads (ads of one dealer) and ba_search (general ad search).

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

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

Gives an explicit use-case phrasing ('where can I buy X from a dealer') and then routes the agent onward: 'call ba_search with seller=dealer for the ads themselves.' Both the when-to-use and the alternative are named, so nothing is left to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the description's job is to add context — and it does: region returns states only unless query is supplied, and 'not every kind exists for every section' warns of empty/varying results. It stops short of describing the actual response shape (list of plain strings vs. label/value pairs), which is the main 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?

Purpose is front-loaded in sentence one, then usage rules and per-section routing follow in descending priority. Dense but purposeful; a few fragments (the region/query syntax note) could be tightened, and the parenthetical enumeration is slightly redundant with the enum.

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 lookup tool with no output schema and full annotation coverage, the description supplies the decision rules an agent needs: when to call it, how query scopes region, and section-specific kind selection. The absence of any description of the returned structure (only one inline value example) is the notable omission.

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 67% and the schema already documents query and vehicle_type, but the description adds real meaning: which kind values pair with which vehicle_type, that query only applies to region and usage, and the truncation behavior of an unfiltered region list. It does not explain all enum members (drive, cylinder, economy, lifestyle, origin, body_status), so not every kind is disambiguated.

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?

Opens with a specific verb and resource ('List the allowed values of one ba_search filter') and enumerates concrete example domains (states/cities, body types, fuels, colors, years). It explicitly positions itself as a lookup helper for the sibling tool ba_search, so an agent can distinguish it from ba_search 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?

Gives an explicit when-to-use rule ('Use it before ba_search when you need an exact value') with a worked example (kind=region query=اصفهان → 'isfahan'), plus a when-not case ('transmission needs no lookup: manual or automatic'). It further routes by section, telling the agent to use vehicle_type=truck with kind=usage and vehicle_type=motorcycle with body/fuel/color.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: the analysis is the vendor's own Persian text, and movers are new cars ranked by price change since their last quote. That language/content detail materially affects how an agent presents results. It omits freshness/caching or rate-limit behavior for a 'today' snapshot.

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 usage and follow-up routing. Every clause carries information; nothing is redundant with 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?

There is no output schema, so the description must describe the return payload, and it does enumerate the components (score, trend, analysis, movers). The Persian-language note pre-empts a real downstream surprise. Minor gap: no indication of how markets are keyed or how many markets 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?

With a single parameter at 100% schema coverage the baseline is 3, and the description earns a step up by defining what a mover actually is (new cars with the largest change since last quote), which is semantics the schema does not convey. It does not discuss the minimum of 0 or what a zero value returns.

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 resource and output shape: today's car market mood (score, trend, per-market analysis) plus biggest price movers. This is clearly distinguishable from sibling list/detail tools like ba_price_list or ba_ad. It stops short of differentiating itself from the closest sibling ba_market_stats, which an agent would likely confuse it with.

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 in the user's own words ("is the car market rising today?") and names the correct follow-up tools (ba_new_prices, ba_price_list). It does not say when NOT to use it or what ba_market_stats is for instead, so the alternative-selection guidance is partial.

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 readOnly/idempotent/non-destructive, but the description adds genuinely new behavior: it samples only the first pages of the newest-updated matching ads, keeps only fixed-price listings (excluding negotiable, installment and presale), and reports in Toman. It also discloses the key limitation that this is a sample of asking prices, not a census nor sale prices — a caveat an agent would otherwise misread as ground truth.

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 output shape, then the use case, then the sampling caveat, then the follow-up routing — a sensible order with little filler. Slightly dense but every sentence contributes a distinct fact.

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 9 optional parameters and no output schema, the description does the needed work by sketching what comes back (per-year price stats in Toman) and how the sample is built. It leaves minor gaps such as behavior when no ads match or how many samples back the stats, but nothing that would cause a mis-call.

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

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

Schema description coverage is 78%, so the schema already carries most parameter meaning, including the vehicle path format and the mileage=0 convention. The description only gestures at narrowing via 'year, mileage and region', adding no semantics for seller, transmission, pages, or year bounds beyond what the schema states, so it sits at the baseline.

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

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

States a specific verb+resource: price statistics (min, quartiles, median, max, per year) for a car model drawn from live Bama ads. It immediately distinguishes itself from ba_search by describing that sibling as the place to see the actual ads, so an agent can choose between stats and listings 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?

'Use it for "what is a 1398 Peugeot 206 worth" questions' gives a concrete triggering question shape, and the closing sentence prescribes a workflow: narrow with year/mileage/region for a tighter range, then switch to ba_search with sort=cheapest to inspect real ads. That names both the condition and the alternative tool.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the description's job is to add context beyond that. It does so by disclosing the row shape (price in Toman, provider types, daily change percent, 30-day trend) in the absence of an output schema, and warns that brand-wide queries can return many trims. Missing pagination/result-limit behavior and any note that history_days can extend beyond the default 30-point trend.

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 and the sibling routing is packed into the last, so structure is good. There is minor waste and imprecision, e.g. the awkward 'how much is a zero Samand Soren today' phrasing and untranslated provider labels that could be trimmed or clarified.

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 tool with no output schema, the description supplies the return-field context an agent needs to interpret results. Remaining gaps are volume/pagination handling for brand-wide queries, which is flagged but not resolved.

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 schema already documents all four parameters, including the trim-needs-model constraint. The description adds one useful behavioral cue (pass model and trim to get a single trim instead of a long list) but no syntax or format detail 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 with scope: 'Current price of every new-car trim of a brand or model on Bama's price list'. It immediately distinguishes itself from siblings by naming ba_market_stats (used market), ba_price_list (all brands) and ba_car_specs (technical 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?

Gives a concrete usage example ('how much is a zero Samand Soren today') and explicit routing rules: use ba_market_stats for the used market, ba_price_list to search all brands, ba_car_specs for technical data. It also tells the agent to pass model and trim to narrow a brand-wide query to one trim.

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 access, so the safety profile is covered. The description still adds real value beyond that: row granularity ('one trim, year and price type'), currency in Toman, and the volatility caveat that prices change daily and are not offers. It stops short of noting result-size or paging behavior, which matters given a 150-row cap.

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 with the core purpose front-loaded and the sibling disambiguation near the end where it is most needed. The closing caveat about prices being daily and not offers earns its place. Minor redundancy in pairing 'all brands' with 'rank 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?

With six optional parameters, no output schema, and a read-only profile, the description is essentially complete: it describes the row shape well enough to stand in for the missing output schema and states the price unit. The only gap is guidance on result volume or what happens when a limit is hit.

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 high at 83%, so the baseline is 3; the description adds meaning by framing the call as a ranking operation and by tying the example queries to the sort dimensions ('cheapest', 'rose most') and to the imported and price-type filters. It does not spell out the individual enum values, but the schema already carries those.

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 Bama's daily price list of new cars (or motorcycles)'), plus scope ('across all brands and rank it'). It also explicitly separates the tool from ba_new_prices (history) and ba_car_specs (specs), so an agent can route between siblings without opening 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?

Gives two concrete intent examples ('cheapest zero-km SUV at market price', 'which imported cars rose most today') that map to sort/filter options, and names explicit alternatives for the adjacent needs: ba_new_prices for a single model's trend and ba_car_specs for specifications. When-to-use and when-not-to-use are both covered.

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/openWorld, yet the description still adds non-obvious behavior: 30 ads per page, the site exposes no total count, and the agent must keep paging while has_more is true. It also discloses data conventions the agent cannot infer — prices in Toman, Jalali years with possible Gregorian imports, mileage 0 meaning zero-km — plus the workaround that ba_ad reports the true count for one model.

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

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

Front-loaded with purpose and result shape, then workflow, then paging caveat — every sentence carries operational information and none is filler. It loses a point for density and a broken clause ("region, body, fuel and" trailing into a new line) that makes the value-sourcing sentence harder to parse than it needs to be.

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 26-parameter, zero-required search tool with no output schema, the definition covers pagination, result size, units, and cross-tool value sourcing, which is what an agent needs to call it correctly. The remaining gap is minor: it never enumerates the fields of a "compact ad" or explains that the returned `code` is the handle for ba_ad, though the ba_ad reference implies 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?

With 92% schema description coverage the schema already carries most parameter meaning, including the ba_filters kind references and Toman/Jalali units. The description's parameter content (Toman pricing, Jalali years, the zero-mileage convention, value sourcing from ba_vehicles/ba_filters) largely restates what the schema says, adding little syntax or format detail beyond it. Baseline 3 is appropriate given 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?

"Search used and new car ads on Bama (bama.ir) with filters; returns up to 30 compact ads per page" gives a specific verb, resource, domain, and result shape. It actively carves out the sibling boundary by naming ba_search_bikes_trucks for motorcycles/trucks, so an agent can route without opening another 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 when-to-use ("find me X under Y" questions), explicit prerequisite workflow (fetch brand/model from ba_vehicles, region/body/fuel/color from ba_filters), and explicit next steps (ba_ad for full details, ba_market_stats for statistics). It also names the exclusion case — motorcycles and trucks go to ba_search_bikes_trucks — which is exactly the routing information an agent needs.

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

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

Beyond the annotations (readOnly/idempotent/openWorld), it discloses the pagination contract ('keep paging while has_more is true; there is no total count') and the follow-up path to ba_ad, which an agent could not infer. It also states unit conventions for prices (Toman) and years (Jalali, with Gregorian leakage on imports). Auth and rate-limit behavior are not covered, so it is strong rather than exhaustive.

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

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

Front-loaded with the core action in sentence one, then progressively narrower guidance (units, workflow, pagination, sibling routing). No filler sentences; the terse parentheticals all carry operational meaning.

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

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

For a 22-parameter read tool with no output schema, the description supplies the essential missing pieces: the has_more paging loop, absence of a total count, and the code field for chaining into ba_ad. It does not describe result item shape or the description_chars truncation behavior, leaving a small 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 already 91%, so baseline is 3; the description earns a bump by explaining where valid values come from (ba_vehicles, ba_filters keyed to kind) rather than just restating field names. The 'kind' section concept and the motorcycle-vs-truck filter split are made explicit. Minor gap: 'transmission' has no schema description and is not covered in the text.

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 motorcycle or truck ... ads on Bama') and immediately scopes the resource set (heavy vehicle, bus, machinery). It explicitly contrasts with the sibling that handles the remaining case: 'Cars are searched with ba_search.'

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

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

Gives concrete triggering examples ('find a Honda scooter under 500 million', 'used Volvo tractor'), names prerequisites for valid filter values (ba_vehicles / ba_filters with the same vehicle_type), routes detail lookup to ba_ad, and names the alternative tool for cars. When-to-use and when-not are both explicit.

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 bar is lower, and the description still adds real behavior: the 25-match cap and the enumeration semantics of each argument combination. It also discloses the lexical shape of returned values (brand, brand,model, brand,model,trim), which is exactly what an agent needs to reuse the output elsewhere.

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 with the cross-tool purpose front-loaded, followed by argument behavior and value format. Minor awkwardness in 'Give query to find matches' but no wasted 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?

No output schema exists, so the description carries the burden of describing returns, and it does so via the value-format convention and the 25-item cap. For a 3-optional-parameter lookup tool this is nearly complete; only pagination/truncation handling beyond the cap is 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 a 3 is the baseline, but the description adds meaning beyond the schema by stating what happens when brand and query are both omitted (list all brands) and how the returned strings encode brand/model/trim. The vehicle_type note ties the enum to the sibling tool that consumes those values.

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 the brand, model and trim values') and immediately scopes it as the value-resolution companion for ba_search, ba_market_stats and ba_new_prices. An agent can tell this apart from ba_filters or ba_car_specs 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?

Clearly explains the three modes: query finds up to 25 matches, brand lists that brand's models and trims, neither lists all brands. It also routes motorcycle/truck lookups explicitly. It stops short of saying when to call this versus ba_filters or ba_price_list, so it is clear context without explicit exclusions.

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