Noclegi 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 latency (~1s direct, up to ~20s via unblocker), null prices with an availability_note when dates are unbookable, cache behavior via no_cache, and the site limitation that no phone/email is published. Prices are stated as PLN inclusive of taxes and fees.

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 the dated/undated distinction are front-loaded, and the long result-shape block is justified given there is no output schema. The opening sentence is overloaded with a long enumeration, which costs some readability, but no sentence is truly 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?

A six-parameter tool with no output schema and no annotations needs exactly this: return shape, failure semantics, pricing conventions, latency, and freshness controls. All are present, so an agent can call it and interpret the response without guessing.

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: it explains what dates unlock (total price of cheapest combination, booking link), what price_from means when dates are omitted, and that rates are per room type for the given guests. The interaction between date params and refunded fields is not spelled out further, keeping it just above 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 place to stay on noclegi.pl' — and enumerates the content returned (description, address, reviews, rooms, rates). This clearly distinguishes it from noclegi_search, which returns a list rather than a single property.

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 explains the dated vs undated modes ('With checkin/checkout it also returns... without dates, `price_from` is...') and the sold-out failure mode. It stops short of explicitly naming noclegi_search as the way to obtain the slug, leaving that routing implicit rather than stated as an alternative.

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 fully carries the burden: it discloses live-fetch latency (~1 s, up to ~20 s on unblocker fallback), caching, sold-out offers returning price null/available false, radius widening when a place is thin, and why an empty match returns a note. That is exactly the operational context an agent needs before calling.

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 purpose and filtering/sorting, but then spends a large block restating the full result object and per-listing fields, which duplicates the output schema. Useful content, but the payload is oversized and the return-shape enumeration does not earn its tokens.

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 search tool with no annotations, the description covers price semantics, date constraints, pagination, fallback behavior, and edge-case results. Nothing an agent needs to call it correctly is missing, even if some of the return-shape detail overlaps 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%, so baseline is 3, but the description adds the crucial cross-parameter semantics: prices are totals only when dates are supplied, otherwise indicative 1-night values; the `price_for` string and the `note` reflect which mode applies. It reinforces but does not go far beyond the schema's own per-param docs.

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) plus resource (places to stay on noclegi.pl) and enumerates the covered property categories. It also distinguishes itself from the sibling noclegi_object by declaring that tool as the follow-up for rooms/rate plans/amenities.

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: use this for discovery, then pass a listing's `slug` to noclegi_object. It also tells the agent when to supply checkin/checkout (to get a real stay quote), to use `page` for more results, and that a count:0 answer is a successful result rather than an error.

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