peaks.fyi — Mountain Routes, Huts & Weather

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful behavioral context: the result is a citable text document covering routes, season, access, hazards, huts, notices, and provenance, and it is not an external web fetch.

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 definition is front-loaded with the core action, then adds a concrete example, scope clarification, content summary, and sibling routing. Each sentence contributes useful information with no wasted framing.

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 one required parameter, full schema coverage, annotations covering safety semantics, and an output schema present, the description is complete enough for correct invocation. It clarifies the document scope and points weather queries elsewhere.

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 the id as a peak slug from search. The description adds an explicit example input, reinforcing slug usage beyond the schema's pattern and description.

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: read a peak search result by catalogue slug as a citable text document. It also distinguishes the tool from external URL fetching and from weather lookup, so an agent can identify its role 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?

Gives clear usage context by saying this retrieves catalogue documents rather than publisher pages, and explicitly routes weather queries to get_weather. It does not compare against other sibling retrieval tools such as get_peak, but the intended usage is otherwise clear.

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 open-world behaviour, so the safety profile needs no restating. The description adds context annotations cannot: that the payload includes unsupported operations, units and a data version, plus the caveat that missing data is not proof of absence — a genuine interpretive constraint for the agent.

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?

Two sentences, no filler, with the action and its scope front-loaded and the interpretive caveat placed last where it functions as a closing rule. Every clause carries 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?

With an output schema present and rich annotations, the description only needs to say what the tool is for and when to reach for it, which it does. A slightly clearer statement that it is the entry-point discovery call for an otherwise unknown catalogue would close the remaining gap.

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?

There are zero parameters, so the baseline applies; nothing about argument semantics needs explaining. The description does not waste space discussing inputs, which is correct here.

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 verb 'Inspect' is paired with a concrete list of what is reported: catalogue coverage, output JSON schemas, data version, units and unsupported operations. That clearly separates it from the data-fetching siblings (fetch, get_route, search, etc.), though the resource itself ('capabilities') is implied rather than stated outright.

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?

'before planning' gives real timing guidance for when to call this rather than a data tool, and the closing caution steers how to interpret gaps in results. It does not name an explicit alternative or a when-not-to-use condition, which keeps it short of a 5.

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, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely valuable non-obvious semantics: the false-negative risk of an empty change set and that notice status is date-dependent and out of scope. It doesn't cover rate limits or result size limits, keeping it below 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?

Three front-loaded sentences: purpose first, return values second, caveats last. Every sentence carries distinct information and there is no 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?

Output schema exists and annotations are rich, so the description only needs to add the interpretive caveats it does add (empty result semantics, notice-status gap). For a two-parameter polling tool this is sufficient to call it 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 description coverage is 0%, so the description carries the burden, but the object-level schema description (not the description text) is what actually explains 'previous' as the preceding snapshot and empty-list-as-baseline. The description only alludes to 'watched set of peaks' and 'previous snapshot', leaving slug format and the baseline mechanics 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?

States a specific operation (compare a watched set of peaks against a previous snapshot) and the outputs (content changes, removals, updated snapshot). It is distinguishable from siblings like get_peak or search_peaks by its diff/stateful nature, though it never names a sibling explicitly.

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 for when to use it (polling a watch list for changes) and a strong when-not caveat: 'No changes means no new source data, not proof that conditions are unchanged. Date-dependent notice status must still be checked.' That implicitly routes the agent to get_notices, though it doesn't name that tool.

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, idempotent and open-world, so the bar is lower; the description still adds real value by disclosing DST handling via UTC instants, polar day/night edge cases, and the caveat that values are geometric and ignore terrain and weather. It does not say what happens for out-of-catalogue slugs or how polar cases are represented in the output.

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 short sentences, front-loaded with verb and resource, then edge-case behavior, then a caveat. No filler and nothing repeated from the schema or annotations.

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 no explanation, and annotations carry the safety profile; the description covers the notable behavioral edge cases (DST, polar days). The one gap is that it never explains that the required slug supplies the location, which is essential to interpreting a sunrise/sunset result.

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 67% and the schema already documents slug and timeZone well, so baseline 3 applies. The description clarifies the date semantics ('exact calendar date') and zone behavior (defaults handled via UTC) but never mentions the required slug or that the observation point comes from a peak, leaving the most important parameter implicit.

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 plus the precise outputs: 'Compute sunrise, sunset and civil twilight for the exact calendar date and IANA zone.' This clearly separates it from get_weather and the search/get_* siblings. It stops short of naming an alternative tool explicitly, so it is a 4 rather than a 5.

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?

