Skamper

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description earns credit for adding behavioral context beyond that: it discloses the content mix returned (editorial picks plus most recent public user-created lists), which tells the agent what data to expect. It stops short of describing ordering or pagination behavior.

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 tight sentences with zero filler. The resource definition and example are front-loaded, followed by the routing pointer to get_runlist, which is the natural reading order.

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 simple read-only browse tool with no output schema, the description covers what is returned and where to go next, which is most of what an agent needs. The remaining gap is the limit parameter, whose range and defaulting behavior (max 20, default 10) are only inferable from the 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 description coverage is 0%, so the description carries the burden for both parameters. It implicitly explains the 'kind' selection by saying results include editorial picks and recent user lists, which maps to featured/recent/both, but it says nothing about the 'limit' parameter's effect, cap, or default behavior.

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?

Uses a specific verb ('Browse') plus a named resource ('Skamper run lists') and clarifies what the resource is with a concrete example ('Best UK trail half-marathons'). It also explicitly separates this tool from the sibling get_runlist, which drills into a single list, so an agent can pick between them 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 clear when-to-use context (browsing curated collections and recent public lists) and names the follow-up alternative, get_runlist, for inspecting routes inside a list. It does not state any exclusion or when-not condition, so it stops just short of full routing guidance.

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 and openWorldHint=false, so the safety profile is covered. The description adds that results are the *nearest* routes constrained to a 4.5–5.5 km band, implying distance ordering, but says nothing about what happens when no route qualifies or how the default result count behaves. Useful context, but thin beyond what annotations provide.

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 the core scope and the numeric band before the example phrasing. The closing 'a 5k near me' line largely echoes the tool title, so it is slightly redundant but still reinforces intent cheaply.

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 only 4 flat parameters and no output schema, the description needs to convey the search scope and result character; it does both by naming the 4.5–5.5 km band and the 'nearest' ordering. Missing detail on empty-result behavior and the limit default keeps it just short of complete.

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 75% — lat, lng and max_distance_from_user_km are already documented in the schema. The description adds the 4.5–5.5 km filtering semantics that no parameter declares, but leaves 'limit' (default 8, max 15) entirely unexplained. Baseline 3 is appropriate given the schema does most of the work.

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 gives a specific verb and resource ('Find Skamper running routes') plus a precise scope: routes 'close to 5 km (parkrun distance)' and 'between 4.5 and 5.5 km'. That tolerance band alone separates it from generic siblings like search_routes or browse_runlists without needing them named.

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 supplies a concrete use context — 'Great for runners asking "a 5k near me"' — which tells the agent when this specialized tool beats a general route search. It stops short of naming an alternative or stating when not to use it (e.g. for 10k or arbitrary distances), so it is clear context without exclusions.

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 that this is a read-only, idempotent, non-open-world operation. The description adds useful behavioral context beyond that, including the returned fields and the requirement of a free Skamper account to download the GPX file.

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 front-loaded with the core action and identifier, followed by return contents and a relevant caveat. Every sentence contributes useful information without redundant wording.

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 simple one-parameter read tool with no output schema, the description is sufficiently complete. It explains what is returned and includes the account requirement for GPX download, which an agent may need to surface to a user.

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%, and the schema already documents the slug parameter with examples. The description only restates that lookup is by slug and adds no meaningful syntax or constraint 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 and resource: fetching full details for a single Skamper route by slug. The word 'single' and the slug-based lookup clearly distinguish it from sibling search/list tools such as search_routes or routes_in_national_park.

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 makes the usage context clear: use this when you already have a route slug and need full route details. It does not explicitly name alternatives or state when not to use it, so it falls short of full alternative routing guidance.

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 and openWorldHint=false, so the safety profile is covered. The description contributes beyond that by disclosing the return payload shape ('list metadata and the ordered routes'), which matters since there is no output schema. It omits error behavior for an unknown slug, which keeps 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?

Two sentences with no filler; the action and lookup key are front-loaded and the return content follows immediately. Nothing could be removed without losing 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 one-parameter read tool with no output schema, the description covers what it fetches and roughly what comes back, and annotations cover the safety profile. The only real gap is what happens on a bad or missing slug.

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 single parameter already documents both its origin (browse_runlists) and the URL format. The description's 'by slug' phrase merely restates the parameter name, adding no new semantics, so the 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 ('Fetch a Skamper run list') plus the lookup key ('by slug'), and adds scope by noting it returns metadata and the ordered routes inside. It separates itself from browse_runlists only implicitly, since the sibling is never named as the contrasting 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?

Usage is only implied: the tool is clearly the detail-lookup counterpart to a listing tool, but the description never says when to prefer this over browse_runlists or search_routes. The slug provenance hint lives in the schema, not the description.

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=true, idempotent=true, and openWorld=false, so the safety profile is covered. The description adds behavioral value by disclosing what the result contains (route counts and slugs) and that the slug is the key for chaining into other tools, which is not derivable from annotations or the empty 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?

