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

Annotations only cover safety (readOnly/idempotent/openWorld); the description adds the real behavioral substance: confidence thresholds (high 40+, medium 15+), the 'insufficient comparables' verdict when confidence is low, the widening breadcrumb strategy, and that comparisons ignore year/mileage/area/condition and reflect asking prices only.

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 question and the mode split, and nearly every clause earns its place. It is dense with nested parentheticals and confidence cutoffs, which slightly taxes readability but introduces no filler.

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

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

With no output schema, the description carries return-value duty and does so fully (percentile, verdict, vs_median_pct, p25-p75 band, confidence) plus caveats. Both zero-required-parameter modes are explained, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds cross-parameter meaning the schema lacks: token vs price are alternate modes, price means monthly rent for rent categories, and breadcrumb widening derives from the ad. It stops short of documenting every parameter individually, which the schema already does.

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, answerable question ('Is an ad's price ... high or low compared with similar ads?') and names the exact outputs (percentile, verdict, confidence). It distinguishes itself from sibling dv_compare by scoping to market-fairness appraisal rather than ad-to-ad comparison.

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 splits the two invocation modes: with `token` it appraises that ad via its own breadcrumb, without it you must supply `price` plus category/query/filters. It also routes the agent to `filters`/`query` for refinement and to dv_compare for specific-ad comparisons.

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 the safe read-only profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description still adds substantial behavior: it scans the newest N pages capped at budget, computes a deal_score with named reasons and penalties, drops implausible/bait ads into skipped_implausible, opens the top 6 ad pages for extra fields with an explicit caveat about the rest, and reports an empty list with a note on unrealistic budgets. This is unusually rich disclosure of algorithm and side data beyond the annotations.

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

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

The purpose is front-loaded in the first line before any implementation detail, and no sentence is purely decorative. It is dense to the point of being run-on, with heavy parenthetical stacking (median, photos, freshness; penalties...), which slightly impedes scanning but does not bury the lead.

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 15 parameters, nested filters, and no output schema, the description carries the burden of explaining returns and it does so: best_value, deal_score, reasons, skipped_implausible, caveat, and note are all named. Combined with the usage and failure-mode guidance, an agent has everything needed to call this correctly.

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

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

Schema description coverage is already 100%, so the baseline is 3, but the description genuinely extends semantics: it clarifies that budget interacts with market_median/budget_median and that query/keywords determine whether bait words are kept rather than filtered, and that a mixed category makes the median meaningless. That adds meaning not encoded 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?

The description states a precise verb (scan/return) and resource (ads within a budget) and even names the two ranked sub-lists it produces: 'best-value ads' and 'the most you can get'. This is far more specific than a tautology and an agent can tell it is a budget-constrained deal ranker. It stops short of distinguishing itself from close siblings like dv_cheapest or dv_find_deals, which is the only reason it is not 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?

It gives real invocation guidance: 'Use a narrow query or brand: a mixed category's median means nothing', and routes onward with 'Next: dv_appraise, dv_post'. It also explains the failure mode ('An unrealistic budget returns an empty best_value with a note'). No explicit when-not or direct sibling exclusion is offered, so a 4 rather than 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, openWorld, and non-destructive, so safety is covered. The description adds real behavioral context beyond them: geometry is thinned to `max_points` per ring so the shape is approximate, and the returned payload differs sharply between the two modes. It stops short of mentioning error behavior for an unknown district or coordinate order caveats beyond [lon, lat].

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, with the resource and the two output modes front-loaded before the usage and next-step guidance. Slightly dense in the first clause, but no filler or 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 carries the return-shape burden and does so adequately by naming the bounding box tuple, the per-neighbourhood id/centre/box fields, and the GeoJSON Feature shape. Missing only failure modes (unknown city/district) and any note on coordinate reference system beyond the [lon, lat] ordering.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantic weight: `district` is framed as a mode switch, not just a filter, and `max_points` is explained as a lossy approximation of the outline rather than a raw cap. `limit` is not clarified further in the description, which keeps this from a 5.

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 (neighbourhood borders of a city) and source (Divar's GeoJSON), then splits the two operating modes explicitly: no `district` returns the city bounding box plus a neighbourhood list, with `district` returns one neighbourhood's GeoJSON Feature. An agent can distinguish this from dv_districts, dv_neighbours, and dv_locate without reading 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 a concrete use condition ('draw an area or test a point against it'), an explicit exclusion with the alternative ('for a point's own neighbourhood use dv_locate'), and a forward pointer ('Next: dv_nearby with the centre'). Routing between siblings is fully specified.

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 the safety profile is covered. The description adds context beyond that — the tree's size (236 nodes) and depth (up to 4 levels) — which helps the agent anticipate the result set, though pagination/limit behavior is left to the 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?

Front-loaded with what the tool returns, then the usage pointer. Two compact sentences with little waste; the parenthetical slug examples add value but are the only slightly list-heavy part.

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 usefully lists the returned fields itself. For a read-only browse tool whose annotations already carry the safety profile, this is essentially complete, with only minor gaps around result ordering or pagination.

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

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

Schema description coverage is 100%, so limit, query and parent are already fully documented in the schema. The description contributes nothing extra about parameter syntax or formats, making the baseline 3 appropriate.

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

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

States a specific resource — the Divar category tree — and enumerates what each node carries (slug, Persian name, path, leaf flag). It distinguishes itself from siblings by naming dv_search as the consumer of the slugs and dv_filters as the per-category filter tool, so an agent can tell it apart 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?

Explicitly states the use case: 'Use to find the `category` slug for dv_search and the other tools,' and routes filters to dv_filters. It gives clear context and a named alternative, though it stops short of a full when-not clause (e.g., what to do when the category is already known).

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, it discloses real behavior: negotiable, placeholder and absurd prices are skipped, sub-10%-of-median ads are dropped unless `include_outliers` is set, rent categories rank on monthly rent, and the response reports how many ads were scanned and skipped. That is exactly the kind of context 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?

Front-loaded with the result shape and ranking rule, then caveats and next steps. It is dense rather than bloated, though the outlier behavior is stated twice (in prose and again against `include_outliers`), which is minor redundancy.

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

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

For a 17-parameter, no-output-schema tool this is close to complete: it explains the scan model, exclusions, ranking, and what the answer reports. It omits only edge behavior such as what a fully unfiltered scan returns, which the agent can infer from the parameter docs.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning to specific params: `pages` (~25 ads per page, affects scan width), `include_outliers` (sub-10%-median ads), and the rent-category interpretation of min/max price. It adds value over the schema without documenting every one of the 17 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?

The description names a specific verb and resource ('the cheapest ads of a search, cheapest first') plus the exact scope of the scan, which cleanly separates it from siblings like dv_search, dv_best_for_budget and dv_find_deals. An agent can tell what this tool returns 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 concrete operating guidance: raise `pages` for a wider scan or narrow with `filters`, and it names follow-on tools (dv_post, dv_compare). It does not explicitly say when to prefer a sibling such as dv_best_for_budget over this one, 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 readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely useful behavior beyond that: dataset size (1,177 cities), Persian letter-variant normalization (ي/ی, ك/ک), and the default behaviour when query is omitted. It does not discuss pagination or result ordering, 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?

Two compact paragraphs, each sentence load-bearing: the first states purpose and returns, the second states fallback behaviour and routing. No filler, and the most important fact 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?

With no output schema, the description compensates by naming the returned fields, and for a 2-parameter optional-query lookup it covers selection, defaults, and follow-up tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already explains limit and query fully, including the 'omit for the 7 biggest cities' default. The description only adds illustrative ID values (Tehran 1, Mashhad 3), which is a marginal gain. 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 gives a specific verb+resource ('City ids for a name') and immediately enumerates what is returned (id, name, URL slug, province id, centre). It is unambiguous against siblings like dv_districts or dv_search, which are named as follow-ups rather than competitors.

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 routing: 'Use first when you need a `city` for another tool', plus a note that other tools also accept the name directly, and a 'Next:' chain pointing to dv_districts and dv_search. Both when-to-use and what-to-use-next are stated.

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, openWorld). The description adds meaningful behavior beyond that: it discloses the computed outputs (cheapest, cheapest_saves_pct, compared_by), the per-metre normalization rule when all priced ads have an area, and the fact that identical specs are collapsed. That is substantive disclosure of what the tool computes and returns.

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?

It is dense but front-loaded: the core comparison semantics come first, then the computed fields. Every clause conveys distinct information about output shape; the parentheticals are slightly heavy but not redundant.

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 describing results, and it does so thoroughly (cheapest, savings percentage, differing rows, shared specs, unique features, compared_by). The only gap is the absence of routing guidance to sibling tools, which is a usage rather than completeness concern.

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 'tokens' parameter is fully described there (2–6 ad tokens). The description adds nothing about token format or provenance, but with complete schema documentation 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?

The description opens with a specific verb and resource ('Side by side: the price of each ad') and immediately scopes the output ('only the specs that differ'). It is clearly distinguishable from siblings like dv_cheapest, dv_appraise, and dv_similar, which perform different single-ad or ranking operations.

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 states a real constraint — 'Works across ads of the same kind (two cars, two flats)' — which tells the agent when the tool is applicable. However, it never names an alternative (e.g. dv_cheapest, dv_appraise, dv_similar) or explains when to prefer comparison over those tools, so the when-to-use guidance is only implied.

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 safety is covered. The description adds genuinely new behavior: the 10,000 cap and its '10,000 or more' semantics, and that the call is cheap. It does not explain cost/latency beyond 'cheap' or the exact return shape.

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

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

Two tight sentences; the most surprising and decision-relevant fact (the cap semantics) is front-loaded in parentheses. No filler sentences.

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 still conveys the essential return semantics (a count, saturated at 10,000) and the nested filters object is documented in the schema. An agent can call this correctly; only finer return details (e.g. whether `ignored` keys are echoed) are left implicit.

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% across 12 params, so the schema already documents each field exhaustively. The description only points to dv_search for argument parity, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (count) and resource (active ads matching a search), plus the key scope qualifier that the result is capped at 10,000. The closing note 'Same arguments as dv_search' immediately separates it from that sibling 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 three explicit use cases (size a market, test whether a filter combination is too narrow, compare cities/districts) and explicitly positions it as a pre-step 'before fetching ads' — i.e. route to dv_search for actual listings. When-to-use and the alternative are both named.

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 the description goes well beyond them: it discloses the 11-ad cap, the absence of paging, the exact shape of each ad row (token, title, price, district, age, photos, tag), and how to build the ad link from url_prefix + token. That is meaningful behavioral context an agent cannot get from structured fields.

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 and returned fields are front-loaded in one sentence, followed by a second paragraph covering the paging limitation, row format, and link construction. Every clause carries usable information with no padding.

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

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

With no output schema, the description carries the return-value burden and does so fully: it lists the page fields, the ad-row fields, the link convention, and the meaning of age_h. An agent can call this correctly and interpret the response without further help.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema ('Dealer id from dv_seller, e.g. ZbeypyTr'), including pattern and length. The description adds no additional semantics about brand_token, 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 names a specific resource ('a business account's public page') and enumerates exactly what it returns (name, active ad count, member since, first 11 ads), so an agent knows precisely what this fetches. It stops short of an explicit contrast with the closest sibling, dv_seller (individual seller vs. business account), so sibling differentiation is left to inference from the param description.

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 clearly states the tool's limit ('only the first batch... no paging') and routes the agent elsewhere for more ('search with the dealer's name or use the ad filters'), naming the viable alternatives. The routing is by description rather than tool name, but the condition that selects the alternative is 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 semantics, so the safety profile is covered. The description usefully adds the scale of the result set (Tehran ~450) and the shape of each record (ids, centre point, streets), which helps the agent anticipate output volume. It does not discuss truncation or the default limit behavior beyond what the schema states.

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 with the core purpose front-loaded and zero filler. The routing sentences are compact, though the trailing 'Next: dv_neighbours' is only marginally valuable.

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 the returned fields (ids, centre point, streets). Annotations cover the safety profile. Pagination/ordering behavior is not described, a minor gap for a potentially 450-item result.

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 (city, limit, query) are already fully documented with defaults, constraints and examples. The description adds no additional parameter syntax or meaning, 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 resource (neighbourhoods/districts of one city) and what each record contains (ids, centre point, main streets), with a volume hint. It explicitly distinguishes itself from search siblings, noting they take district names directly while this tool supplies the underlying ids.

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 cases ('to get the district ids for a districts filter', 'to pick coordinates for dv_nearby'), an exclusionary note that dv_search and other search tools don't need it, and a next-step route to dv_neighbours. 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 establish readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful behavior: the payload arrives as text in `data` and the caller must write the file itself, missing prices are emitted as empty fields, and the exact column set. That is real disclosure beyond structured data, though it says nothing about size limits or truncation.

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 clause, followed by the essential operational note about `data` and the file-writing responsibility. The column enumeration is compact and earns its place because there is no output schema to describe the shape.

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 18 optional parameters, nested `filters`, and no output schema, the description carries the return-shape burden and does so by enumerating columns and flagging empty prices. It does not touch on output size, pagination interplay between `limit` and `pages`, or the `ignored` key mentioned in the schema, leaving minor gaps.

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% across all 18 parameters, so the schema fully documents city, limit, pages, format, filters, etc. The description adds no parameter-level meaning beyond pointing at dv_search's argument set, which is the expected baseline 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+resource (ads of a search exported as CSV or JSON lines) and names the output medium, which clearly separates it from dv_search's inline results. It even lists the emitted columns. It stops short of explicitly contrasting itself with dv_search beyond noting the shared arguments, so it is not a full 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?

"Same arguments as dv_search" plus "ready to save to a spreadsheet or analyse" implies when to reach for this tool over the search sibling, but there is no explicit when/when-not statement or named alternative. The reader must infer that dv_export is the file-producing counterpart of dv_search.

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, open-world behavior, so the bar is lower. The description still adds real context beyond them: the lookup is backed by Divar's own typed search, and the result set varies by whether `query`/`brand` is supplied.

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 what the tool returns, then the with/without `query` branching in two compact sentences. Slightly dense with parentheticals but no filler.

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

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

No output schema exists, and the description partially covers returns ('key, title, model count'), plus how to feed keys into dv_search. It does not describe pagination/limit behavior or error cases when a brand/category is unknown, but is otherwise sufficient for a read-only 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 100%, so the baseline is 3, but the description genuinely clarifies parameter interplay the schema states only per-field: `query` triggers typed search, omitting it returns the full list, and `brand` restricts to one brand's models. That coupling of query/brand/filter is the key semantic an agent needs.

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: it returns allowed values for a filter (brand/model keys, districts, option lists), and gives concrete scale ('161 car brands'). It is clearly separable from dv_filters (which yields filter keys) and from dv_search (which consumes the keys).

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 explains the two modes: with `query` it uses Divar's typed search to map Persian text to a key, without it returns all brands or one brand's models, and it tells the agent to pass results into dv_search as brand_model/filters. It stops short of naming dv_filters as the sibling that supplies the `filter` key.

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 useful behavior: which filter types exist, that 'lazy' filters have long option lists needing a different tool, and that rent vs. sale categories filter different fields (credit/rent vs. price), all in Toman. It stops short of stating pagination or response-shape details, but it goes meaningfully beyond the annotations.

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

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

The purpose and the usage cue are front-loaded in the first two sentences, and the rest is dense but load-bearing type examples. It is a single run-on block with no visual grouping, which slightly hurts scanability, but there is no filler.

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

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

With no output schema, the description correctly explains what is returned and adds domain rules (rent vs. sale filter fields, Toman units) plus pointers to dv_filter_options for long lists. It is complete enough to call the tool correctly, though it leaves the relationship between the schema's city/category params and the referenced `filters` payload implicit.

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% for the two declared parameters (city, category), so the baseline would be 3. The description earns an extra point by supplying value-encoding semantics for the filter payload (number_range -> {min,max}, repeated_string -> list, str -> scalar, boolean -> true) that the schema does not document at 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?

The description specifies the resource precisely: it enumerates every filter a category supports along with the returned fields (key, type, Persian label, unit, options). It also names the sibling dv_filter_options and the alternative path via dv_search, so an agent can distinguish it from the rest of the dv_* family 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?

It states the trigger condition explicitly ('Use before dv_search when you need more than price and district') and routes the agent to alternatives for the lazy/long-list filters. The when-to-use and the escape hatch are both spelled out rather than 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?

Beyond the read-only/idempotent annotations, it discloses the filtering logic in detail: median basis is price per m2 for sale, ads under 20% of median, suspect/placeholder prices, bait/co-op titles, notice/parking titles are dropped, and "Asking prices only". This is genuinely useful behavioral context an agent cannot infer from the 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?

Front-loaded with the core definition, then the exclusion rules, then guidance — no filler sentences. It is dense and telegraphic (Persian keyword lists, backtick references), but every clause carries operational 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 16-parameter discovery tool with nested `filters` and no output schema, it covers the essentials: median semantics, exclusion rules, and narrow-query guidance. It does not explain the shape of the returned "scored deals" (no output schema exists) or the apparent gap between `min_discount_pct` max of 60 and the stated 70% floor.

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 adds meaning beyond the schema by explaining what `min_discount_pct` is measured against (median, up to 70% below) and by advising that `query`/`filters` must be narrow for the median to be meaningful.

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

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

Specific verb and resource: it finds ads priced below the median, explicitly "without a budget", which implicitly separates it from dv_best_for_budget and dv_cheapest. The scope (scored deals, bait/junk removed) is clear. It does not explicitly contrast itself with dv_search or dv_cheapest, so sibling differentiation is partial.

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 rule: "Use a narrow query or filters: the median of a mixed category means nothing", plus a workflow pointer ("Next: dv_post, dv_appraise, dv_compare"). It states the condition that makes results meaningful but does not say when to pick this over the other deal-hunting siblings.

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 useful context beyond that: street address resolution is limited to covered areas, and the returned ids are intended as filters for other tools.

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 lines, front-loaded with the result and then the usage hint. It is tight and waste-free, though the opening sentence is a fragment whose missing verb slightly reduces immediate clarity.

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 does the work of describing what comes back (city, neighbourhood, street address, city id, district id) and its coverage limit. For a two-parameter read-only tool this is close to complete; only the handling of points outside covered areas or outside Iran is left unspecified.

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 both lat/lon carry bounds plus worked examples, so the schema fully carries parameter meaning. The description adds no syntax, format or edge-case detail about the coordinates 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?

The description names the exact resource produced (city, neighbourhood, street address) for a GPS input, which is a specific and recognizable reverse-geocoding operation. It is a noun phrase rather than a verb+resource statement, so the action ('locate') must be inferred from the name, but the output is unambiguous.

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

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

It states what the result is for ('Gives the city id and district id to use as filters') and explicitly chains to the next tool ('Next: dv_nearby for ads around the point'). No exclusions or when-not conditions are given, so it falls short of a 5.

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

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

Annotations declare only the safety profile (readOnly, openWorld, idempotent, non-destructive); the description adds substantial behavioral detail beyond that: it scans only the newest `pages` pages, drops negotiable/suspect prices into `excluded`, trims prices below a tenth of the median, returns `price` for sales vs `rent`/`deposit` for rentals, and explicitly warns these are asking prices from a newest-ads sample, not closed deals.

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 return statistics and the key sampling caveat, then details `by_district`/`per_day` and next steps. Slightly repetitive (the district/day split is announced up front and re-explained later), but every sentence carries information for a 16-parameter tool with no output schema.

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

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

With no output schema, the description fully covers the return surface (min/percentiles/median/mean, `by_district` with ad count and median, `per_day` counts and medians, `excluded`) plus the sample-vs-market caveat, which is exactly what an agent needs to interpret the numbers.

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 16 parameters, including the '~25 ads per page' meaning of `pages`. The description reinforces the sale-vs-rental price interpretation (relevant to min_price/max_price) but adds little syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource: computing asking-price statistics (min, p10–p90, median, mean) for a search, split by district and by day. An agent can tell this apart from dv_count (a count), dv_price_trend (a trend over time) and dv_cheapest (a listing) 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 concrete context for meaningful use ('use a narrow query or filters (one model, one area) for a meaningful median') and routes the agent onward with 'Next: dv_cheapest, dv_best_for_budget, dv_appraise.' It lacks an explicit when-not-to-use statement, but the sampling caveat effectively delimits when this tool is appropriate.

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?

Adds substantial behavior beyond the annotations: a 200-ad cap per area with total_in_area as the true count, ~500 m pin fuzzing (approximate_location) making distances approximate, and rounded map prices. These are exactly the caveats an agent needs and are consistent with readOnly/idempotent hints.

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 purpose and return shape, then the constraints/caveats, then the next step. Dense but every sentence (fuzzing, cap, category requirement, price rounding) earns its place; no filler.

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

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

With no output schema, the description carries the return contract (coordinates, distance, price chips, thumbnail, total_in_area) and the key limitations (cap, fuzz, approximate distances). A mutation-free 12-param tool is fully covered for correct invocation.

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 parameters are already well documented (lat/lon sourced from dv_place_search/dv_districts, filters keys from dv_filters, price units). The description reinforces the required-category rule and price rounding but adds little parameter syntax beyond the schema — baseline 3.

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+scope: ads on the map around a GPS point, returned nearest-first, with the exact payload fields (coordinates, distance, price chips, thumbnail). The map/geographic framing and the 'Next: dv_post for details' routing make it distinguishable from the many search 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?

Gives clear context for use (geographic point search) and a hard precondition ('a category is required'), plus a next-step pointer to dv_post. It stops short of explicitly naming an alternative like dv_search for non-map queries, so it is contextual rather than 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavioral context: `districts` is Divar's short adjacency list (Vanak lists one) and `nearest` supplements it with centroid-distance districts within 3 km, up to 6, which explains why results vary by area.

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

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

The purpose is front-loaded in the first sentence, followed by the mechanics of `districts` and `nearest`, and it ends with the actionable handoff to dv_search. It is well ordered, though the parenthetical detail (within 3 km, up to 6, Vanak lists one) is somewhat granular for a definition.

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 lookup with no output schema, the description does enough: it names the two result sets (districts, nearest) the agent will get back and what to do with them. It is not exhaustive about the exact return shape, but the essential call-and-consume loop is covered.

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 (district_id from dv_districts, city name/id with comma-separated examples). The description does not meaningfully extend parameter semantics beyond noting the outputs should be fed back as `districts` to dv_search, so the 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?

The description states a specific resource (adjacent neighbourhoods around a district) and the intent (widening a neighbourhood search to the surrounding area). It does not explicitly differentiate itself from the sibling dv_nearby, which is the most likely confusable tool, so it falls just 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?

It implies usage by describing the widening scenario and by saying to pass the ids as `districts` to dv_search, which gives the agent a downstream workflow. However, it never states when NOT to use it or how it differs from dv_nearby/dv_districts, leaving the selection decision partly to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world. The description adds genuinely non-obvious behavior: promoted old ads are excluded by date, `more` signals that the page limit was hit, and nothing is stored or pushed (stateless cursor polling). The only gap is how far back the cursor can reach or what happens if `since` is stale.

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 compact sentences, front-loaded with what the tool returns and then the polling contract. Nothing is redundant against the schema despite the tool having 17 parameters.

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 surfaces return-side signals (`latest`, `more`) and the exclusion of promoted ads. It leaves a few operational questions open for a 17-param, nested-object tool, such as cursor expiry, but it is adequate for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 17 parameters, including the `since`/`hours` relationship and the `latest` convention. The description reinforces the `since`-from-previous-`latest` loop but adds no format or validation detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Ads published after a moment, newest first') and states the tool's distinctive behavior as a polling cursor over a saved search. It distinguishes itself from a one-shot search by describing repetition-free polling, though it never names its nearest sibling (dv_search or dv_watch) 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?

It gives a concrete operating loop: call it, remember `latest`, pass it as `since` next time, and let a caller or scheduler decide when to poll. That is clear when-to-use guidance, but there is no explicit when-not-to-use or routing statement against dv_search/dv_watch.

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 it read-only, idempotent and non-destructive, so the safety profile is covered. The description adds substantive behavior beyond that: it is rule-based rather than an LLM, it discloses its extraction limits, and it points the agent at `notes` to see what was assumed.

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?

Opens with the core transformation, then lists extraction rules and caveats; every clause maps to a real parsing behavior an agent needs. It is dense but each sentence earns its place, with only mild redundancy in the price-modifier enumeration.

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 the return keys (`search`, `notes`) and tells the agent how to consume them. Combined with the disclosed limitations and the pointer to dv_filters, an agent has everything needed to call and use the result correctly.

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

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

Schema coverage is 100% and the single `text` parameter is already exemplified in the schema, so baseline is a 3. The description earns above baseline by explaining what the text is parsed into (amount modifiers زیر/تا/بالای, rental words moving to a rent category, '80 متری' becoming a ±10% size filter).

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

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

States a specific transformation ('turn a plain Persian request into dv_search arguments') and enumerates exactly which fields it extracts (city, neighbourhoods, price bounds, category, leftover words). It is clearly distinguishable from siblings dv_search (the consumer) and dv_filters (the fallback for rooms/year/mileage).

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: use dv_filters for rooms/year/mileage, and the produced `search` can be passed directly to dv_search. What is missing is an explicit when-not (e.g., skip this tool if you already have structured arguments), though that is strongly implied.

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 the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description adds genuine value by naming the response buckets (mapping, unchanged, unverified) and clarifying what each means. It does not state what happens for ids absent from all three buckets, which is a minor 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?

Front-loads the purpose in one sentence, then the trigger condition, then the return-taxonomy detail. Every clause carries information and nothing is repeated.

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 enumerating the three result categories and flagging the district limitation. Combined with the 100%-covered input schema, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% and the single `ids` parameter is fully described in the schema ('Old district/city ids saved from earlier Divar data'). The description echoes this framing without adding format, ordering, or batching semantics, 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 (convert) and resource (old Divar place ids → current ones), with the reason (Divar merged and renumbered places). An agent can immediately distinguish this id-remapping utility from lookup siblings like dv_districts or dv_place_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 trigger condition — 'when an id from an old link or saved data returns nothing' — and routes the district-checking case to the named alternative dv_districts. Both when-to-use and when-not-to-use are 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 establish read-only, idempotent, open-world, non-destructive behavior, so the bar is lower. The description still adds real value by disclosing the return shape (coordinates plus bounding box), calling itself an autocomplete service, and noting that Persian text works best. Error/empty-result behavior is not covered.

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 function and immediately followed by the canonical follow-up tools. No filler or redundancy.

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

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

There is no output schema, and the description compensates by naming the returned values (lat/lon and bounding box) and how to use them. What it omits is failure/ambiguity handling for unrealized queries, which matters for geocoding but is minor for a read-only lookup.

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 adds meaning beyond the schema by stating the expected input nature (landmark or street name) and the query-language preference ('Persian text works best'), which the schema does not express.

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 concrete verb and resource: 'Map autocomplete: turn a landmark or street name into coordinates and a bounding box.' It also names the output artifacts, which differentiates it from generic search. It does not, however, distinguish itself from nearby-sounding siblings such as dv_suggest or dv_parse_query.

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?

Guidance is limited to downstream consumption: 'Use the returned lat/lon with dv_nearby ... or dv_locate.' That implies this is the geocoding entry point, but there is no explicit statement of when to prefer it over dv_suggest/dv_place_mapping, and no exclusion conditions.

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

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

Annotations only cover the read-only/idempotent safety profile, and the description adds real behavioral facts beyond that: lat/lon are fuzzed ~500 m, no phone number is exposed because Divar hides it from anonymous users, `suspect_price` marks placeholder prices, and `rent 0 + full_deposit` means رهن کامل. These are non-obvious data-shape and visibility constraints an agent could not infer from structured fields.

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 a one-line scope statement, then grouped into price semantics, location/feature semantics, the contact limitation, and next-tool routing. It is dense with backticked field names but every clause carries information; a slightly tighter price sentence would earn a 5.

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

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

With no output schema, the description carries the full burden of explaining the return payload, and it does: price/deposit/rent, specs, images, fuzzed coordinates, and the missing phone field. Nothing an agent needs to interpret or act on the response is absent.

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

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

Schema description coverage is 100%, so `token`, `full_text`, and `max_images` are already fully documented in the schema (including the 1500-char truncation default). The description's backticked terms (`price`, `deposit`, `rent`, `negotiable`) describe return fields, not input parameters, so it adds little beyond the baseline for this dimension.

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 scope: 'Everything public about one ad', immediately establishing this as the single-ad detail fetch. The phrase 'one ad' implicitly contrasts with the list/search siblings (dv_posts, dv_search) without the agent needing to open 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?

Ends with explicit routing: 'Next: dv_similar, dv_appraise (is the price fair), dv_seller, dv_compare', and notes to use `url` for seller contact since no phone is returned. It gives clear follow-on context but no explicit when-not-to-use condition (e.g. 'use dv_posts for batches').

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, openWorld), but the description adds non-obvious behavior: compact payload (specs plus one image, description truncated at 300 chars) and partial-failure semantics where a removed ad yields an `error` field instead of failing the whole call. That is meaningful context beyond the annotations, though ordering/pagination behavior is 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, zero filler, with the payload shape front-loaded and the routing hint second. Every clause earns its place.

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

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

With no output schema, the description usefully sketches the return shape (compact specs, one image, truncated description, `error` for removed ads), which is enough to call and interpret it. Minor gaps remain, such as whether results are returned in token order.

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 description coverage (type, example, maxItems), the schema carries the semantics. The description only restates the batch cap of 10, adding no format or token-provenance 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 ('Details of up to 10 ads in one call') plus the batch scope, which cleanly distinguishes it from the singular sibling dv_post. An agent knows exactly what this returns 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?

'Use to read a shortlist from dv_search' names the upstream tool and the workflow condition that selects this one, which is strong routing guidance. It does not state explicit exclusions (e.g., when to prefer dv_post or dv_compare instead), so it stops short of a 5.

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

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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true. The description explains the write side effect that makes this non-readOnly (one point per day persisted to a local file), the replacement behavior on a second same-day call, and the fact that history only starts from the first call and can never be back-filled. That is meaningful context beyond the annotations, though it says nothing about failure modes or file location.

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 what the tool produces, then the mechanics, then the caveat and the alternative. Four dense sentences, each carrying information; slightly long but no filler and no repetition of the name.

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

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

With 8 optional params, nested filters and no output schema, the description compensates by describing the return shape (last 90 points plus change_pct) and the persistence model. It lacks detail on the `filters` object (delegated to dv_filters) and on what happens when zero results are recorded, leaving minor gaps.

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, but the description ties parameters to behavior: `pages` defines the scan scope, `record` controls whether today's median is persisted, and `query`/category narrowness determines whether the median is meaningful. It stops short of documenting city/districts/brand_model 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 precise verb+resource: it records the median asking price of a search, one point per day, in a local file, and returns a 90-point series with change_pct. It explicitly names the sibling it is not (dv_market for one-off distributions), so an agent can separate the two 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 concrete when-to-use guidance (call daily, a scheduler helps), an explicit exclusion/alternative ('For a one-off distribution use dv_market'), and a query-quality constraint ('Use a narrow query: a mixed category's median is noise'). It also states the repeat-call semantics (same UTC day replaces today's 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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses promoted older ads appearing in the first 1-3 rows, that ordering is newest-first, that unsupported category filters are returned in 'ignored', and that an empty Persian query is retried once with folded letters. These are non-obvious runtime behaviors an agent could not infer from annotations or 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?

Front-loaded with the core purpose, then a tight second paragraph of behavioral facts. The second paragraph is clause-heavy, but each clause carries distinct information (age_h, image, suspect_price, ordering, cursor, ignored, retry), so little is wasted.

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

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

For a 20-parameter tool with no output schema and nested filter objects, the description does the heavy lifting on return-value semantics (age_h units, image gating, suspect_price 'outlier' rule, next_cursor), deferring only the card field list to server instructions. The remaining gap is that it doesn't explain the ignored-filter contract's impact on results or pagination limits with `pages`.

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 schema description coverage at 100%, the baseline is 3, but the description adds relational meaning the schema does not: 'image comes only with thumbnails' ties two parameters together, and it clarifies cursor semantics by mapping 'next_cursor' from a prior call into the cursor param. Dense param docs are still carried by 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?

Opens with a specific verb+resource+scope: 'Search Divar ads in one or more cities by category, text and filters', plus the output shape ('compact cards, prices in Toman'). This is clearly distinguishable from siblings like dv_count, dv_cheapest, or dv_nearby 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?

Usage is implied through the 'Next: dv_post, dv_compare, dv_cheapest, dv_market' follow-up list and the cursor-continuation note, but the description never states when to prefer dv_search over the many overlapping siblings (dv_count, dv_find_deals, dv_place_search) or any when-not conditions. Adequate but leaves the routing decision to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuine context beyond them: the privacy posture ('No phone number or identity is exposed') and the data-shape caveat that a personal seller has no business card (`seller_kind`).

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 its outputs, then usage, then caveats. The parentheticals ('one flat or fifty cars?') carry real semantic signal rather than filler, though the sentence count is slightly higher than strictly needed.

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 return-value meaning, and it does: ad counts, business card fields, and the ad list, plus the seller_kind caveat. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so both input params (token, limit) are fully documented in the schema. The description mentions brand_token and seller_kind, but those are output fields rather than inputs, so it adds little input-parameter meaning beyond the schema. Baseline 3.

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 ('the seller behind an ad') and enumerates the concrete outputs: personal/business ad counts, the business card (name, brand_token), and their ads. It also differentiates itself from siblings by naming dv_dealer and dv_post, so an agent can place it precisely.

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

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

Explicitly states the use case ('judge a seller... and list their other ads') and routes to the alternative: 'For a dealer's whole page call dv_dealer with the brand_token (`dv_post` does not give one)'. The when-to-use and the fallback are both spelled out.

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 safe/idempotent read semantics, and the description goes well beyond them: the four-level breadcrumb widening order, narrowest-first sorting, newest-first ordering, and concrete outlier exclusion thresholds for property (5x price, 0.4x/2.5x area) with the resulting `excluded_outliers` count. This is exactly the behavioral context an agent cannot infer from structured fields.

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 and scope are front-loaded in the first sentence, and each subsequent sentence adds a distinct fact (search strategy, sort order, exclusion rules, next tools). It runs long and includes an illustrative parenthetical, but no sentence is pure 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?

There is no output schema, so the description carries the return-value burden and does so: it names `basis` and `excluded_outliers` and states the sort order. Combined with the disclosed filtering rules, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds interpretive meaning the schema lacks: 'widening step by step' clarifies what `pages` (pages scanned per breadcrumb level) actually traverses, and the breadcrumb level list explains what the returned `basis` refers to.

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

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

States a precise verb+resource ('Ads similar to one ad') plus the matching logic (same brand/model or category + neighbourhood) and the widening fallback. An agent can distinguish it from siblings like dv_nearby or dv_search 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?

Explains the algorithmic context ('Divar has no similar-ads endpoint; this searches the ad's own breadcrumb') and names the follow-on tools (dv_compare, dv_appraise). It does not, however, explicitly state when to prefer this over other discovery siblings such as dv_nearby or dv_find_deals.

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 safety is covered. The description adds genuinely new context: the check is 'one small request to Divar' (cost/latency footprint) and it discriminates network failure from argument error. It does not discuss caching/TTL of the reported values, so it stops short of 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 it returns and then the diagnostic condition. The closing pointer to the server instructions is mildly tangential but earns its place as ordering guidance.

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

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

With no parameters, no output schema to explain, and rich annotations, the description covers what an agent needs: what is reported, when to call it, and its request cost. Only the shape/reliability of the reported values (e.g. cache freshness) is left implicit.

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 no parameters, so there is nothing for the description to clarify beyond the schema; baseline for a zero-param tool is 4.

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 ('Is Divar reachable and how fast') plus the exact facets exposed (version, live latency, caches, local watch state). This clearly separates it from the search/listing siblings, which never report transport health.

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 — 'Call first when other tools fail' — and states the diagnostic payoff (distinguishing a blocked network from a bad argument). It also routes the agent to the server instructions for the normal tool order, so when-not-to-use is implied by that ordering.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description usefully adds return-shape semantics absent from any output schema: each suggestion carries a category slug and a probability, and `categories` are guesses for the bare word. This is real added value beyond the annotations.

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

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

Two short paragraphs with no waste; the purpose comes first and the usage hint plus next step follow. The opening sentence is slightly roundabout but still front-loaded and economical.

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 two-parameter lookup with no output schema, everything an agent needs is present: what is returned (slug + probability), when to reach for it, and where to go next. The `city` parameter is fully covered by the schema, so no gap remains.

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

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

Schema description coverage is 100%, so both `query` and `city` are already fully documented in the schema. The description adds no syntax or format detail beyond what is there, 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 function ('what Divar's search box would suggest for some text') plus a second output type (category guesses), so the agent knows exactly what comes back. It partially differentiates from siblings by naming dv_search as the follow-up step, though it never explicitly contrasts with the near-neighbour dv_parse_query or dv_categories.

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 states a clear trigger condition: use this when the user only supplied a product name and you need the right category and a good query. It also points to the next tool in the workflow ('Next: dv_search'), but gives no when-not guidance or distinction from dv_parse_query.

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?

Despite annotations already covering safety (readOnlyHint=false, openWorldHint=true), the description adds substantial non-obvious behavior: state is a local file at ~/.divar-mcp/state.json, overridable via DIVAR_MCP_STATE, holds only the caller's searches, nothing is pushed, and check mutates the mark so the next call shows only newer ads. That is exactly the kind of hidden-state disclosure annotations cannot carry.

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

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

Front-loaded with purpose, then action semantics, then state location, then next-step routing — a sensible ordering with no filler. Slightly dense and the mid-paragraph line breaks are arbitrary, but every sentence carries needed 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, nested-object, mutation-and-read hybrid with no output schema, the description covers the create/check lifecycle, persistence model and follow-up tool. list and delete are left to the schema, which is acceptable given 100% coverage.

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 adds genuine meaning by tying `create` params to dv_search's argument set and clarifying the mark semantics of `check` (watch_id omitted = check all). It stops short of explaining several action-specific params, which the schema already covers.

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 (save a search, then get only ads that appeared since the last check) and immediately distinguishes itself from siblings by naming dv_search, dv_new_since and dv_post. An agent knows this is a persistent watchlist, not a one-shot search, 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?

Explicitly routes usage: `create` reuses dv_search arguments, `check` runs dv_new_since and advances the mark, and check 'does not run by itself: call it from a schedule or when asked'. It also names the follow-up tool (dv_post for a new ad), so the when-and-what-next is fully specified.

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