Usage is implied by the domain (ask for daylight at a peak on a date) and the closing line hints that weather/terrain are separate concerns, but there is no explicit 'use this when' or 'use get_weather instead for X' routing. Nothing misleading, just no guidance for choosing between daylight and weather lookups.

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?

Beyond the read-only annotation, it discloses critical data semantics: beds are capacity not vacancies, live availability/reservations/rental inventory/current opening status are unknown, and next year's dates must not be inferred. This meaningfully prevents misuse of the returned data.

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?

Four tightly written sentences, each carrying distinct value: scope, field contents, bed semantics, and explicit data limitations. No filler, and the core purpose 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?

Annotations cover safety and idempotency, an output schema exists, and the description covers the most important caveats about data limitations. The remaining gap is parameter-level explanation, particularly hutId and how date interacts with the returned seasons.

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?

The description does not mention any parameter names or clarify the roles of slug, hutId, or date. Schema coverage is 67%, with hutId having no description at all, and the description does nothing to compensate for that gap beyond the vague phrase 'for a peak'.

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 – 'Read huts' – scoped to a peak, and enumerates what is returned (documented seasonal operation, source years, booking/contact URLs). An agent can distinguish this from sibling tools like get_peak, get_route, and get_weather 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?

Usage context is implied: planning huts for a peak. The description explicitly rules out treating the data as live availability or current opening status, but it does not name an alternative tool for live availability or reservations, leaving the agent to infer routing.

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?

Beyond the annotations, the description adds important behavioral context: omitted dates default to today's UTC date and are echoed in requestedDate, expired notices may still describe recurring regulations, and expiry is not evidence that access is open. It also directs the caller to verify current law with the linked source, which is valuable interpretation guidance for a read-only, open-world data tool.

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 compact and front-loaded with the core purpose, followed by invocation details and cautionary notes. The phrase 'explicit scope uncertainty and recurrence hints' is slightly opaque, but the text is appropriately sized for the 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?

Given the read-only annotations and existing output schema, the description covers the essential behavior, default date handling, expired-notice caveat, and verification requirement. It is only slightly incomplete because it does not explain the routeId parameter or clarify the relationship between notices and routes/peaks.

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 67%, and the schema already explains the date default and slug meaning. The description reinforces the slug and date usage but does not mention the routeId parameter at all, leaving a clear parameter-semantics gap.

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 clearly states a specific verb and resource: reading dated notices, including publication validity, scope uncertainty, and recurrence hints. It is distinguishable from the sibling tools by its focus on notices rather than routes, weather, or huts, though it does not explicitly name those alternatives.

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 implies usage by saying to supply slug and trip date, and warns to verify current law with the linked source. However, it does not explicitly say when to choose get_notices over related tools such as get_route or get_weather, nor does it state when not to use it.

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, so the safety profile is covered. The description adds real behavioral context beyond them: default output is a compact overview plus route IDs and notices, and 'Research is not live availability' warns that data may be stale — a meaningful caveat an agent would otherwise miss.

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?

