YerevanEstate — Yerevan apartment prices

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

Annotations only declare readOnlyHint=true, so the description carries the return-shape burden and does so well: sale price per m² and total, monthly rent, contributing factors, building floors/material, street median, and amenity distances. However, it says nothing about behavior when an address can't be geocoded, how ambiguous addresses are resolved, or confidence/precision of the model output – meaningful gaps for a geocoding-plus-pricing tool.

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

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

The core purpose is front-loaded in the first clause, but the rest is one very long sentence with stacked parentheticals enumerating model features and nearby amenity types, which is hard to scan. The Russian tail-line is a fair localization touch, but the amenity lists could be compressed without losing information.

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

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

For a 12-parameter read-only tool with no output schema, the description is fairly complete: it explains the inputs' role at a high level and describes the returned values in detail, including the amenity distance payload. The main missing piece is guidance on the many optional property attributes and what happens on address-resolution failure.

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 only 42% across 12 parameters, so the description should compensate more than it does; it mentions floor, renovation, and building data as model inputs but leaves sqm, rooms, ceiling, elevator, material, newBuild, furniture, and listingType unexplained beyond the schema. It does hint that both sale and rent estimates are returned, which gives implicit meaning to listingType. Baseline-plus for partial compensation.

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

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

States a specific verb+resource ('Price for a flat at an exact Yerevan address') and scopes it to building-level geocoding, which clearly separates it from area-level siblings like get_area_stats and the generic estimate_price. The multilingual address examples further pin down what the input identity looks like.

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

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

The phrase 'exact address' plus three example address formats makes clear when this tool applies versus coarser area tools, and 'Free' tells the agent there is no cost barrier to calling it. It never explicitly names the alternatives (estimate_price, get_area_stats) or states when NOT to use it, so routing still requires inference.

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

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

Annotations only declare readOnlyHint=true, so the description carries the burden of explaining what the tool produces, and it does: a price band plus up to 5 comparable listings, with a verdict only when a price is passed. It does not disclose data recency, minimum comparable count, or what happens when the market has too few listings, which would matter for trusting the verdict.

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 front-loads the core output description and uses short clauses for the sale/rent distinction, so the important information is read first. The trailing Russian phrase ('Оценка квартиры: дорого или нет') and the enumeration of percentiles are slightly padded, but no sentence is wasted overall.

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

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

For a 9-parameter, enum-heavy tool with no output schema, the description supplies the missing return-value picture (percentiles, verdict, up to 5 comparables) and clarifies units per listing type. It leaves out data freshness and behavior on sparse comparables, which are the remaining gaps for a valuation 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 89%, so nearly every parameter is already documented, including the English/Russian/Armenian district formats and the rent-only requirements for rooms and furniture. The description reinforces the sale-total vs monthly-rent interpretation of price and the role of sqm, but adds no format, default, or interaction detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb (estimate) and resource (Yerevan apartment sale price or monthly rent), then enumerates exactly what comes back: median, 25th–75th percentile, and a below/in/above-market verdict. An agent can distinguish this valuation tool from retrieval siblings like get_listing or get_area_stats 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 clearly conditions behavior on whether a price is supplied ('if a price is given, a verdict') and separates the sale case (total for the given m²) from the rent case (per month), which tells an agent when each mode applies. It does not name alternative sibling tools or state when not to use this, so it stops short of full routing guidance.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful context that the id must come from `search` and that the tool is premium-gated, but it does not describe return behavior, failure modes, or auth requirements beyond the premium tag.

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

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

The description is a single efficient sentence with the key constraint front-loaded. The unexplained `[Premium]` label adds slight ambiguity but no verbosity.

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

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

For a simple one-parameter read tool with annotations, this is minimally adequate. However, it leaves ambiguity about the `[Premium]` requirement and how this tool differs from `get_listing`, which matters given the crowded sibling set.

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 0%, so the description must carry parameter meaning. It does explain that `id` is a listing id returned from `search`, which is useful provenance, but it does not specify format or clarify whether this is the same id used by sibling listing tools.

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

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

