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

With no annotations, the description must carry the behavioral burden, and it does disclose that this is a file write of GPX 1.1 with elevation and that the target directory must pre-exist. It is silent on overwrite behavior (does an existing file get replaced?), whether the filename derives from the name param or route_id, and whether permissions/side effects apply.

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 front-loaded sentence with no filler; every clause (format, elevation, directory constraint) earns its place. The packed parenthetical for out_dir constraints is slightly terse but readable.

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 described, and the format/elevation/directory requirements are covered. For a filesystem-mutating tool with zero annotations, though, the overwrite semantics and how the output filename is chosen are meaningful gaps.

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 must compensate, and it only partially does: out_dir gets real added meaning (must exist, absolute or ~), but route_id is left implicit and the name parameter is never explained (filename? GPX track name?). The most ambiguous parameter is 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?

The description names a specific verb ("Write") and resource ("a planned route as GPX 1.1") plus the output destination, which is far more precise than the bare name export_gpx. It does not explicitly contrast itself with siblings like plan_route or route_details, but the write-to-file purpose is unambiguous.

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 one prerequisite for out_dir ("must exist; absolute or ~"), which implies the tool is used after a route exists. However, it never says when to choose this over alternatives, nor that a route must be planned first (e.g., via plan_route) or that route_id must reference an existing route.

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?

No annotations are provided, so the description carries the burden. It does disclose useful behavior: the lookup uses Nominatim, is limited to Irish place names, and returns candidate matches with name and coordinates. However, it omits operational details such as rate limits, ambiguity handling, and whether an empty result is expected when no Irish place matches.

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 two short sentences with the core purpose front-loaded and the return shape immediately after. There is no filler, and every clause contributes useful information for selecting or calling 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?

An output schema exists, so the description need not explain return values in depth, and it does summarize the key return fields. Still, for a tool with no annotations and 0% schema description coverage on its inputs, the description leaves gaps around the 'limit' parameter and expected query format that would help an agent 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 schema does not explain the parameters. The description implies that 'query' is an Irish place name, but it never explains the 'limit' parameter (default 5) or how it controls the number of returned candidates. It therefore only partially compensates for the missing schema documentation.

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 ('look up an Irish place name') and names the backing service (Nominatim), so the agent knows this is a geocoding lookup rather than a routing tool. It does not explicitly distinguish itself from siblings like route_details or plan_route, but the purpose is clear enough to select it for place-name lookups.

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?

The description gives no guidance on when to use this tool versus alternatives such as route_details, plan_route, or pick_points. The Irish-place-name scope is stated, but there are no exclusions, prerequisites, or workflow context to help the agent decide when geocoding is the right 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?

With no annotations the description carries the full burden, and it discloses the meaningful behavior: the tool yields plain data dicts whose keys (`settings`, `objective`) map onto plan_route arguments. It does not explicitly state that the call is side-effect free or list what serialization/shape edge cases exist, so it stops short of fully covering the behavioral surface.

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 dense sentence: the resource and its contents come first, followed by the consumption instruction. No filler, nothing that fails to earn its place.

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 zero-input lister with an output schema already present, the description need not explain return values, and it still adds the crucial consumption mapping. The only minor gap is the absence of any explicit statement that calling it has no side effects.

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, so the baseline is 4. The description goes further by naming the two output fields and which plan_route argument each feeds, which is directly actionable semantics even though the output schema already exists.

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 names the resource (settings presets) and enumerates the concrete preset kinds (straight & lanes, plain flow, climb, flat) plus their output form ('as dicts'). It implicitly separates this from siblings by pointing at plan_route as the consumer, though the listing verb itself is only implied.

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 exactly what to do with the result: pass `settings` to plan_route and `objective` as plan_route's objective argument. That is a clear usage context with no realistic alternatives to disambiguate among siblings, but there is no explicit 'when not to call' or prerequisite statement.

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 burden and does disclose key traits: the tool is interactive and blocking (it opens a browser and waits for the user), and it depends on an external server being up. It omits what happens when the user never clicks (timeout behavior, failure mode), which matters for a blocking call.

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 tight sentence front-loads the action and follows with the prerequisite and return contract. No filler, though the parenthetical could be structured more crisply.

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 the description need not explain the return shape, though it helpfully notes 'lat,lon' strings and their use in plan_route. The remaining gap is timeout/failure behavior for a tool that blocks on human input.

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 0%, so the description must document both parameters. 'Click 1 or 2 points' loosely hints at `n` but never names it or its bounds, and `timeout_s` is not mentioned at all despite governing how long an agent will block.

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: asks the user to click 1 or 2 points on the planner map and waits for the result. It also names the downstream consumer (plan_route) and the return format, so an agent can distinguish this interactive picker from geocode or route_details 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?