Four short sentences, front-loaded with purpose, then example, then optional sections, then sibling routing. Nothing is redundant and every sentence carries information the agent acts on.

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 present and annotations covering safety, the description supplies what remains: default vs optional sections, data-freshness caveat, and alternative tools. The one gap is not explaining how to obtain a slug (resolve_peak) beyond 'returned by search'.

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 sections enum plus its 'omit for compact overview' default are fully documented in the schema. The description's only addition is a concrete example input, which illustrates the slug format but does not extend meaning beyond 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?

States a specific verb and resource ('Get compact peak facts and route IDs') and immediately scopes it against siblings by naming get_weather and get_huts. An agent can distinguish this from search_peaks/get_route 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?

Explicitly routes three alternatives: search for fact questions, get_weather for current weather, get_huts for booking info — a genuine when-to-use/when-not set. It omits the resolve_peak vs get_peak distinction, even though resolve_peak is the likely source of the required slug, leaving one sibling relationship 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?

Annotations only cover read-only/idempotent/openWorld; the description adds real data-quality context the annotations cannot: failed, truncated or outline geometry must not be used for navigation, times are estimates, and there is no live safety or opening guarantee. For a mountain-route tool these caveats materially change how an agent should present the output.

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 verb, resource, and identifier source, then the field list, then caveats. It is dense but every clause adds signal; the only mild clutter is the semi-colon-free field enumeration that runs long.

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?

Output schema exists, so return-value explanation is not required, yet the description still previews the payload and covers the safety caveats well. The gap is includeDescription's effect on the response, which nothing in the definition explains.

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 67%, and the description's only parameter-related contribution is noting that routeId originates from get_peak, which the schema already says. The third parameter, includeDescription, is left undocumented in both the schema and the description and is never explained.

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 (get one route), the exact identifiers needed (peak slug + routeId), and enumerates the payload (grade, equipment, key passages, stages, trailhead, timing, confidence, geometry QA). That field list makes it clearly distinguishable from siblings like get_route_briefs and get_route_point.

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 that routeId comes from get_peak, which routes the caller to the right upstream tool, but it never states when to prefer this over get_route_briefs, get_route_point, or search_routes, nor any exclusions. Usage is implied rather than declared.

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 readOnly/idempotent/destructive/openWorld, yet the description adds real context beyond them: per-route errors and source provenance are preserved, partial results must not be treated as complete, and there is no booking, live-transport or suitability guarantee. These caveats materially shape how an agent should interpret and act on the output.

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 follow-on sentences carry routing and caveats rather than filler. The section enumeration overlaps with the schema enum, but it still reads efficiently rather than padded.

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 present, return-shape detail is not required, and the description still covers scope, input constraints, sibling routing, and interpretation caveats including partial results. 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 only 33%, but the description compensates by naming the sections (equipment, huts, access, notices, daylight) and flagging that daylight is 'dated' (the date parameter), plus the six-route cap. It does not explain the slug/routeId pair format, which the nested schema does cover.

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 (compare) and resource (up to six routes), and enumerates the packet contents — grade, timing conflicts, equipment, huts, access, notices, daylight. It explicitly distinguishes itself from get_route (full details) and get_weather (forecasts), so an agent can route without inspecting schemas.

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?

Names both alternatives and the condition that selects them: batch comparison lives here, full detail in get_route, forecasts in get_weather. The 'up to six known routes' framing plus the schema note about slug/routeId pairs from search_routes tells the agent exactly what input is acceptable.

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/openWorld, so the description is free to add real value: it warns that missing coordinates or conditions 'remain unknown' (partial results are possible), which is non-obvious and prevents false conclusions. The scope caveat about not being live navigation guidance adds further context. It doesn't state how complete a typical result is or whether misses return an error versus an empty result.

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: purpose first, then return contents, then caveats. No filler or redundancy. Slightly list-like in the middle sentence, but every clause carries 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?

