Tatry Planer

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false and openWorldHint=false, so safety and side effects need no restatement. The description instead adds two things annotations cannot: results are timestamped with a source, and — critically — "Brak komunikatu nie znaczy, że szlak jest bezpieczny," which tells the agent how to interpret an empty result rather than presenting it as a safety clearance.

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 sentences, each earning its place: what is returned and from where, when to call it, and the safety caveat on empty results. The most decision-relevant material (scope and sources) is front-loaded.

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, single-optional-enum lookup with no output schema, the description is nearly sufficient: it conveys the data sources, the presence of a status date and source per item, and the empty-result caveat. The only gap is the unaddressed default behavior of kraj and any hint about result volume or freshness window.

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?

Coverage is 0% for the single optional parameter kraj, and the description never mentions it, so the schema's enum values (Polska/Słowacja) do the work. The enum is self-explanatory, but the description leaves open what happens when kraj is omitted (both countries returned?) — a real ambiguity for a filter parameter that is not required.

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 concrete resource (current park notices on closed trails and obstacles) and enumerates the actual sources covered — live TPN, seasonal TANAP/TPN closures, Slovak HZS entries — plus the fact that each item carries a status date and source. That is far more specific than the sibling tools (szukaj_tras, trasa, wyznacz_trase), which all deal with route search/planning, so an agent can separate this from them by subject alone.

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?

"Użyj, gdy ktoś pyta, czy szlak jest otwarty albo co jest zamknięte" gives an explicit triggering question type, which is exactly the routing signal an agent needs. It stops short of 5 because it names no alternative tool or negative case (e.g., what to use when the user wants route options rather than closure status).

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 read-only, idempotent, non-destructive behavior, but the description adds useful context beyond them: the catalog size, the maximum of 10 returned routes, and the important semantic caveat that czas_max_h includes the approach to the shelter. It does not disclose result ordering or behavior when no routes match.

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 description is three tightly written sentences with no redundant restatement of the title or schema. Purpose and usage are front-loaded, followed by the key time caveat and return behavior.

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, the description appropriately mentions that up to 10 routes are returned with ready times and links. It covers the main behavioral and semantic gaps for a search tool, though it could say more about ranking or empty-result behavior.

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 63%, and the description compensates with a critical clarification for czas_max_h: it counts total time including the approach to the shelter, which is not stated in the schema. It also reinforces the return limit, though many of the eight parameters are left to 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?

The description uses a specific verb and resource ('Szuka tras w katalogu Tatry Planer') and scopes the catalog to 145 routes in Poland and Slovakia. It is clear what the tool does, but it does not explicitly differentiate itself from siblings such as wyznacz_trase or trasa.

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 clearly states when to use the tool: when someone asks for a trip proposal, with concrete examples like 'na 4 godziny z dzieckiem' and 'łatwy szczyt bez łańcuchów'. It does not mention when not to use it or name alternative sibling tools.

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 the safety profile (read-only, idempotent, non-destructive, closed-world), so the bar is lower. The description does add one useful behavioral trait, that safety notes are date-dependent, implying results vary over time, but it says nothing about behavior on unknown slugs or how name/slug conflicts are resolved.

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?

A single sentence with no filler, front-loading the tool's scope before the parameter guidance. The long parenthetical content list makes it dense and slightly harder to scan, but nothing 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?

With no output schema, the description usefully enumerates what comes back, including the conditional safety notes and links. It is nearly complete for a simple read tool; only lookup failure / disambiguation behavior is left implicit.

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 both parameters already carry examples and the 'from szukaj_tras' origin note. The description's parameter guidance largely restates the schema, adding only the loose precedence hint of slug-first, name-as-fallback.

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 ('Pełny opis jednej trasy z katalogu') and then enumerates the returned content (numbers, time with approach, stage-by-stage course, description, safety notes, links), which clearly separates it from the sibling tools that only search (szukaj_tras) or compute routes (wyznacz_trase).

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 tells the agent where to get the identifier ('Podaj slug z szukaj_tras') and gives a fallback ('albo nazwę celu'), effectively chaining this tool after the search tool. It stops short of stating when not to use it or what happens with ambiguous names.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description adds real value beyond that by listing the computed outputs and their structure (breakdown of outbound/return/total time, cumulative-time track, planner link). It also discloses a naming constraint (Polish or Slovak names), though it says nothing about failure behaviour for unrecognized place names.

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 sentences: the core action and return payload first, then the usage rule, then the naming caveat. The output enumeration is dense but every item is distinct information an agent can use; nothing is redundant with the schema or title.

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?

No output schema exists, yet the description compensates by enumerating the returned fields. Together with the usage rule, the example, the language constraint and the schema's 2–8 point bounds, an agent has everything needed to invoke the tool 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?

With 100% schema coverage the baseline is 3, and the description goes beyond the schema by noting that point names may be Polish or Slovak — information the schema does not contain and that directly affects how the `punkty` array must be filled. It adds nothing for `z_powrotem`, but that parameter is already self-documenting with a default.

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: computes an arbitrary route along marked trails through the given points, and enumerates what it returns (km, elevation gain, outbound/return/total times, cumulative-time track, planner link). The phrase „połączeń spoza katalogu” implicitly sets it apart from the catalog-based sibling szukaj_tras, so an agent can choose between them 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?

Explicitly says when to use it — for connections outside the catalog — and gives a concrete example („z Kuźnic przez Zawrat na Kozi Wierch”), which is exactly the selection cue an agent needs. It stops short of naming szukaj_tras as the alternative for catalogued routes, so the exclusion is implied rather than stated.

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