Implies usage clearly: call this before plan_route to obtain 'lat,lon' start/end strings, and it requires `make planner` running. It gives a prerequisite and a purpose in the workflow, but offers no explicit exclusions or alternatives (e.g., when to use geocode instead).

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: it discloses geocoding of place names (echoed back), a 30-60 s latency for loops, and that length is ignored for one_way. It does not say whether the call is read-only/side-effect free, what happens on unresolvable place names, or the shape of plan notes.

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?

Telegraphic parameter-grouped style with the most load-bearing facts (modes, distance rules, objective) up front and return behavior last. Every clause carries information, though the run-on density and the stray line break make it slightly harder to scan than it needs to be.

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 tool with an output schema, the description covers all the semantically complex inputs plus a one-line note on the returned markdown table and plan notes. The gaps are the unmentioned n (result count) and bearings parameters, which no structured field 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 description coverage is 0%, so the description does nearly all the work: it defines mode values, start/end formats, the length family and its tolerance, objective values, return_mode values, and the settings dict including the main_road_penalty 1..5 scale with a concrete 2.5 example. Two parameters, n and bearings, are left entirely 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?

States a specific verb and resource ('Plan routes') and immediately enumerates the mode vocabulary, so an agent knows this is the route-generation entry point. It also implies its place in the pipeline by telling the caller to feed returned ids into route_details / export_gpx, though it never explicitly contrasts itself with those siblings.

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 conditional rules: loops and out-and-backs require length_km (+-10%) or min_km/max_km, one_way requires end and ignores length, and settings should come from list_presets. Alternatives are implicit via the downstream id usage rather than stated as explicit when-not-to-use 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?

With no annotations, the description carries the behavioral burden. "Explain" and the listed output metrics strongly imply a read-only informational operation, but the description does not explicitly state side effects, permissions, or error 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?

The definition is a single front-loaded sentence with zero waste. It efficiently lists the key output dimensions without unnecessary preamble.

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 and the description summarizes the returned metrics, so return values are reasonably covered. What remains missing is the route_id source/prerequisite and any guidance on when to choose this over siblings.

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%, and the description never explains route_id, its expected format, or where to obtain it. The single parameter is simple and inferable from context, but the description adds little beyond the schema's parameter name.

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 ("Explain") and resource ("planned route"), then enumerates the route metrics returned. It clearly separates this from plan_route by implying this is post-planning detail retrieval, though it does not explicitly name the sibling.

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?

The phrase "planned route" and required route_id imply this should be used after a route has been planned. However, there is no explicit when-to-use guidance, no mention of plan_route, and no exclusions versus export_gpx or other siblings.

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 still discloses meaningful behavior: it spawns a local server process, is conditional on reachability, and blocks for up to 60 seconds. It does not say what happens on timeout or failure (error vs. partial start), which is the main remaining gap for a process-launching 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?

A single sentence that is front-loaded with the action and resource, then adds the mechanism and the blocking timeout. No filler, and 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?

The tool is simple, parameterless, and ships with an output schema, so return values need not be explained. The description covers what an agent needs to call it correctly; only failure/timeout semantics are unaddressed.

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, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies no configuration is needed.

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 (Start) and resource (the local BRouter server), plus the concrete mechanism (scripts/run_brouter.sh serve). It is clearly distinct from the sibling 'status' tool, though it does not name any 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?

The phrase 'if it is not reachable' gives an explicit precondition and signals the call is safe/idempotent when the server is already up. It does not point the agent at 'status' as the way to determine reachability, so the routing to the alternative is left implicit.

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?

No annotations are supplied, so the description carries the full burden, yet it never states that this is a read-only, side-effect-free query, whether an unavailable BRouter instance is reported as an error or as a value, or what the reachability/coverage fields mean. Listing the reported facets is a start but leaves the behavioral profile thin.

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?

It is a single compact sentence with zero padding, which is good, but as a sentence fragment without a subject or verb it reads as a field list rather than a definition, and the most important information (what the tool returns/why to call it) is not 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?

An output schema exists, so return-value detail is legitimately omitted, and with zero parameters the call mechanics are trivial. Still, for a status/health tool it would help to say it reports the state of the configured BRouter instance and is the natural first call in the workflow, which is absent.

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, so the schema fully covers the call signature; the description adds nothing to misinterpret and nothing is missing on the parameter side.

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 enumerates the domains reported (reachability, region, weight set, flow index size, DEM coverage), which tells an agent what information is surfaced, but it is a noun phrase with no verb, so the action (return current BRouter server/segment state) is only inferred from the name 'status'. It also never distinguishes itself from siblings like start_brouter or list_presets.

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?

No when-to-use guidance is given: nothing says this is the pre-flight/health check before calling plan_route or route_details, and no alternatives or exclusions are named. The agent must infer applicability from the tool name alone.

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