With an output schema present, the description needn't spell out return structure, and it still previews the return categories usefully. For a read-only, three-param lookup, the main remaining gap is telling the agent that slug/routeId likely come from search_peaks/search_routes beforehand.

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 67%, with slug and query documented but routeId left bare. The description adds no parameter-level guidance — it doesn't clarify that query is a free-text name match or how slug, routeId and query interact (e.g., whether all three must agree). Baseline 3 for mid coverage with no compensating detail.

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: 'look up a named waypoint or difficult passage on a route', and enumerates what comes back. Clearly narrower in scope than a whole-route tool like get_route, though it never names that sibling to sharpen the contrast.

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?

Usage is implied by 'named waypoint or difficult passage' and the exclusion 'this is not live navigation guidance' sets a domain boundary. However, no tool-level alternative is named (e.g., use get_route for the full route overview, search_routes to find a routeId first), so the agent must infer when this is the wrong call.

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, idempotentHint, openWorldHint and destructiveHint=false, so safety and idempotency are covered. The description adds genuinely useful behavior beyond that: stale records are marked, expired/missing/far-future data is unavailable, point samples are distinct from accumulated intervals and window totals, and coverage gaps should be checked. That is solid added context, though it remains telegraphic about what a partially-covered response actually looks like.

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 and free of filler; nearly every clause carries operational meaning. It is somewhat dense and telegraphic in places ('Stale is marked; expired, missing and far-future data is unavailable'), and the output-semantics sentence sits awkwardly between parameter guidance.

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 present, return-value detail is unnecessary, and the description still covers staleness, unavailability windows, coverage checking, and the sibling alternative. An agent has everything needed to choose this tool and call it 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 description coverage is 100%, so the schema already defines slug format, ISO 8601 start/end with exclusive end, view enum, and targetId omission semantics. The description reinforces the intent of start/end and targetId (bounding the response, all-targets default) but adds no syntax or format detail beyond the schema, 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 and resource ('Get published weather for a peak') plus the optional target scope (summit/hut/trailhead), which no sibling provides. It also differentiates itself from get_peak by naming that tool for long-range planning.

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 set targetId and start/end for a bounded planning response and warns that unfiltered forecasts are large, which tells the agent when to narrow. It names a concrete alternative ('For a trip months away use get_peak seasons instead') and adds a prohibition against inventing forecasts or safety verdicts.

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, openWorld and non-destructive, so the safety profile is covered. The description adds value by disclosing the returned artifacts (current slug plus citable URL) and the rename-recovery behavior, which annotations do not convey.

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 short sentences, front-loaded with purpose, followed by the recovery guidance and an inline example. Every element is relevant; the inline JSON example is slightly redundant with the schema but aids quick invocation.

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 one required parameter, rich annotations, and an output schema covering return values, the description gives enough to call it correctly. It does not need to explain the response format further; only explicit sibling routing 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 param description already enumerates canonical peak:id, Wikidata Q ID, OSM ID, slug and translated name. The description reinforces this list and adds a concrete example, so it adds modest but real meaning beyond 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 states a specific verb (resolve) and resource (peak), and enumerates accepted identifier forms plus what it returns: current slug and citable URL. This clearly distinguishes it from get_peak or search_peaks in spirit, though it never names those siblings explicitly.

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 a concrete usage scenario — 'Use canonical IDs to recover from renamed slugs' — and an example invocation, which tells the agent when this applies. It stops short of naming alternatives or stating exclusions, which keeps it below a 5.

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 (readOnly, idempotent, non-destructive, openWorld), so the description only needs to add context — and it does, disclosing the return shape (citable peak IDs and URLs) and the semantics of an empty result set. It stops short of noting result-count limits or ranking behavior, which keeps it at 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?

Three tight sentences: capability first, then sibling routing, then the empty-result caveat. Every sentence carries distinct information and nothing is repeated.

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 one-parameter search tool with an output schema and rich annotations, the description supplies everything an agent needs: what to put in, what comes out, which sibling to prefer, and how to read a null result.

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?