The description states a specific verb and resource: fetch one listing by id. It also clarifies that the id comes from `search`, but it does not distinguish this tool from sibling `get_listing` or explain the `[Premium]` qualifier.

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 by requiring an id returned from `search`, so the agent can infer it should search first. However, it does not say when to use this instead of `get_listing` or other listing retrieval 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 readOnlyHint=true, so the safety profile is covered and the description adds the default radius of 500 m plus the fact that the data is 'live' asking prices. It says nothing about freshness, latency, or empty-area behavior when no listings fall in the circle, which matters for a radius query.

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 payload information is front-loaded in the first clause and the usage rule follows immediately, so the agent hits the important content first. The trailing Russian tagline 'Цены вокруг точки' is a pure duplicate of the English purpose and is the only wasted text.

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 enumerates the returned statistics and mentions the street names, which is what an agent needs to judge relevance. The only real gap is the absence of any note on what happens when the circle contains no listings.

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 0%, so the description must carry the load, and it does more than the schema: it explains that radiusM is a distance in meters around a point and that its default is 500 m. lat/lng are described only implicitly as 'a point' and via the geocoding hint, leaving their coordinate convention unstated.

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

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

The description states a specific verb and resource — 'Live asking-price stats for all listings within radiusM of a point' — and then enumerates the actual metrics (median $/m², p25–p75, new vs resale, days on market, price cuts, streets). That enumeration makes it easy to distinguish from get_market_overview and get_district, which are broader-scope 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?

It gives a concrete trigger phrase, 'how much near X', plus an explicit prerequisite ordering: geocode X first. It does not name an alternative tool or state when not to use it, so it stops just short of full routing guidance.

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

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

Annotations declare readOnlyHint=true, so safety is covered; the description adds that the source is government data and the aggregation grain is monthly with a new-build/secondary split. It does not state the time coverage available, any publication lag typical of government statistics, or the response shape, which matters given there is no output schema.

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

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

Two short sentences with the metric and scope front-loaded, which makes it fast to parse. The trailing Russian sentence 'Сколько квартир продано' duplicates the English meaning and does not earn 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 one optional parameter and no output schema, the definition covers the essentials but leaves the return shape underspecified: it is unclear whether results come as a time series of counts per month, how far back the data goes, and whether the new-build/secondary split is a field or a separate series. Adequate but with clear gaps for an agent planning to consume the output.

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 schema already explains accepted district formats (English/Russian/Armenian names or number 2–13). The description only confirms the filter is optional and limited to a single district, adding little beyond the structured field. Baseline 3 is appropriate.

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

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

States a specific resource and metric: monthly count of apartment sale deals from government data, broken out by new-build vs secondary. This is distinguishable from siblings like get_price_history or get_area_stats by resource and metric. It stops short of naming a sibling explicitly, so a 4 rather than 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?

'Optionally for one district' tells the agent the parameter is a filter and that omitting it yields all-district data, which is useful. However, there is no guidance on when to prefer this over get_area_stats, get_market_overview or get_price_history, leaving the agent to infer the distinction.

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 (readOnlyHint=true), so the description's job is to explain the payload, and it does: it discloses the returned dimensions (monthly price per m², new-build vs secondary, renovation, building material) even though no output schema exists. It stops short of stating units/currency, the time coverage, or what happens for an invalid district identifier.

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 definition is short and the metric list is front-loaded, but it is telegraphic rather than well-formed prose, and the trailing Russian sentence 'Подробно о районе' is vague filler that restates the tool's purpose without adding information. Removing it would lose nothing.

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

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

For a single-parameter read tool with full schema coverage and no output schema, the description covers enough to call it, and the enumerated metrics compensate somewhat for the missing output schema. It leaves gaps an agent would care about: units and currency of the price figures, how many months of history are returned, and behavior on an unknown district.

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%: the 'district' parameter is fully documented in the schema, including the English/Russian/Armenian name forms and the numeric 2–13 option with examples. The description adds no additional meaning about the parameter, 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 resource (a single Yerevan district) and enumerates the metrics returned: price per m² by month and splits by new build vs secondary, renovation and building material. That is enough for an agent to distinguish it from market-wide siblings like get_market_overview, though it never explicitly contrasts it with the close siblings get_area_stats or get_street.

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?

