deweloperuch-mcp

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

With readOnlyHint/openWorldHint already given, the description still adds real behavioral context: the result is approximate, each call is a live service query so batch estimation is discouraged, and estimated_value=null means the service gave no valuation so the agent must read hint. It also flags truncation/omission of comparables.

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

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

Front-loaded with the core action, then usage trigger, then return semantics, then coordinate prerequisites. Some of the return-field enumeration partly duplicates the existing output schema, making it slightly longer than strictly necessary, but every paragraph carries usable 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?

Covers the trigger, the coordinate prerequisite with sourcing options, the approximation caveat, the null-failure path, and the service-query cost constraint. Even though an output schema exists, the description's semantics (null meaning, truncation) close the remaining operational 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 coverage is 100%, so baseline is 3. The description goes beyond it by explaining that address is descriptive only and does not determine location (lat/lng govern), and that lat/lng should come from search_locations or get_investment, with the tradeoff that an investment's coordinates are more precise for a given offer.

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: estimates apartment value for a given area at a (lat,lng) point in Poland from RCN transaction prices. It also distinguishes itself from a formal appraisal ('to porównanie z transakcjami w pobliżu, a nie operat szacunkowy'), which no sibling could be confused with.

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

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

Explicit trigger ('Użyj, gdy użytkownik pyta, ile może być warte mieszkanie albo czy jego cena jest rynkowa'), explicit prerequisite (requires coordinates, does not geocode), named alternatives for sourcing coordinates (search_locations, get_investment), and an explicit exclusion ('nie wyceniaj seriami wielu punktó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 only declare readOnlyHint and openWorldHint, and the description adds real behavior beyond them: it restricts scope to apartments not houses, explains the pagination summary fields, warns that recent months may be incomplete due to registry lag, and notes include_trend costs an extra service query. Some of this describes return values already covered by the output schema, which slightly lowers the gain.

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 returned data, then the slug explanation, ordering, and constraints; every sentence carries information. It is somewhat long and repeats the limit parameter details already present in the schema, costing it a point.

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

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

For a lookup tool with an output schema, the description covers what an agent needs: data scope, ordering rules, truncation semantics, data-freshness caveats, the cost of the optional trend, and how to interpret/present building_url. Nothing essential 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 documents all three parameters fully. The description adds the origin of building_slug (last segment of the deweloperuch.pl building URL, with examples) and reinforces that building_url should be shown to the user, but largely mirrors schema content. Baseline 3 applies 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 and resource ('Zwraca budynek z rejestru cen transakcyjnych (RCN)') and enumerates the returned fields (adres, miasto, współrzędne, lokale z transakcjami). It distinguishes the data source from siblings by clarifying these are sale prices, not developer offer prices.

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 clear conditional guidance on obtaining the slug ('gdy go nie znasz, poproś użytkownika o link') and where to source it (estimate_property_value comparables), which is useful. However, it never explicitly says when to choose this tool over siblings like get_transaction_statistics or search_offers, leaving tool-level selection 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 readOnlyHint and openWorldHint, but the description adds non-obvious semantics: city narrows summary and investments while cities always covers all of Poland, and truncation is disclosed via investments_omitted and truncated. It also instructs that developer_url/investment_url should be surfaced to the user, which is an output-handling behaviour not visible in 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?

Purpose and scope are front-loaded, then slug sourcing, then city/limit constraints, so the structure is sound. The long parenthetical enumerations of output fields are partly redundant with the output schema and inflate the text, but no paragraph 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 profile tool with an output schema, the description covers everything an agent needs: what sections return, how to obtain the required slug, how city and limit scope results, what truncation signals mean, and which sibling handles individual offers. Nothing required for correct invocation 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 the baseline is 3, but the description adds real meaning beyond the schema: the ordering rule for limit (investments with most active offers first) and the subtle asymmetry that city does not scope the cities block. These are semantic constraints the schema fields alone do not convey.

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 profil dewelopera') and enumerates the returned sections (summary, investments, cities) with their sub-fields, so the agent knows exactly what this tool produces. It is clearly separable from siblings like get_investment, which the description explicitly names as the place for individual offers.

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 pytanie dotyczy dewelopera: gdzie i ile buduje, w jakich cenach') plus an exclusion ('Pojedynczych ofert tu nie ma: oferty inwestycji daje get_investment'). It also routes the agent to the right source for the required slug (search_developers, search_offers, get_investment, get_offer).

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 supply readOnlyHint and openWorldHint, yet the description adds substantial behavioral detail: default 12 periods, truncated=true signalling older data, the 120-period cap, nbp_prices limited to 17 cities and 3 aggregates (not Poland), per-location dataset availability errors, publication lag, and a warning to read 'note' because the latest period may be incomplete.

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?

Long but well-structured into three blocks (what it returns, return shape, limitations) with the core purpose front-loaded. Dense and mostly waste-free, though the return-field enumeration overlaps with the output schema 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 3-parameter tool with an output schema, the description covers the remaining gaps an agent needs: default/limit behavior, truncation, geographic coverage restrictions, data freshness/lag, and incomplete-period caveats. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the tradeoff between period frequency and payload size, the availability constraint that not every dataset exists for every location, and the fact that errors indicate which argument to change. The dataset/location enumerations themselves stay 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?

Starts with a precise verb+resource ('Zwraca oficjalne statystyki GUS i NBP jako szeregi czasowe') and enumerates the covered domains and the geographic scopes. It explicitly carves out what it does NOT return ('ofert i cen konkretnych mieszkań tu nie ma (search_offers)'), so an agent can separate it from offer-level siblings 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 clear context ('Użyj jako kontekstu rynku') and an explicit exclusion pointing to search_offers for specific listings. However, it does not route against the obvious closest siblings get_market_statistics and get_transaction_statistics, leaving the agent to guess which statistics tool to pick in borderline cases.

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 operational burden and does so well: it explains the limit default, the truncation contract (offers_returned, truncated, offers_omitted, offers_total), warns not to raise the limit casually, and flags that include_history makes the result longer and slower. It loses a point because much of that field-level detail is already carried by the output schema rather than being purely additive behavior.

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 structure is strong and front-loaded: what it returns, then when to use it, then constraints and the sibling alternative. It is somewhat long for the payload it delivers, and the limit/default restatement duplicates the 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?

An output schema exists, so return values need not be re-explained, yet the description still supplies the pieces the schema cannot: when to pick this over get_offer, how to source the slug, and how to interpret truncation. For a read-only three-parameter lookup, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents limit, include_history and investment_slug with defaults, ranges and the slug's provenance. The description largely restates those (default 20, include_history extends the result) instead of adding new 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?

The description opens with a specific verb+resource ('Zwraca inwestycję (projekt deweloperski)') and enumerates the returned data: city, street, coordinates, developer, average active-offer prices, offer count and offer list. It explicitly separates itself from the sibling get_offer ('Dla jednej oferty lepiej użyć get_offer'), so an agent can route 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 an explicit when-to-use ('Użyj, gdy chcesz zobaczyć mieszkania jednego projektu'), names the alternative for the single-offer case, and states exactly where investment_slug originates (search_investments, search_offers, get_developer). It also tells the agent to surface investment_url/developer_url to the user as links, which is actionable guidance rather than description filler.

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, but the description adds substantial behavior beyond that: only active (non-archived) offers, exactly one city, counts that may diverge from search_offers totals, no individual offers, and guidance that list_url/developer_url should be surfaced as links. This is unusually rich scoping and output-behavior disclosure.

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 usage, then limitations — a sensible order. It is dense and somewhat long, with a heavy parenthetical enumerating return fields that is partly redundant with the output schema, but every sentence still carries routing or constraint 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?

An output schema exists so return values need not be explained, yet the description still covers purpose, routing, filtering scope, data-source caveats, and exactly one city. For a 6-parameter read-only statistics tool, an agent has everything needed to invoke it and interpret constraints 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. The description adds value beyond the schema by clarifying that the price/area filters are optional and applied to offers, that city must be a city_slug from search_locations, and that 'polska' will not work — meaning not captured in the schema field text.

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

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

States a specific verb and resource ('Zwraca statystyki rynku ofert deweloperskich w jednym mieście') and enumerates exactly what is returned: offer/investment/developer counts, price and price-per-m² distributions, area percentiles, and top developers. It explicitly distinguishes itself from search_offers ('a nie konkretnych mieszkań'), so an agent can route 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 an explicit when-to-use rule ('Użyj, gdy pytanie dotyczy rynku miasta... typowe ceny, kto ma najwięcej ofert') and names the alternative tool for the contrasting case ('a nie konkretnych mieszkań (search_offers)'). Limitations are also spelled out (active offers only, single city, counts may differ).

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses reporting latency ('transakcje trafiają do RCN z kilkumiesięcznym opóźnieniem'), that recent months are incomplete with understated counts and uncertain prices, that truncated=true signals older data exists, and that empty periods carry no prices. These caveats directly affect interpretation of results.

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

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

Front-loaded with the core purpose, then distinctions, then behavioral caveats — good ordering. It is dense and repeats the month-vs-quarter field list that the granularity schema description already carries, which costs a little efficiency but the repetition is defensible for a statistical 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?

Even though an output schema exists, the description enumerates the return envelope (periods, total, returned, truncated, available_from, hint, note, stats_url) and, more importantly, supplies the interpretive caveats (incomplete recent months, truncation semantics) an agent needs to use the output correctly. Nothing material 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 the baseline is 3, but the description adds genuinely new guidance: the 60-period cap implies ~9k characters and the recommendation to use quarter for long-term trends. It also restates the scope restriction (whole cities only, no districts/streets/polska) that 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 and resource ('Zwraca ceny transakcyjne mieszkań w mieście z Rejestru Cen Nieruchomości') plus the unit of analysis (miesiące/kwartały: liczba transakcji i ceny za m²). It explicitly distinguishes itself from three siblings (search_offers, get_market_statistics, get_government_statistics) by contrasting actual sale prices against offer prices and NBP figures.

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 search_offers/get_market_statistics for offer prices, get_government_statistics for official NBP prices, this tool for actual RCN transactions. It also states when to pick quarter over month ('dla trendu wieloletniego wybierz quarter zamiast wielu miesięcy') and warns not to combine months and quarters in one series.

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/openWorldHint; the description adds substantial behavioral context the annotations cannot: return envelope (total, returned, truncated, hint, items), the ranking_url for city level, the fact powiat_id is informational and accepted by no tool, and data-quality caveats (no period given, mean/median unknown, powiat counts span many years and are not comparable to city counts).

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 well-structured: purpose and routing first, then return shape, then constraints. All sentences carry information, though the return-shape detail is somewhat redundant given the tool has an 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?

For a read-only ranking tool with a full output schema and 100% parameter coverage, the description covers routing, data caveats, and result interpretation (ranking_url to hand to the user, non-comparable powiat counts). Nothing an agent needs to call and present 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 sort, level, limit and min_transactions; the description's parameter value is mostly reinforcement plus practical guidance (e.g., set min_transactions≈50 when sorting by price, don't raise limit unnecessarily). It adds some real advice beyond the schema but does not carry the primary burden.

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+resource: ranking of Polish towns (level=city) or powiatów by RCN transactions, with metrics (transaction count, price per m²). It explicitly distinguishes itself from get_transaction_statistics (single-city trend) and search_offers (offer prices), so an agent can route 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?

