deweloperuch-mcp

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

Goes well beyond the readOnly/openWorld annotations: declares the estimate is approximate, explains estimated_value=null and the low_confidence<5 threshold with required hedging, enumerates result fields including truncated/omitted/hint, and warns that each call is a live service request that should not be batched across many points.

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 one-line purpose and caveat, then return contract, then prerequisites; every paragraph carries actionable information. Minor redundancy from re-stating coordinate sourcing that the schema already explains, and the description is long for a 5-parameter tool.

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?

Despite an output schema existing, the description supplies the handling rules an agent needs (null → read hint, low_confidence → hedge, truncated/omitted handling) plus cost awareness and the coordinate prerequisite. Nothing needed 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 coverage is 100%, so lat, lng, limit and area_m2 are already documented; the description mostly repeats the coordinate-sourcing guidance already present in the schema descriptions. It adds the useful nuance that address does not determine position (lat/lng decide), but that too is mirrored 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?

States a specific verb and resource ('Szacuje wartość mieszkania o danym metrażu w punkcie (lat, lng)') plus the data source (transakcje z Rejestru Cen Nieruchomości) and the caveat that it is a comparison, not an appraisal. It does not explicitly say how it differs from the aggregate-statistics siblings (get_market_statistics, get_transaction_statistics), so differentiation is inferable rather than stated.

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 ('Użyj, gdy użytkownik pyta, ile może być warte mieszkanie albo czy jego cena jest rynkowa'), a hard prerequisite (coordinates required, no geocoding), and routes the agent to search_locations or get_investment to obtain lat/lng. It also forbids batch use. It stops short of explicit when-not-to-use exclusions against the statistics 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?