Two sentences, no filler: the first defines the tool and its output, the second tells the agent exactly what to do next. The payload description is front-loaded before the chaining 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 no output schema, the description carries the burden of describing returns and does so at a high level (parks, route counts, slugs). Minor gaps remain, such as whether the list is a complete static catalog or may change, but nothing needed to invoke 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?

The tool takes zero parameters, which sets a baseline of 4. The only parameter referenced (national_park) belongs to sibling tools, and the description correctly frames it as an output-to-input handoff rather than a parameter of this tool.

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 ("List the UK National Parks") plus a scoping qualifier ("Skamper covers") and the response payload (route counts and slugs). An agent immediately knows this is a discovery/enumeration tool rather than a route-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?

Explicitly routes the agent forward: "Use the slug with routes_in_national_park or search_routes (national_park=...)", naming both relevant siblings and even the parameter to pass. It lacks an explicit when-not-to-use clause, but for a zero-argument enumeration tool the usage context is effectively 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds what they cannot: results are a ranked shortlist carrying surface, ascent, course shape and national park fields, plus canonical Skamper URLs. It does not discuss result-set size behaviour or what happens when no route matches, which is the remaining gap for a recommendation engine.

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 doing distinct work: purpose, usage trigger with example, return shape and disambiguation. The purpose and the routing decision are front-loaded, and there is no restatement of the title or filler wording.

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 10-parameter, zero-required recommendation tool with no output schema, the description covers purpose, invocation style, return fields and sibling routing, which is close to sufficient. The minor hole is that it never states all parameters are optional or what the defaults produce, leaving the agent to infer behaviour when the user gives minimal context.

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 80%, so baseline is 3; the description earns a bump because the example sentence demonstrates how free-text runner intent maps onto specific fields (trail_runner, ~15k, avoid roads, scenic, low technicality). It still adds nothing for limit, distance_tolerance_km or the near_lat/near_lng pair, which remain schema-only.

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 ("Recommend a UK running route") plus the scope qualifier "that fits the runner", which distinguishes it from filter-based listing tools. The final sentence names the sibling it is not (search_routes), so an agent can separate the two 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?

Gives an explicit when-to-use trigger ("when a user describes who they are and what they want") with a concrete worked example, and states the selection rule against the alternative: preference-based requests go here, exact numeric filters go to search_routes. Both the use case and the exclusion are spelled out.

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, and openWorldHint=false, so the safety profile is covered. The description adds the geographic bound (UK parks only), consistent with openWorldHint=false, plus the slug-discovery workflow. It says nothing about result volume, pagination, or what a returned route contains.

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 short sentences, front-loaded with the purpose followed by the required input and its discovery path. No filler, no repetition of the 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?

For a simple two-parameter read-only listing tool with no output schema, the description covers what it does and how to supply the key input. The only real gap is the undocumented limit parameter and the absence of any hint about result size or pagination 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 coverage is 50%: slug is documented in the schema, but limit (default 15, max 40) has no prose explanation anywhere. The description does add real value for slug by pointing to list_national_parks as the discovery mechanism. The limit parameter's meaning and the effect of capping results remain undocumented.

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?

"List running routes inside a UK National Park" gives a specific verb (list), resource (running routes), and a geographic scope (UK National Park) that separates it from generic siblings like search_routes. It does not explicitly say how it differs from search_routes or browse_runlists, so it stops short of 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?

It states the required input path clearly: pass the park slug, and use list_national_parks to discover valid slugs. That is actionable prerequisite guidance. It gives no when-not-to-use guidance or contrast with search_routes, which is the obvious alternative for route lookup.

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 and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the result cap ('up to 20 compact route summaries') and the return shape ('canonical URLs'). It does not say what happens with zero matches or how limit interacts with the cap, so it stops 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?

Three sentences, all load-bearing: capability and filters first, return shape second, disambiguation third. No repetition of the title and 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?

For an 11-parameter, zero-required search tool with no output schema, the description covers the filter space, the result size, and routing to siblings. It omits edge behavior such as empty results and whether filters combine as AND, which keeps it from being fully complete.

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 64% schema coverage the schema already documents most parameters, including the runner-oriented hints on max_paved_pct and min_paved_pct. The description's enumeration of filter dimensions largely mirrors those schema properties rather than adding new semantics; the only mild addition is framing 'name' as a filter, while the schema calls the parameter 'query' and describes it as free text over titles and slugs.

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 Skamper's curated UK running-route database') and enumerates the concrete filter dimensions it accepts (name, lat/lng, distance range, max ascent, paved %, course shape, national park). It also names the sibling tools it is not (recommend_route, find_5k), so an agent can route correctly 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?

Explicit triggering condition — use when the user gives concrete filters — plus two named alternatives with the exact condition that selects each ('describes who they are or what they want' → recommend_route; 'parkrun-distance asks' → find_5k). Both when-to-use and when-not-to-use are covered.

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