There is no explicit when-to-use guidance and no named alternative. The phrase 'One Yerevan district' weakly implies per-district granularity as opposed to street- or address-level tools (get_street, estimate_address), but the agent must infer that boundary itself, and the trailing 'Подробно о районе' adds nothing directive.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: a '[Premium]' tier gate that can affect whether the call succeeds, and an enumeration of the returned content (specs, price history, days on market, verdict, comparables), which matters since no output schema exists.

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

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

A single front-loaded sentence with the verb, lookup key, and payload contents in order of importance. Nothing is redundant with the schema, and the premium marker sits up front where it is noticed before invocation.

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

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

For a one-parameter premium lookup with no output schema, the description covers what is returned and the tier constraint. It stops short of saying what happens when the premium entitlement is absent (error vs. partial payload), which is the main remaining gap.

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

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

With one parameter at 100% schema description coverage, the schema already explains the id format and provenance ('starts with L', from search_listings / get_price_drops'). The description adds only 'by id', so 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 retrieval ('Full details for one listing by id') and enumerates the payload (specs, price history, days on market, fair-price verdict, comparables). This distinguishes it from list-oriented siblings like search_listings and get_price_drops, though it never names those siblings 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?

There is no explicit when-to-use or when-not guidance; usage is only implied by 'by id' and the schema note that the id comes from search_listings / get_price_drops. An agent can infer the search-then-fetch workflow but must supply the routing logic itself.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the time windows are fixed (change measured from a Sep 2025 baseline, deals over 'the last full year'), which matters because the tool takes no parameters and the agent cannot alter them. It stops short of describing the response shape or how districts are keyed, but nothing contradicts 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 metrics are front-loaded in a single dense clause and there is no filler around them. The trailing Russian sentence ("Цены на квартиры в Ереване по районам") repeats the same topic in another language and adds no selection value for an agent, which is the one piece of waste.

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

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

There is no output schema, yet the description effectively enumerates the returned fields and their units (USD per m², changes, listing counts, deal counts), so an agent knows what to expect. Only minor gaps remain, such as whether the change is expressed as a percentage and how the per-district values are structured.

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 has zero parameters, so the baseline is 4 and there is no parameter meaning for the description to supply. It correctly avoids inventing inputs and instead spends its words on what the fixed output 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?

The description names a specific resource and scope (Yerevan plus each of its 12 districts) and enumerates the exact metrics returned: average asking price per m² in USD, change since Sep 2025, listing counts, and deals per district for the last full year. That is enough for an agent to distinguish this aggregate snapshot from siblings like get_district or get_area_stats 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?

The overview framing implies when to use it (a first-pass market summary across all districts), but there is no explicit when-to-use or when-not guidance and no mention of the obvious alternatives such as get_area_stats, get_district, or get_rental_yields. The agent must infer that this is the broad, all-districts entry point rather than a single-area lookup.

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

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

With readOnlyHint=true already declaring the safety profile, the description adds real behavioral detail: the drop is computed against the maximum price in the last `days` (default 30) and results are ordered biggest-drop-first. The [Premium] prefix hints at an access/entitlement requirement, though it is not spelled out, and nothing is said about result volume beyond the schema's limit.

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 and the computation, followed by the filter summary. The trailing Russian sentence duplicates the title rather than adding information, which is mild waste but the rest is tight.

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

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

For a 7-parameter tool with no output schema, the description covers the drop logic and sort order but omits the two behaviorally significant defaults (minDropPct, listingType) and gives no sense of what a returned listing includes. Adequate to call it, not adequate to predict what comes back.

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 only 29%, so the description needs to compensate and only partly does: it explains `days` (including default 30) and implicitly the district/street/rooms filters. It says nothing about `minDropPct` (default 5) or `listingType` (default 'sale'), both of which materially change results — an agent could unknowingly exclude rentals or filter out small drops.

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 computed property: live listings whose asking price dropped, measured as current price vs the highest price in the `days` window, sorted by largest drop. It is clear enough to distinguish from search_listings or get_price_history, but it never names a sibling or explicitly excludes them.

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 'Filter by district, street, rooms' and the [Premium] tag, which signals a gated feature. There is no explicit when-to-use/when-not guidance or pointer to alternatives such as get_deals or get_price_history.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description does add real value by disclosing the returned metrics (USD and AMD price per m², plus listing counts), but says nothing about history depth, period granularity, or what happens for sparse segments — meaningful gaps for a time-series tool.

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

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

Two tight sentences with the metric definition front-loaded and the district shortcut second; nothing is wasted. The second sentence largely duplicates the schema, which keeps it from 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 four required parameters, no output schema, and no annotations beyond readOnly, the description should carry more of the return-shape burden. It states the metrics and currencies but not the time span, period boundaries, or response structure, leaving an agent unsure what a 'monthly history' actually contains.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description adds interpretive context by framing the four parameters as a segment product and restating the 'Yerevan'/1 city-wide convention, but that convention is already in the district schema description, so the net addition is modest.

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 and verb ('Monthly average asking price per m² ... and listing counts') and spells out the four-dimension segment it covers (district × material × new/secondary × renovation). An agent can tell it produces a historical series rather than a point estimate, though no sibling (estimate_price, get_market_overview, get_area_stats) is named to sharpen the contrast.

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?

There is no explicit when-to-use or when-not-to-use guidance relative to the many overlapping siblings (estimate_price, estimate_address, get_market_overview, get_area_stats). The phrase 'for one segment' only hints that all four dimensions must be fixed; nothing tells the agent why it would pick this over an estimate tool.

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

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

The annotation readOnlyHint=true already establishes the safety profile, so the description's main added value is disclosing the output payload (median yield %, typical range, median rent, median price, payback years, sample size), which is genuinely useful given there is no output schema. However, it never clarifies the scope of the result: whether it returns every district in one response, whether results are ranked, or how many districts/samples are included, which is the key behavioral unknown for a "per district" tool.

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

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

The first sentence is a dense, front-loaded list of exactly what the tool returns, with no filler. The second sentence is a short Russian tagline that conveys the use case but adds little operational information and introduces a language mix that may be less useful to an English-context planner.

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

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

With no output schema, the description correctly takes on the job of enumerating return fields, and the filters are fully documented in the schema. What is missing for a district-level aggregate is the result scope and ordering (all districts vs. a subset, sorted by yield or not) and any note on how sample size should be interpreted.

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 all three enum parameters are described in the schema, so baseline 3 applies. The phrase "for one apartment type" hints that the filters narrow the segment but does not map onto renovationType, newConstruction or constructionType, and does not explain how the defaults (renovated / No / Stone) affect the numbers returned.

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 ("Gross rental yield per district") plus an enumerated set of returned metrics, so the agent knows exactly what the tool produces. It stops short of naming or contrasting itself with any sibling, but no sibling in the list appears to cover rental yields, so differentiation is not strictly needed.

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

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

The closing line "Где выгоднее сдавать квартиру" implies the decision this tool supports (comparing districts for rental return), which is weak but real usage guidance. There is no explicit statement of when to prefer it over estimate_price, get_area_stats or get_market_overview, and no exclusions or prerequisites.

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 readOnlyHint, the description discloses non-obvious behavior: minimum sample threshold triggering a radius/district fallback, per-segment (~600 m) breakdowns of long streets, and inclusion of the 5 buildings with most listings. Each response carries n and a window, which tells the agent results are statistical estimates rather than raw listings.

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?

Dense but front-loaded: the core purpose and metrics come first, then coverage details, then the fallback rule. It is a single run-on sentence stack with a stray Russian tagline ('Цены по улице'), but almost every clause carries information an agent needs, so waste is minimal.

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

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

There is no output schema, so the description must explain returns — and it does, enumerating the metrics, the segment granularity, the top-5 buildings, and the n/window/fallback metadata. For a one-parameter read-only stats tool this covers everything needed to call and interpret 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?

With 100% schema coverage the single 'name' parameter is already documented with examples, so the baseline is 3. The description adds genuine value by stating that Armenian, English, Russian, legacy names and typos are all accepted, which the schema's example list only hints at.

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: price statistics (median $/m², p25–p75, new build vs resale, DOM, price cuts) for one named Yerevan street or block. The scope ('one street or block', plus ~600 m segments and top 5 buildings) is clear enough to separate it from area/district-level siblings like get_district or get_area_stats.

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: results carry n, window and a fallback to radius500/district when the street has fewer than 15 listings, which tells the agent what to expect and when the answer is thin. It never names an alternative tool ('for district-level use get_district'), so the routing guidance is implied by scope rather than 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?

readOnlyHint=true already establishes this as a safe read. The description adds real value beyond annotations: it declares the output is a list of ids intended for `fetch`, and shows the accepted free-text syntax. It does not disclose result limits, pagination, language support, or what 'current' excludes (e.g. sold/archived listings).

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 capability, then example, then return contract. The '[Premium]' tag and backticked `fetch` reference are compact and high-signal; no sentence 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 one-parameter read tool with annotations and no output schema, most of what an agent needs is present. Gaps remain around result volume and the overlap with `search_listings`, which matter for choosing and chaining 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 0% for the single `query` parameter, so the description must carry the semantic load. The example '2 rooms Arabkir under 120000' usefully reveals that the free-text string can combine room count, district, and price bound, but no other constraints (currency, format, length) are documented.

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 — free-text search over current Yerevan listings — and includes a concrete example query. It also names the follow-up tool (`fetch`), so the agent can see where its output goes. It loses a point because the sibling `search_listings` appears to do the same thing and is never distinguished.

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

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

The example query and the 'Returns ids for `fetch`' note imply the intended workflow (natural-language query, then hydrate via fetch). There is no explicit when-to-use or when-not guidance, and nothing tells the agent whether to prefer this over `search_listings` or the structured `get_listing` path.

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

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

Annotations only declare readOnlyHint=true, so the description must add behavior, and it does: a [Premium] access marker, a data-freshness constraint ("seen in the last 14 days"), and the return shape (up to 20 results with price, $/m², street and an id). With no output schema, that return-field disclosure is genuinely valuable. It does not explain paging behavior via offset or what happens when filters yield nothing, which keeps it below a 5.

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

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

Two tight sentences, front-loaded with the verb and resource, then the filters, then the return shape — good ordering. The trailing Russian sentence merely restates the tool title in another language and adds no new information for an agent, which is the only real waste.

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

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

For a 14-parameter, zero-required tool with no output schema, the description covers the three things an agent most needs: what it retrieves, which filters are supported and what comes back (including the id needed for get_listing). Gaps relative to complexity are pagination (offset/limit interaction) and the meaning of the [Premium] tier. Those are material but not blocking for a first successful call.

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

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

Schema coverage is only 43%, so the description must compensate, and it does by enumerating the filter families that map to most parameters (district, street or block, distance from a point, rooms, price, area, new build, renovation, sale vs rent). It does not add meaning for sort, limit or offset, which remain bare in the schema apart from defaults and enum values. Overall it recovers most of the coverage gap.

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 concrete verb and resource ("Find apartments currently listed for sale or rent") plus an explicit freshness window of 14 days, and enumerates the filterable dimensions (district, street/block, radius, rooms, price, area, new build, renovation). It also names the follow-up tool (get_listing) for the returned id, which helps separate this from generic siblings like search. It stops short of explicitly saying how it differs from search or get_listing, so it is clear but not fully sibling-differentiated.

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 rather than stated: an agent can infer this is the entry point for browsing listings and that returned ids feed get_listing. There is no explicit when-to-use/when-not guidance, no mention of when to prefer search, get_listing, get_price_drops or estimate_price instead, and no note on what the [Premium] tag gates. Adequate but with clear gaps.

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