Beyond the readOnly/openWorld annotations, it discloses ordering rules (units by newest transaction, each unit's transactions oldest-first), how non-regular transaction classifications are excluded from averaging and counted separately, truncation semantics via truncated/units_omitted/units_total, incomplete recent registry months, and the extra backend call cost of include_trend. This is exactly the behavioral context 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?

It is front-loaded with the purpose, then slug/URL, ordering, caveats, and limits in a logical sequence. It is dense and long, and the limit/truncation rules are partly duplicated in the schema, but nearly every sentence carries information an agent needs.

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

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

For a tool with an output schema, three parameters, and full schema coverage, the description covers everything an agent needs: what is returned, ordering, exclusion of non-market transactions, truncation flags, data-lag caveat, and the cost of the optional trend query.

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 real meaning: building_slug is defined as the last URL segment of the building page with an example and a fallback instruction, and include_trend is explained as a nearby-area average over the last 12 quarters within radius_km. The limit behavior is also restated for truncation context.

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 ("Zwraca budynek z rejestru cen transakcyjnych (RCN)") and enumerates the returned components: address, coordinates, average prices, and units with transactions. It explicitly differentiates itself from sibling offer tools with "To ceny, za które lokale sprzedano, nie ceny ofertowe deweloperów."

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 selection context: use only for apartment buildings, not houses ("tylko budynki z mieszkaniami, nie domy"), and instructs the agent to ask the user for the page link when building_slug is unknown. It does not, however, name a sibling alternative for the case where the building is unknown but a location search could help.

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/openWorldHint already covering the safety profile, the description still adds substantial behavior: default scope is all of Poland, city narrows both summary and investments, cities is always Poland-wide with a hint when the site provides no city list, summary is computed by the tool from investments in scope, summary.cities is a count, and truncation is signalled via investments_omitted/truncated/hint. It even specifies output guidance (developer_url and investment_url should be surfaced to the user as links).

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 usage, then parameter scope, then limits — a sensible order with no filler sentences. It is dense and runs long, and the developer_slug provenance restates the schema description, so some trimming is possible, but every remaining block 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 three-parameter read tool with an output schema, the definition covers scope defaults, aggregation semantics, truncation signalling, and cross-tool slug sourcing. An agent has everything needed to call it correctly and interpret partial results.

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 goes further by explaining what city actually changes (aggregation scope for summary/investments, default 'polska'), where city_slug values come from, and the practical consequence of limit (at most N investments, omission flags). The developer_slug sourcing is largely repeated from the schema, which keeps it 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?

Opens with a concrete verb+resource ('Zwraca profil dewelopera') and enumerates exactly what comes back: name, offer summary, investments with active offers, and cities. It also explicitly bounds the tool ('Nie podaje strony www dewelopera') and distinguishes it from get_investment for individual offers, so an agent can separate it from siblings without opening schemas.

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

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

States the triggering question shape ('gdy pytanie dotyczy dewelopera: gdzie i ile buduje, w jakich cenach'), tells where to source developer_slug (search_developers, or developer_slug fields in search_offers, get_investment, get_offer, get_market_statistics), and names the exclusion case pointing to get_investment for individual offers.

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 readOnlyHint/openWorldHint it discloses concrete behavior: default of 12 periods, truncated=true signaling older data available with periods up to 120, a size estimate (~10k characters), and publication lag (last period may be weeks/months old, up to a year for Polish demography) plus an incomplete-last-period caveat via 'note'. It also flags the nbp_prices geographic limitation and that errors indicate what to supply — none of which the annotations 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?

Three tight paragraphs with clear roles: what it returns, what it excludes, and limitations — front-loaded with the resource statement. It loses a point because the field list ('periods, series (series_id, label, unit, values...), frequency, source, total, returned, truncated, available_from, note, stats_url') restates an output schema that already exists.

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 statistics tool with 3 parameters, an enum, and an output schema, an agent has everything needed: dataset semantics, location format rules (lowercase, no diacritics, hyphens, 66 powiat cities only), period limits, data lag expectations, and the instruction to surface stats_url as a link. Nothing material is left to inference.

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 cross-parameter meaning the schema only partly captures, namely that dataset availability varies by location and that an error will name the correct value. The dataset and periods semantics (enum meanings, 1–120 range, size tradeoff) largely duplicate the schema's own parameter descriptions, so it stops short of 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?

The first sentence names a specific verb+resource ('Zwraca oficjalne statystyki GUS, NBP i Eurostatu') and enumerates the exact content (mieszkania oddane i rozpoczęte, ceny m² wg NBP, bezrobocie, wynagrodzenia, demografia), plus the three location granularities. It explicitly rules out sibling concerns: offers → search_offers, RCN transaction prices → get_transaction_statistics, multi-city comparison → rank_locations.

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

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

Explicit when-not guidance with named alternatives and the condition that selects each one ('Ofert mieszkań tu nie ma (search_offers)... ceny z rejestru RCN daje get_transaction_statistics... porównanie wielu miast... rank_locations'). It also states dataset-specific usage limits (nbp_prices only 3 aggregates and some large cities, not 'polska') and warns that not every dataset exists for every location, with an error message as the fallback.

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 readOnly/openWorld annotations, it discloses pagination semantics (offers_returned, truncated, offers_omitted, offers_total), the meaning of a non-zero offers_omitted as an incomplete list, and the payload cost of include_history (~10k vs ~6k characters at limit 20). It even notes that price_change_since_start is available without history, which is exactly the trade-off an agent needs.

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

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

Front-loaded with purpose and the mapping of slug to source tools, then a clearly separated 'Ograniczenia' block for limits and cost. It is somewhat long and repeats offer/character-count figures that also appear in the limit schema description, 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?

For a 3-parameter read tool with an output schema, the description covers everything an agent needs: how to obtain the slug, how to surface the returned URLs to the user, how truncation is signalled, and when to escalate to get_offer. Nothing material is left to inference.

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 decision-relevant meaning: what limit=0 means, why not to raise the limit, and when include_history is worth its ~150-character-per-offer cost. It largely restates rather than extending the schema's own parameter text, which caps it below 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?

The description names a specific verb and resource ('Zwraca inwestycję (projekt deweloperski)') and enumerates exactly what comes back: city, street, coordinates, developer, average prices of active offers, offer counts, and an offer list ordered active-first. It also distinguishes itself from a sibling by pointing single-offer lookups to get_offer.

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 explicitly when to use it ('Użyj, gdy chcesz zobaczyć mieszkania jednego projektu'), where the required investment_slug comes from (search_investments, search_offers, get_developer), and redirects to get_offer when only one listing is needed. Both the positive trigger and the alternative path are present.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantially more: only active (non-archived) offers are counted, only one city per call, "polska" fails, figures are as-of the as_of result field and may diverge from search_offers totals, and individual offers are absent so list_url/developer_url must be surfaced to the user as links. These are real behavioral traits an annotation 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 purpose and outputs, then usage routing, then caveats — a sensible ordering. It is dense and the enumeration of every developer field is somewhat verbose, and "Opcjonalnie tylko oferty z zakresu ceny i metrażu" partly restates optional schema defaults, 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?

For a read-only statistics tool with 6 params, full schema coverage and an output schema, the description covers scope, freshness, aggregation caveats, and the follow-up links an agent must present. Nothing needed to call it correctly — or to interpret the numbers — 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 baseline is 3, but the description adds meaning beyond the schema: city must be a city_slug obtained from search_locations and must not be "polska", and the price/area parameters restrict which offers the statistics are computed over rather than just filtering output. The top_developers parameter's effect is only implied by the mention of "największych deweloperów wg liczby ofert".

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 ("Zwraca statystyki rynku ofert deweloperskich w jednym mieście") and enumerates exactly what is returned: offer/investment/developer counts, price and price-per-m² and area distributions as min/p25/median/p75/max, and top developers by offer count. It then explicitly contrasts itself with search_offers (individual listings) and get_developer (a developer's investments), so the agent can distinguish it from siblings 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?

Provides an explicit when-to-use rule — "Użyj, gdy pytanie dotyczy rynku miasta (typowe ceny, kto ma najwięcej ofert)" — together with the when-not condition ("a nie konkretnych mieszkań") and the exact alternative to route to (search_offers, get_developer). The single-city constraint and the warning that "polska" is not a valid city_slug further steer correct invocation.

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 and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the two-parameter prerequisite, the fields returned, the semantic meaning of price_flags, and the instruction to surface investment_url/developer_url as links. It does not cover pagination or error behavior, so a 4 rather than 5.

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

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

It is front-loaded correctly: purpose, then when-to-use, then prerequisites, then return contents. The price_flags explanation is lengthy and partly overlaps what the output schema already carries, but it does encode semantics (e.g. the suspicious_reduction rule) that are not self-evident. Slightly verbose but each block 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?

For a tool whose complexity lies in price-history interpretation, the description supplies the prerequisite, the alternative tool, the return shape, and the meaning of every flag. Even though an output schema exists, the semantic definitions of lowest_price_30d/90d and suspicious_reduction are necessary context an agent cannot infer from structure alone.

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 both parameters and their sources. The description adds only the constraint that offer_id alone is not enough, which is a marginal increment over the schema's own parameter descriptions. 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 opens with a specific verb+resource: it returns one offer together with its full price history, investment, and developer. It explicitly distinguishes itself from the sibling get_investment by noting that listing offers for one investment is a different tool. An agent can tell exactly what it retrieves 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 an explicit use case ("Użyj, gdy chcesz zobaczyć, jak zmieniała się cena mieszkania"), names the alternative for a related task (get_investment for offer lists), and states a hard prerequisite: both offer_id and investment_slug are required, with offer_id alone insufficient. Nothing about when/when-not 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?

Beyond the readOnly/openWorld annotations it discloses non-obvious behaviour: default of 12 periods, truncated=true meaning older data exists, the 60-period ceiling, publication lag causing incomplete periods, periods with no transactions, and that last_complete_period is still provisional with a hint field for suppressed values. That is substantive operational context, though the response envelope itself is left to the 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?

Structure is deliberate: purpose and sibling disambiguation first, then granularity semantics, then constraints and data-quality caveats. It is dense and the long run-on sentence about truncated, incomplete and last_complete_period packs several distinct rules together, but no sentence is filler.

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

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

For a read-only three-parameter statistics tool with a full output schema, the description covers everything an agent needs: scope limits, mode trade-offs, pagination ceiling, data-lag handling and how to treat incomplete or empty periods. Return-value detail is correctly delegated to the output schema.

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

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

Schema coverage is 100% and the schema descriptions already define the month/quarter trade-offs, the 1–60 range and the city_slug format, so the description largely restates rather than adds. The only marginal additions are the pairing of truncated with periods and the note that periods=60 gives full history only for quarter.

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 (transaction prices for flats in a city from RCN since 2017) plus the measures returned, and explicitly separates this tool from three named siblings: search_offers, get_market_statistics and get_government_statistics. An agent can pick this tool over its neighbours 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?

It states when to use each mode (month = secondary market with full medians; quarter = long history but fewer measures) and explicitly warns not to merge the two series. Hard exclusions are spelled out: flats only, whole cities only, no districts, streets, aggregates or Poland-wide data.

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 readOnlyHint/openWorldHint by disclosing data-quality caveats an agent could not infer: the service doesn't say whether prices/area are mean or median, city period is not reported, price sorting silently drops places below 20 transactions unless min_transactions=0, market=all totals may not equal secondary+primary, and nbp_price_per_m2 covers only 17 cities. It also explains that omitted places are surfaced via 'hint', which directly affects how results should be interpreted.

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

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

Front-loaded with purpose and the two modes, then constraints — good ordering. It is long, and the paragraph enumerating return fields overlaps with the existing output schema, which is the one place wording does not fully earn its space.

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 six-parameter, two-mode ranking tool with heavy cross-tool definitional traps, the description covers mode selection, incompatibilities, default thresholds, data caveats and result interpretation. Combined with the output schema, an agent has everything needed to call it correctly and to avoid the documented pitfalls.

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 this is above baseline: the description adds cross-field constraints the schema only partially implies (indicator excludes level=powiat, min_transactions and market), a usage tip for limit ('zawężaj min_transactions, nie podnoś limitu'), and a definitional warning that average_dwelling_area is not comparable to average_area from get_government_statistics. Slightly redundant in restating enum semantics already documented per-parameter.

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

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

The opening sentence names a specific verb+resource ('Porównanie wielu miejsc w jednym okresie') and immediately states the negative scope ('nie zwraca szeregu czasowego'), then splits it into two explicit modes (with/without indicator). It names the sibling tools that cover the excluded case, so an agent can route without opening any schema.

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

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

Explicit when-to-use routing: 'Trend jednego miasta w czasie: get_transaction_statistics (RCN) albo get_government_statistics (GUS, NBP)'. Mode selection conditions are stated (level=city vs powiat without indicator, indicator forces city-only), and it warns against an invalid comparison ('nie porównuj liczb transakcji miejscowości i powiatów').

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 and openWorldHint, so safety is covered; the description adds genuinely useful behavior: the name-to-slug conversion role, the truncation contract (truncated=true means more matches exist, refine or raise limit to max 20), and the total=null edge case. It does restate some return-field structure that the output schema likely covers, which keeps it off a 5.

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

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

Front-loads the core purpose before the routing rationale, then the return/truncation contract. Dense but every sentence carries information; the field-by-field enumeration of items is the only mild over-explanation.

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 an output schema, full parameter descriptions, and annotations present, the description only needs to add the lookup role and truncation handling, both of which it covers. 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 coverage is 100% and the schema already documents both 'name' (fragment, 2–100 chars, examples) and 'limit' (default 5, max 20). The description largely repeats those facts, though it does add the framing that 'name' is a lookup key for slug resolution. Baseline 3 is appropriate when the schema carries the load.

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 ('Znajduje deweloperów ... po fragmencie nazwy') and scopes it to the primary market, then explicitly excludes adjacent data ('Nie zwraca ofert ani cen'). It distinguishes itself from siblings by naming the downstream tool it feeds, get_developer.

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 ('Użyj, żeby zamienić nazwę dewelopera na developer_slug, którego wymaga get_developer'), names the alternative/next step, and states a when-not ('Nie zwraca ofert ani cen'). An agent knows exactly when to pick this over search_offers or get_developer.

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 and openWorldHint, so the description carries the real behavioral load: it discloses that city mode returns only investments the site shows on the city map (those without active offers may be absent), that averages cover active offers only, that items without an average sort last, and that total/returned/truncated/hint report what was cut. It even flags that links should be surfaced to the user.

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

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

Front-loaded with purpose and the two modes, then grouped into return fields and limits. Dense and mostly waste-free, though the enumerated return-field list partially duplicates what the output schema already provides and could be trimmed.

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 five-parameter search tool with an output schema, annotations, and eleven siblings, nothing an agent needs is missing: mode selection, field availability per mode, sorting behavior, filtering exclusions, and truncation reporting are all 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 the baseline is 3, but the description adds cross-parameter semantics the schema does not: which parameters only work together with city (sort, developer_slug), how name alone switches to nationwide site-ordered search, and a practical sizing rule for limit (roughly 550–750 output characters per city item).

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 ('Wyszukuje inwestycje – projekty deweloperskie, rynek pierwotny') and immediately distinguishes the two operating modes (city = full data, name-only = whole Poland with a reduced field set). An agent can tell this apart from search_offers and get_investment without opening any schema.

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

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

Gives explicit when-to-use guidance with concrete examples (cheapest per m² in a city, one developer's projects, slug lookup by name) and names the boundary against siblings: price/area filtering goes to search_offers, offer and project details go to get_investment. It also states the negative case (city=polska does not work).

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

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

Annotations already cover read-only/open-world safety, and the description adds valuable semantics beyond them: total=null meaning, truncated=true handling, offer_count=0 exclusion, and that search_offers does not filter by street. Much of the raw field list is redundant with the existing output schema, so it stops short of a full 5.

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

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

Purpose is front-loaded, followed by usage, then output semantics; every sentence is information-dense. It is somewhat long and the itemized field list borders on redundancy given the output schema, but 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?

Given a single-param tool with an output schema and read-only annotations, the description covers purpose, the sibling dependency, edge-case semantics (truncation, zero-offer filtering), and downstream usage. 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% and the single query param is fully documented in the schema (length, Polish characters, examples). The description restates it as a name fragment without adding syntax or format beyond what the schema already provides, 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?

States a specific verb+resource: finds cities, districts and streets in Poland by name fragment. It explicitly distinguishes itself from siblings by noting it returns neither offers nor prices, which sets it apart from search_offers. An agent can identify its role immediately.

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

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

Explicitly says to use it at the beginning to convert a place name into the city_slug required by search_offers, giving the exact ordering and dependency. It also states when NOT to forward results (offer_count=0) and how district/street map to search_offers parameters.

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 and openWorldHint=true, so the safety profile is known. Beyond that the description discloses genuinely useful behaviour: a hard 20-page ceiling, what truncated=true means and the instruction to narrow filters rather than page further, and the caveat that status=all totals are computed inconsistently upstream. These are substantive additions, but return-format detail overlaps with the output schema, so it sits comfortably above a bare baseline rather than at the top.

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 front-loaded and organised into purpose, return shape and limits, and each block carries real information. However the semicolon-chained sentences are dense, and the item-field enumeration duplicates the existing output schema, which is exactly the kind of repetition that dilutes a definition without adding value.

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 13-parameter, paginated, cross-referenced search tool this covers what an agent needs: entry prerequisites, filter capabilities, pagination limits and truncation handling, plus routing to get_offer and get_investment for depth. Given an output schema already exists, the field-by-field return listing is redundant rather than filling a gap, which is the only shortfall.

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%, yet the description still adds meaning the schema lacks: it enumerates the supported filter set, explains that an omitted sort yields an unguaranteed, non-ranking default order (so an agent should always pass sort), and warns that price_dropped keys off the change from the first price. It also documents the negative space — no room, floor or developer filters — which is parameter semantics no schema can 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?

The opening sentence gives a specific verb and resource ('Wyszukuje oferty mieszkań od deweloperów') plus hard scope boundaries: primary market only, asking prices rather than transaction prices, one city or one district, and the explicit caveat that city=polska does not work. It also names the siblings that serve different purposes (get_offer, get_investment, get_developer, search_locations), so an agent can separate this tool from its neighbours 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?

It states when to call it (city or district level search) and when not to (no room/floor/developer filtering; use get_developer for a developer's projects, get_investment for all offers in one investment, get_market_statistics for city-wide price levels). It also gives the exact preconditions: obtain city_slug and district names from search_locations, because the city value must be a single-city slug.

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