Gratka MCP

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

With no annotations, the description carries the full burden and does so: it discloses the live upstream fetch and typical latency (<1s), the presence of a 5-minute cache, data-suppression behaviors ("No phone numbers", private owners unnamed), and the `note` field signaling an inactive listing. That is exactly the mutation/return behavior an agent cannot infer from 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?

Purpose is front-loaded in the first clause and the long field enumeration is doing real work because there is no output schema. It is dense and readable, though the field list borders on exhaustive where a shorter summary of the return shape would suffice.

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?

Two-parameter read tool with no annotations and no output schema; the description compensates by spelling out the full result envelope including the optional `note` and its meaning. Nothing an agent needs to invoke or interpret the response 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 already 100% with both parameters documented, so baseline 3 applies; the description adds a bit by reinforcing that `id` comes from gratka_search. It does not explain `no_cache` beyond what the schema says, so it earns only a modest bump.

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 ("Full details of one Gratka.pl listing") and enumerates exactly which fields come back, which cleanly separates it from the sibling gratka_search. An agent can tell this is the detail-fetch step, not the search step, 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?

"Get the id from gratka_search" explicitly sequences this tool after the search sibling, which is the key routing decision. It does not state exclusions (e.g. when morizon_offer would be preferred instead), so it stops short of full when/when-not coverage.

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

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

With zero annotations the description carries the full burden and does so: live fetch from Gratka.pl's own API with typical sub-second latency, a 5-minute server cache, one results page of up to 35 listings, null-valued fields when omitted, price in PLN (monthly for rent), and area in m². It also discloses the meaning of `kind`, `seller_type`, `total_count` versus `page`, and what `resolved_location` represents.

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 routing before the long result-shape block, and every clause is informational. It is on the long side, with the listing field list appearing both in the shape summary and again in a per-field enumeration that partly duplicates the existing 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 14-parameter, annotation-free search tool this covers everything an agent needs: what is searched, how to route elsewhere, page size and pagination, units, caching, empty-result handling, and field semantics. The return-value detail is technically redundant with the output schema but adds interpretive value rather than noise.

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 beyond it by tying units and interpretation to transaction type ('prices are numbers in PLN, for rent `price` is the monthly rent'), clarifying that prices/areas are numeric, and explaining that `location` is resolved by the site's own matcher and surfaces as `resolved_location`. It does not, however, restate the enum semantics for `type`, `sort` or `market`, which the schema already handles.

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

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

States a specific verb and resource ('Search property listings on Gratka.pl'), enumerates the property types and transaction modes covered, and names the sibling it hands off to (gratka_offer) as well as the portal it deliberately duplicates (Morizon.pl). An agent can distinguish it from morizon_search and gratka_offer 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 explicit routing: pass a listing `id` to gratka_offer for full details, use gratka_offer only with Gratka.pl ids, and 'search one portal, not both' because Gratka.pl and Morizon.pl expose identical inventory. It also states that an empty match is a successful result rather than an error, which prevents a common misreaction.

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 no annotations, the description carries the burden well: it discloses that private owner names and phone numbers are omitted, that data is fetched live from Morizon's API in under a second, and that a `note` is set when a listing is inactive. Auth and rate-limit behavior are not mentioned, keeping it short of a 5.

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

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

Front-loaded with the resource and field inventory, then prerequisites and return shape. The field enumeration is dense but each item is informative rather than filler.

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

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

There is no output schema, and the description fully spells out the result envelope including the optional `note` field, so an agent knows exactly what it will receive and what edge cases to expect.

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 the id's provenance (from morizon_search, or a full link per the schema) and explains the practical meaning of staleness for the inactive-listing case.

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 ('Full details of one Morizon.pl listing') and enumerates the actual fields returned, so it is immediately distinguishable from morizon_search and the gratka siblings.

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

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

Explicitly routes the agent to morizon_search to obtain the id, which is the key prerequisite. It gives clear positive context but does not state exclusions or contrast against gratka_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?

With no annotations, the description carries the full burden and does so: live API fetch with typical latency, a 5-minute server-side cache (echoed in no_cache), null-field semantics, seller_type/kind enumerations, and empty-result behavior. It also explains pagination limits (35/page, total_count across pages).

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 and information-dense, but the long block enumerating every field of the result object and each listing is largely redundant with the output schema and adds bulk without adding decision-relevant guidance. The core routing advice is buried mid-paragraph rather than split out.

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?

Excellent coverage for a 14-parameter search tool: the agent knows what it will get back, how pagination works, how empty results appear, and how this tool relates to both siblings. No material gap remains.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description adds modest extra meaning (rent prices are monthly, prices in PLN, area in m², sorts 'like the site') but largely restates the filter list already in the schema, so it stays close to the baseline.

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

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

Specific verb+resource ('Search property listings on Morizon.pl') plus an enumerated set of property types, transactions and filters. It also explicitly distinguishes itself from siblings by telling the agent to search one portal only and to pair it with morizon_offer rather than gratka_search.

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

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

Explicit routing: 'Morizon.pl shows the same listings as Gratka.pl ... search one portal, not both, and use morizon_offer only with Morizon.pl ids.' It also clarifies that count: 0 with a note is a success, not an error, so the agent knows not to retry or treat it as a failure.

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