Nieruchomosci Online 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 well: it discloses that data is fetched live, gives realistic timing (1–3 s normally, up to ~20 s with an unblocker fallback), and notes the 5-minute result cache via no_cache in the schema. It omits error/failure behavior and any rate-limit or auth expectations.

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

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

Front-loads the purpose, then the id source, then fetch behavior and result shape — a logical order with no filler sentences. The result-field enumeration is long but earns its place since there is no output schema.

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

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

With no output schema and no annotations, the description compensates fully: it describes the exact result envelope and field list, the data source, and expected latency. An agent has everything needed to call and interpret it.

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 both parameters are already documented, including the id-or-URL forms and the cache bypass. The description's 'Get the id from nieruchomosci_online_search' duplicates what the schema already states, adding little beyond 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?

States a specific verb and resource ('Full details of one nieruchomosci-online.pl listing') and immediately enumerates the concrete fields returned, so the agent knows exactly what this retrieves. It is clearly the single-record counterpart to the sibling search tool.

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 nieruchomosci_online_search' explicitly routes the agent to the sibling for the prerequisite, which is the key usage decision. It does not spell out when-not-to-use (e.g. use search for browsing), but the single-listing scope is unambiguous.

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-fetch latency (1–3 s, up to ~20 s on unblocker fallback), null handling for omitted page fields, currency/unit semantics (PLN, monthly rent, m²), and the meaning of `kind` and `seller_type`. The empty-result contract is a genuinely useful behavioral 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 purpose and sibling routing before details, and every section is information-dense. The long result-shape dump partially duplicates the existing output schema, which is the main cost.

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 tool with no annotations, the description supplies latency, caching behavior, null semantics, empty-result handling, pagination and sibling routing. With an output schema present, the description does not need to explain return values further, so 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 baseline is 3; the description still adds real meaning beyond the schema by stating prices are PLN numbers with rent being monthly, area in m², and by enumerating seller_type values. It does not restate the region/location exclusivity or room-type constraints itself, so it is additive but not exhaustive.

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 (search), a named source (nieruchomosci-online.pl), and the covered property types, transactions and filters. It also explicitly delimits itself from its only sibling, nieruchomosci_online_offer, which handles full details.

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 pass a listing `id` to nieruchomosci_online_offer for full details, tells the agent to use `page` when more results are needed, and clarifies that an empty match with a `note` is a successful result rather than an error. That is concrete when-to-use / what-happens guidance.

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