Explicit when-to-use: comparing many cities (most transactions, most expensive, cheapest) → this tool; single city over time → get_transaction_statistics; developer offer prices → search_offers. It also gives a concrete usage rule (supply min_transactions ~50 when sorting cities by price).

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 only declare readOnlyHint and openWorldHint; the description goes far beyond by disclosing the 20-page cap, the truncated flag semantics with remediation ('zawęź filtry zamiast przeglądać kolejne strony'), the truncated-items behavior, and the list_url reuse. This is rich behavioral context an agent could not infer.

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?

Long but dense and clearly front-loaded: purpose, filters, return shape, then limits. Every paragraph carries distinct information (filter set, return fields, pagination cap, alternatives), though it is near the upper bound of useful length for a 13-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?

For a complex paginated search with an output schema, the description still explains the return envelope, the truncated hint, the 20-page limit, and the correct fallbacks to sibling tools. Nothing an agent needs to call it correctly or handle its edge cases 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 the baseline is 3, but the description adds meaning beyond it: the offer-price vs transaction-price framing, the city=polska sentinel, the district-only-with-matching-city constraint, and the fact that rooms/floor are unsupported. These context notes are genuinely additive over the schema field descriptions.

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?

Starts with a specific verb+resource ('Wyszukuje oferty mieszkań od deweloperów') and immediately scopes it (tylko rynek pierwotny, ceny ofertowe, nie transakcyjne). It also names sibling tools for adjacent tasks, so an agent can distinguish it from get_offer, get_investment and get_market_statistics 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?

Explicitly states what it does NOT filter by (liczba pokoi, piętro, deweloper) and routes each unsupported case to the correct alternative (get_developer, get_investment, get_market_statistics). It also gives the polska-vs-city selection rule and the truncated=true workflow, leaving nothing to inference.

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