The single query parameter is fully documented in the schema (100% coverage), including length bounds and an example. The description restates the same facets in near-identical wording, adding only the slightly broader 'climbing request' framing, so the schema is doing 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 (search) and resource (peaks.fyi catalogue) plus the accepted query facets: name, alternative name, country, range, or free-form climbing request. It also names what comes back (citable peak IDs and URLs), which lets an agent distinguish it from fetch and search_peaks 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 routes the agent: use fetch to read a result, use search_peaks for explicit filters and pagination. It also pre-empts a common misinterpretation by stating that an empty result means no match in this catalogue, not that the mountain does not exist — a real when-not-to-conclude rule.

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?

The annotations already establish a safe, idempotent, open-world read, so the description's job is to add context, and it does: hard-constraint semantics, the shape of the return (compact summaries, IDs, total, nextOffset), and the important caveat that peak-level filters can describe different routes. It stops short of covering result ordering or what 'compact' omits, so it is strong but not exhaustive.

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: capability first, constraint semantics second, workflow caveat last. No filler, and the most decision-relevant clause (filters are hard constraints) is up front.

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 spelled out, yet the description still flags total and nextOffset, which is helpful for pagination. For an 11-parameter search tool with nested bbox/near objects, the only real gap is the absence of any guidance on combining geographic filters with the free-text query.

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 55%, so the description needs to compensate, and it does by naming the filter families (country, elevation, season, difficulty, glacier) and by adding semantics the schema cannot express — that these are hard constraints and that difficulty/elevation are peak-level, not route-level. It is silent on bbox, near, and the query string beyond the family list, but those parameters carry their own schema 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?

A concrete verb ('find and compare') plus the resource ('mountains') and a list of the filter dimensions it supports, so the agent knows exactly what it gets. It also names get_peak and get_route as downstream steps, which partially distinguishes it from siblings, but it never explicitly contrasts itself with search or search_routes, leaving the nearest alternatives ambiguous.

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 operating context: all filters are hard constraints and are never silently relaxed, and the agent is told to read get_peak and get_route before recommending a route. That is real routing guidance, though it stops short of stating when this tool should be preferred over search_routes or resolve_peak.

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 the description still adds substantial non-obvious behavior: unknown glacier status is excluded by glacier filters, coordinates constrain peaks rather than trailheads, transport matches documented prose rather than confirmed operation, and historical season text is not a current operating confirmation. These are exactly the caveats an agent needs to avoid over-claiming 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?

Purpose and the 'SAME route' constraint are front-loaded, followed by pagination and scope caveats in a sensible order. It is dense and slightly run-on by the end ('Historical season and public transport descriptions are not current operating confirmations' repeats the transport caveat), but nearly every sentence carries distinct 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?

For a 12-param open-world search with an output schema (so return shape needn't be described), the definition covers pagination, filter semantics, and the key trust caveats about transport and season data. Missing pieces are minor: no guidance on how month or query interact with results, and no note on default limit 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?

With only 25% schema coverage across 12 params, the description carries real weight and does so for the tricky ones: glacier unknown-exclusion semantics, bbox/near applying to peaks not trailheads, publicTransport meaning documented-not-confirmed, computed round-trip hours, and cursor via nextCursor. Opaque params like month, query, countries, and maxDifficulty get no added meaning, leaving gaps, but the highest-risk semantics are covered.

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: 'Find routes satisfying all supplied constraints on the SAME route', and immediately enumerates the filterable dimensions (difficulty, glacier travel, style, round-trip hours). It implicitly differentiates from search_peaks by scoping to routes, though it never names a sibling tool explicitly, and 'Searches all candidate peaks' slightly muddies the object of the 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?

Gives concrete operational guidance: 'use nextCursor until null for complete results' and 'Read route details and conflicts before recommending', which routes the agent to get_route afterwards. It also flags scope traps ('Coordinates filter peak locations, not trailheads'). It stops short of explicitly contrasting when to use this versus search or search_peaks, so no exclusions of alternatives are stated.

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