MapMap

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

With no annotations supplied, the description carries the full behavioral burden and does so: records self-expire 'within minutes', they rank below official closures and never retract one, the tool is feature-gated (SN_CAMERA_INCIDENTS_ENABLED, 501 when unarmed), and it requires GATEWAY_URL + GATEWAY_API_KEY. This is unusually rich disclosure for a read 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?

It is front-loaded with the core claim and every sentence carries information, but the single dense run-on paragraph mixes filter mechanics, record contents, caveats, and gating, making it harder to scan than a short structured form.

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 gated, credential-requiring tool this covers what an agent needs: how to scope the query, what each record asserts and includes, expiry behavior, the coverage_note caveat, and attribution requirements. An output schema exists, yet the description still usefully summarizes record contents.

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 baseline is 3. The description restates the near/radius_m and shape/buffer_m defaults that the schema already documents and omits min_confidence and include_recently_expired entirely, adding little semantic value beyond the structured fields.

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 opening clause names the specific resource and its provenance (road incidents a traffic camera saw and a vision model confirmed, in force now), and the 'rank below official closures' line implicitly separates it from sibling closure/observation tools. An agent can tell what this returns 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?

It gives an explicit selection rule for the spatial inputs ('Give exactly one' of near/bbox/shape) with defaults, warns that an empty list never means a clear road, and states the deployment gating ('Off unless the deployment arms camera incidents... an unarmed gateway answers 501'). Conditions for use and non-use are both covered.

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

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

With no annotations, the description fully discloses behavior: data comes from operator-published feeds, costing respects the selected profile (truck dimensions/ADR), results are ranked by power, empty results mean 'none from these operators' not 'no chargers', statuses are live only when availability_live is true, and the `say` field is the authoritative answer. It also covers error behavior for missing datasets and mandates displaying attribution. This is exemplary transparency beyond the 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?

The description is long but every sentence carries operational significance. It front-loads the key differentiator (real detour time) and the coverage caveat early. It is dense but well-organized, avoiding fluff; the length is justified by the tool's complexity and edge cases.

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?

Despite having an output schema, the description explains the interpretation of results (coverage_note, empty results meaning, live vs ingested statuses, say field composition) and error handling. It covers all parameters and their interdependencies, making it complete for an agent to call correctly without additional 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 100%, so baseline is 3. The description adds meaning: it explains connectors list, gives a min_kw example, clarifies that available_only requires a live feed, and explains how truck costing affects detours. It also ties parameters to output semantics (e.g., detour_minutes/detour_km). This adds value beyond the schema without redundancy.

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 ('Find') and resource ('EV charge points along a route') and highlights the distinctive real detour-time calculation versus straight-line guesses. It is clearly distinguished from siblings like cheapest_fuel_along_route (fuel vs EV) and search_along_route (generic search vs costed charging).

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?

Provides explicit input modes (origin+destination or geometry_polyline6, not both), conditions for available_only (requires live feed, otherwise refused), and the important caveat about operator coverage and the coverage_note. It does not explicitly name alternatives or when-not-to-use, but the context is clear and actionable.

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 provided, the description carries the full burden and does an excellent job. It discloses live data sources, the definition of 'stale' with exact conditions, ranking rules, the behavior of stale prices (never baseline, no saving), and the instruction to quote them honestly. It also explains the 'say' field's composition and the error case for missing datasets. This is exceptional transparency.

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 long but every sentence contributes. It is well-structured with the purpose first, then input modes, data sources, output details, stale-price handling, and the 'say' field guidance. It is not overly verbose given the complexity, though it could be tightened slightly without losing essential 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?

Given the 9 parameters, 100% schema coverage, and presence of an output schema, the description is remarkably complete. It covers all input modes, fuel types, costing models, the stale-price logic, the 'say' field composition, attribution display, and error conditions. Nothing essential for correct invocation 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 schema already describes all parameters (100% coverage), so baseline is 3. The description adds meaning beyond that: it explains the mutual exclusivity of origin/destination vs geometry_polyline6, the effect of fill_litres on saving_total, the truck profile's impact on detour restrictions, and the aliases for fuel codes. This is valuable added context.

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 ('Find the cheapest fuel'), a clear resource (fuel along a route), and distinguishes itself from the sibling 'cheapest_charging_along_route' by focusing on fuel types. It also contrasts with generic search tools by emphasizing real detour times and price freshness. The scope 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?

The description gives explicit input modes (origin/destination or geometry_polyline6), defaults for fuel and max_detour_minutes, and explains the 'say' field should be read verbatim. It does not explicitly name alternative tools, but the usage context is clear. It also mentions the MapMap gateway requirement and error behavior, which helps the agent decide when 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?

With no annotations provided, the description carries the full disclosure burden and succeeds: it states the conservative worst-case reading ('a blocked answer may over-restrict but never under-restricts') and operational traits ('No network access; answers instantly'). This is exactly the kind of behavioral context agents need beyond the 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?

Three sentences, purpose front-loaded in the first ('Check whether a vehicle may pass through a tunnel...'), with every sentence earning its place. No fluff; the behavioral caveat and operational notes are tightly packed in the final sentence.

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 description covers purpose, parameter usage, interpretation semantics, and operational behavior, while the output schema covers return values and the input schema covers all parameters. Slightly more could be said about edge-case handling (e.g., unrecognized tunnel codes), but nothing essential to selecting or invoking the tool 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 100%, so the schema already documents all three parameters; baseline is 3. The description adds marginal value by reinforcing which parameters to supply and giving code examples ('B', 'C5000D', 'B/D', 'none'), though these overlap with the schema's own examples.

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: 'Check whether a vehicle may pass through a tunnel of a given ADR category ("A"–"E")'. The ADR tunnel category scope clearly differentiates it from geo siblings like check_clearance_on_route, which concerns route clearance rather than hazmat tunnel restrictions.

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 implies its use case (determining hazmat tunnel passage) and instructs what to provide ('Provide hazmat and, when known, the load's ADR 8.6.4 tunnel restriction code'), but it never explicitly contrasts with alternatives such as check_clearance_on_route or states when not to use it. Usage context is present but left 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?

With no annotations, the description carries full disclosure burden and succeeds. It reveals return verdicts, honesty caveats, that clearance_enforcement.route_certified is always false, that unsurveyed ground returns not_surveyed_m and is never judged, and that the MapMap gateway and API key are required with no fallback. This is extensive behavioral transparency beyond the 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?

The description is long, but the tool is complex and the length is mostly justified by caveats, return semantics, and infrastructure requirements. It is front-loaded with the core purpose, though a few phrases are slightly convoluted or repetitive, such as the explanation about the route step and gateway requirements.

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 tool's complexity and the presence of an output schema, the description covers all necessary operational context: when to use it, what parameters mean, what each answer type implies, survey coverage limitations, and authentication/gateway requirements. Nothing an agent needs to call this correctly appears 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%, so the baseline is 3, but the description adds meaningful semantics: it explains that width_m only triggers a separate width-axis check, that height_m is required because there is no default vehicle, and that margin_m is added to the measurement before the verdict, not to the routing step. This materially improves parameter understanding.

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: measuring overhead clearance along a route against surveyed point cloud geometry. It distinguishes itself from routing and map-tagged height tools by framing the output as physical measured headroom, not posted height, and by contrasting with the routing step and other sibling tools.

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 explicitly says 'Reach for this when a truck route came back unchanged' and explains the difference between route-level avoidance and measured headroom. It also states the tool cannot answer from the routing step alone and that there is no fallback, providing clear usage context, though it does not name many alternative sibling tools explicitly.

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 does well: it discloses the two palette variants checked, the exact thresholds, that failing pairs list slots to adjust, and that contrast never blocks publishing. It does not explicitly state it is read-only, but 'Audit' and 'Advisory' imply no mutation.

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 carry purpose, input, thresholds, and advisory behavior with no filler. Every sentence earns 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?

The tool has only two parameters, an output schema exists, and the description supplies thresholds, input alternatives, palette variants, and follow-up guidance via set_palette. 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?

Schema coverage is 100% and the schema already documents the exactly-one-of style_id/theme rule and theme format. The description adds only a concise restatement and a pointer to create_style, which is useful but not a major increment over 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 opens with a specific verb ('Audit'), a precise resource ('a map style's colour contrast'), and an explicit standard (WCAG 2.1 thresholds for label text and graphics). This clearly distinguishes it from sibling tools like check_adr_tunnel or set_palette.

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 clear invocation condition ('Pass a hosted style_id OR an inline theme document') and directs failed pairs to set_palette. It lacks an explicit 'when not to use' contrast, but the advisory note that publishing is never blocked on contrast conveys the appropriate context.

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 delivers richly. It discloses the key behavioral trait: 'STRAIGHT-LINE clustering' with no road, river, or one-way system consulted, including the estuary example. It also discloses determinism across deployments, the bin-packing relaxation behavior, the `basis` output caveat, and the MapMap gateway requirement.

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?

Although the description is long, every sentence earns its place: purpose, recipe, critical caveat, parameter rules, determinism promise, balance-block explanation, and gateway dependency. It is front-loaded with the use case and the key straight-line warning, and uses bold markers to guide attention. There is no filler or redundancy.

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 description is complete for a 6-parameter tool with an output schema. It covers the recipe's place in the workflow, the clustering distance model, the exact-one parameter selection, determinism, how territories interact, the bin-packing relaxation possibility, and the required gateway. Since an output schema exists, the description's brief summary of the response shape is adequate.

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 baseline is 3 and the schema already documents every parameter thoroughly. The description adds emphasis (e.g., 'EXACTLY ONE of') and restates the derived-count logic, but it does not add materially new meaning beyond the schema's own parameter descriptions. A score of 3 reflects that the schema does 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?

The description names a specific verb and resource: 'Group stops into balanced geographic clusters,' and immediately explains the purpose with the one-cluster-at-a-time use case. It distinguishes itself from siblings by explicitly saying it is the 'front half of the recipe' and the 'right tool for deciding which stops belong TOGETHER and the wrong one for deciding what ORDER to visit them in,' contrasting with optimise_routes and order_stops.

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 fully explicit: use cluster when a day is 'too large for one optimisation,' then 'call `optimise_routes` per cluster.' It gives an exclusion rule — straight-line clustering makes it wrong for ordering — and names the specific alternative to use for order. It also states the exact-one-of constraint among `clusters`, `max_cluster_locations`, and `max_cluster_load`.

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?

There are no annotations, so the description carries the full behavioral burden. It discloses the merge order (base first, theme merged over it), the default behavior when neither is provided, the special worldview behavior with accepted values and fallback behavior, and the return contract. This is rich, accurate behavioral context beyond the 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?

The description is dense but every sentence earns its place: creation intent, parameter choices, merge behavior, worldview behavior, and return value. It is front-loaded with the core purpose and organized so the reader learns the default case before the edge cases.

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 tool with three parameters, no annotations, and a nontrivial merge model, the description is complete. It explains how base, theme, and defaults interact, names the downstream tools for the returned style_id, and specifies the compiled style URL. Nothing essential is missing for an agent to invoke 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?

The schema already provides 100% coverage for parameter names, but the description adds significant extra meaning: the exact list of base values, the theme document structure with base/palette/layers, the merge semantics, and the worldview field with allowed country codes. This materially helps an agent construct valid arguments.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Create a hosted map style.' It distinguishes itself from sibling tools like get_style, set_palette, set_layer_paint, and list_style_layers by focusing on creation and by stating the generated style_id is meant for the set_* tools. No ambiguity remains about what this tool does.

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 clear context for when to use create_style: to lay down a base, merge a theme, or start from the default theme. It also routes the agent to list_style_layers for base details and to set_palette/set_layer_paint for follow-up modifications. It does not explicitly state when not to use create_style versus get_style, but the creation-oriented guidance is strong.

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 provided, the description carries the full burden of behavioral disclosure. It does this thoroughly: it states that elevation_m is null where DEM coverage is missing and 'never a guess', and it discloses that the encoded_polyline form returns resampled lat/lon and cumulative range_km. This goes well beyond a basic 'returns elevation' statement and gives the agent confidence about edge cases.

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: the core purpose is in the first sentence, and the key constraint ('not both') appears early. Every sentence earns its place, covering purpose, input modes, return behavior, and edge cases without redundancy. It is appropriately sized for a tool with three parameters and a rich output schema.

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 tool's moderate complexity (two mutually exclusive input modes, optional resampling, null-coverage behavior) and the presence of a rich output schema, the description covers everything an agent needs to invoke it correctly. It explains the trade-off between the two modes, the resampling parameter's scope, and the null semantics. The output schema handles return-value details, so the description doesn't need to repeat them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the mutual exclusivity of points and encoded_polyline, clarifies that resample_distance_m is ignored for points, and describes the return behavior (one sample per point, null for missing coverage). It doesn't add much about the LatLon format, but the schema already covers that thoroughly. The extra behavioral context justifies a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Sample terrain elevation') and immediately distinguishes the two input modes (points vs encoded_polyline). It clearly states what the tool does and how it differs from the many sibling tools, which are mostly routing/geospatial operations rather than elevation sampling.

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 explicitly says 'not both' for the two mutually exclusive input modes, and explains when to use each: point elevation vs along-route profile. It also clarifies that resample_distance_m applies only to encoded_polyline and is ignored for points. This is direct, actionable guidance with no ambiguity.

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 provided, the description carries the full burden of behavioral disclosure. It discloses that the result is always positive regardless of winding order, that computation is geodesic, and that it is local with no quota. It does not mention edge cases like degenerate rings or the exact return format, but the output schema likely covers the return value. The description adds meaningful behavioral context beyond the 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?

The description is four sentences, each earning its place: what it computes, the winding-order invariance, the intended scope, and the local-computation note. It is front-loaded with the core purpose and avoids redundancy with the schema.

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 single-parameter tool with a rich schema and an output schema, the description is nearly complete. It covers the main behavioral traits and usage constraints. The only minor gap is not stating what happens with fewer than 3 points or degenerate rings, but the description already says '3+ coordinates' and the schema requires an array, so this is adequately implied.

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 documents the 'points' parameter and the LatLon format. The description adds the key semantic constraint that the ring must have 3+ coordinates and that the area is computed geodesically, which is not fully explicit in the schema. This compensates for the schema's generic 'coordinates to consider' phrasing.

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 ('Area in square metres enclosed by a ring of 3+ coordinates') and a clear resource, distinguishing it from sibling geo tools like geo_distance, geo_length, and geo_centroid. It also clarifies the geodesic computation and the intended use case, so an agent can tell it apart from other geometry tools 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?

The description explicitly says when to use it ('Intended for zones and boundaries') and when not to ('not for polygons covering more than half the globe'). It also notes the local computation ('no network call, no quota'), which helps an agent choose it over network-dependent alternatives. This is clear usage guidance with 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?

With no annotations provided, the description carries the behavioral disclosure burden. It covers the computed result, the axis-aligned nature, and the important side-effect signals: no network call and no quota. It does not discuss edge cases like invalid coordinates or wrapping behavior, but the schema already constrains coordinate ranges.

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 first explains the behavior and output format, the second gives a practical use case and cost/performance note. The most important semantic information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter computation with a rich input schema and an output schema present, the description covers what the tool does, the returned fields, a typical use case, and the local/no-quota behavior. Nothing essential for correct invocation 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 100%, so the schema already documents the points parameter and LatLon formats thoroughly. The description adds minimal parameter-level nuance beyond '1+ coordinates' and the output field names, which does not substantially exceed the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific operation ('axis-aligned bounding box enclosing 1+ coordinates') and gives the exact output shape {min_lat, min_lon, max_lat, max_lon}. This clearly distinguishes it from sibling geo tools like geo_centroid, geo_area, or geo_distance.

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 use case ('fitting a map view to a set of stops') and adds that it is a local computation with no network call and no quota. It does not explicitly name sibling alternatives or exclusions, but the stated context is clear enough for an agent to select it appropriately.

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 provided, the description carries the full burden of behavioral disclosure. It discloses three important traits: the result is the initial bearing (not final), the bearing changes en route for long distances, and the operation is local with no network or quota implications. It does not describe error behavior or what happens with invalid coordinates, but for a pure geometry calculation this is a minor gap. No contradiction with annotations exists.

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 zero filler. The first sentence states the result and unit; the second adds the geodesic nuance and the local-computation performance trait. Each sentence earns its place, and the most important information 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?

The tool is a simple geometry computation with a rich input schema and an output schema. The description covers the essential behavioral context (initial bearing, change along the geodesic, local computation) and does not need to explain return values because an output schema exists. An agent reading this description has everything necessary to invoke the tool correctly and interpret the result in 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 description coverage is 100%. The 'from' and 'to' parameters are clearly named and described as 'Start coordinate' and 'End coordinate,' and the shared LatLon definition explains both object and array forms, including the 'longitude FIRST' order. The tool description itself adds no parameter-level semantics, so it neither improves nor harms the schema's already sufficient documentation. 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?

The description names a highly specific operation and output: 'Initial bearing from one coordinate to another, in degrees clockwise from true north (0-360).' It also clarifies the geodesic context ('bearing at the START of the geodesic'), which distinguishes this from an average or final bearing. None of the sibling tools compute bearing, so there is no ambiguity.

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 clear contextual guidance: the bearing is the initial one and changes over long distances, implying that for navigation along a route one should not assume a constant bearing. It also notes 'Local computation: no network call, no quota,' which helps an agent decide when a cheap local calculation suffices. However, it does not explicitly name alternative tools (e.g., geo_destination or geo_distance) or state exclusion conditions, so it falls 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?

With no annotations provided, the description carries the behavioral burden, and it does well by explicitly stating 'Local computation: no network call, no quota.' This clarifies that the operation is synchronous, offline, and quota-free, which is valuable for an agent deciding whether to invoke it.

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, information-dense sentences. The definition is front-loaded, followed by practical examples and a key behavioral note, with no filler or repetition of schema content.

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 computation tool with a rich schema and an output schema present, the description covers the essential context: what it computes, when to use it, and its local non-quota behavior. No critical information for invoking 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 schema already documents the points array and the LatLon format with 100% coverage, so a baseline of 3 applies. The description adds meaning by specifying '1+ coordinates', clarifying the minimum input count that the schema does not enforce, and by explaining the geometric meaning of the result.

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: it computes the centroid (geometric mean position) of coordinates. The examples 'pick a depot location or centre a map' make the function’s intent immediately clear and help distinguish it from sibling geo tools like geo_distance or geo_area.

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 concrete use cases ('pick a depot location or centre a map'), making its intended application clear. It does not explicitly name alternative tools or when not to use it, but the purpose is specific enough that an agent can select it confidently.

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 does so richly: components are REQUIREMENTS not hints, an unknown `country` is refused rather than silently matching nothing, `lang` outside the supported set is refused, and unmatched/inferred `match` verdicts plus small `score_gap` signal unreliable answers. This is far beyond what the schema states.

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?

Dense and largely front-loaded — the core action and the two input modes come first, then behavioral caveats. It runs long, with the `lang`/exonym material at the end feeling somewhat expendable, but nearly every sentence carries operational 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 9-parameter, zero-required tool with an output schema, this covers the gaps well: mutual requirement of query/components, return count and fields, ranking bias, and how to interpret `match`/`score_gap`. An agent could invoke and correctly act on results without opening 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 coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: the requirement-vs-hint distinction between structured components and `query`, the 'at least one of the two is required' rule, and the ranking effect of `focus`. It stops short of fully decoupling from the schema's own parameter text.

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: 'Turn a place (address, POI, town) into coordinates.' It implicitly distinguishes itself from reverse_geocode (coordinates→place) by naming the inverse direction, and from siblings like nearby_places/places_in_view by framing itself as the forward geocoder.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing to the alternative: 'Use `verify_places` when the address came from a model or a user and needs checking rather than using.' It also gives a concrete selection rule for the two input modes: 'Pass the parts whenever you already hold the address in parts (a form, a CRM row, a manifest).'

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 full behavioral disclosure. It clearly states this is a local computation with no network callchers, and it explains the calculation semantics with exact units and reference directions. It could add edge-case behavior (e.g., poles, antimeridian) but is transparent about the core side-effect-free nature.

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 dense sentences with no filler. The core result is front-loaded first, then the inverse relationship and local-computation note follow logically.

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 geometric computation with an output schema presentlor, the description covers the essential selection and side-effect context: what it computes, how it relates to sibling tools, and that it is local. The lack of geodetic model details is a minor gap given the inverse-relationship hint.

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 documents each parameter thoroughly. The description adds contextual meaning about the inverse relation and gives units, but these mostly mirror the schema definitions rather than adding substantial new semantics.

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?

Description states a precise calculation: the coordinate reached after travelling a distance from a point on a given bearing. It names the inverse relationship to geo_distance and geo_bearing, which clearly distinguishes it from those sibling tools.

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 'The inverse of geo_distance + geo_bearing' tells an agent when this tool is conceptually appropriate, and 'Local computation: no network call' gives a clear practical context for preferring it for offline or quick calculations. It does not explicitly state when not to use it, but the inverse framing is sufficient for selection.

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 provided, the description carries the full burden of behavioral disclosure. It goes beyond a plain function summary by stating that it computes on the WGS84 ellipsoid, is a local computation, makes no network call, and consumes no quota. This gives the agent trustworthy operational expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no filler. The core result and unit are front-loaded, the critical distinction from driving distance follows immediately, and the local-computation note is valuable behavioral context rather than repetition.

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 description is complete for a two-parameter computational tool: it explains the algorithm, the unit, the coordinate system, the limitation, and the alternatives. The input schema is detailed, and an output schema exists, so return-value details are not required in the description.

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 defines the two coordinate formats, including the GeoJSON [lon, lat] ordering. The description adds only the unit ('metres') and the general notion of 'two coordinates', which is minimally additive. The baseline of 3 is appropriate because the schema does 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?

The description uses a specific verb and resource: 'Distance in metres between two coordinates' and clearly identifies the computation as geodesic straight-line distance. It also distinguishes itself from route/matrix by explicitly stating what it is NOT, which differentiates it from the many geo_* 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?

The description explicitly tells the agent when not to use this tool ('NOT a driving distance') and names the alternatives ('use `route` or `matrix` for travel distance and time'). It also adds a practical usage signal by noting that computation is local, with no network call or quota.

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 behavioral disclosure burden. It adds useful context: geodesic summation, local computation with no network call or quota, and the explicit non-route scope. It does not discuss error handling or precision limits, but for a read-only measurement tool these are minor.

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 with distinct value: purpose, route exclusion, and computational behavior. The main purpose is front-loaded 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?

With only one parameter, a detailed schema, and an output schema, the description covers the essential decision factors: what it measures, the geodesic method, the route distinction, and resource impact. Nothing an agent needs 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?

Schema coverage is 100% and the LatLon definition thoroughly documents both coordinate formats and longitude-first ordering. The description adds the important 2+ minimum for the points array, something the schema does not enforce, and clarifies the line/order semantics through 'polyline'.

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?

Clearly states it computes the total geodesic length in metres of a supplied polyline of 2+ coordinates. The explicit 'NOT a driven route' and pointer to `route` distinguishes it from the routing sibling, and the polyline framing separates it from point-to-point distance tools.

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 tells the agent to use `route` when a driven route is needed rather than the supplied line, giving a concrete when-not and alternative. The phrase 'the line you supply' implies the intended use case (measuring arbitrary geometry) and the local-computation note reinforces when it is safe to call without quota concerns.

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 and handles it well: it discloses local computation, no network/quota, geodesic distance, and interpolation between vertices. It implies a read-only calculation without side effects, though it does not explicitly state that or describe edge-case 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?

Four sentences, each earning its place: result, interpolation caveat, use case, and execution traits. The most important information is front-loaded and there is no redundant boilerplate.

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 two-parameter local calculation with a rich input schema and an output schema present, the description gives all needed call-time context: result meaning, units, interpolation behavior, and cost model. Nothing critical for invoking the tool 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 100%, so the baseline is 3; the description adds no parameter-level syntax beyond the schema. It correctly maps the two inputs to 'coordinate' and 'polyline', but the schema already documents the {lat, lon} object vs [lon, lat] array distinction and the 2+ vertex requirement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb+resource statement: it returns the closest point on a polyline to a coordinate plus the geodesic distance in metres. It clearly distinguishes itself from generic geo_distance/geo_length by noting the answer may lie between vertices, and the use case 'how far is this address from the route?' reinforces its identity.

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 provides an explicit use case and a practical execution trait: local computation with no network call and no quota. It does not name sibling alternatives or state when not to use it, but the context is clear enough to guide an agent toward this tool over generic distance or geometry helpers.

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 provided, the description carries the full burden. It discloses the boundary-counts-as-outside behavior, automatic polygon closing, and local computation with no network call or quota. These are meaningful behavioral traits beyond what the schema shows. It doesn't mention performance limits or error cases, but for a pure geometry predicate the disclosed traits are the important ones.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the first states purpose and use cases, the second specifies inputs and the boundary rule, the third adds the local-computation trait. No filler, no repetition of schema content.

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 two-parameter geometry predicate with a rich schema and an output schema present, the description covers the essential behavioral context: boundary handling, polygon closing, and local execution. It doesn't describe the output format, but the output schema exists, so that's not required. A small gap is not mentioning what happens with invalid polygons (e.g., self-intersection), but that's minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters thoroughly, including the GeoJSON [lon, lat] array alternative. The description adds the '3+ coordinates' requirement and the auto-closing behavior, which are useful, but most parameter meaning is already in the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Whether a coordinate lies inside a polygon', then lists concrete use cases (delivery zones, catchments, congestion/clean-air zones, site boundaries). This clearly distinguishes it from sibling geo tools like geo_distance, geo_centroid, or geo_area, which answer different spatial questions.

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 states the exact inputs needed ('Provide point {lat, lon} and polygon as 3+ {lat, lon} coordinates') and clarifies the boundary rule ('Points exactly on the boundary count as OUTSIDE'). It doesn't explicitly name sibling alternatives or say when not to use it, but the use-case list and local-computation note give enough context for an agent to select it appropriately.

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 provided, the description carries the full burden of behavioral disclosure. It discloses unit semantics (degrees not metres), an approximate conversion to metres, endpoint preservation, return contents, and the fact that computation is local with no network call or quota. This is unusually thorough and lets an agent predict side effects and cost.

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 carry the essential information: purpose, unit warning, endpoint behavior, returns, and local computation. The most critical caveat (degrees not metres) is front-loaded, and every sentence earns its place without redundant prose.

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 two-parameter tool with an output schema, the description covers all agent-critical aspects: purpose, input units with magnitude intuition, endpoint guarantee, return shape, and execution characteristics. An agent has everything needed to invoke it correctly; any remaining details, such as coordinate format variants, are already fully handled by the rich input 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?

The input schema already describes both parameters with 100% coverage, so the baseline is 3. The description adds genuine value beyond the schema by quantifying the tolerance in real-world terms ('0.0001 drops detail finer than roughly 10 m at the equator') and by clarifying that endpoints are always kept, which affects how the points parameter is interpreted.

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 ('Reduce the number of coordinates') and a concrete resource ('a polyline') while naming the algorithm (Douglas-Peucker). This clearly distinguishes it from sibling geo tools like geo_length or geo_area, which perform different operations on geometries.

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 clear context: this tool is for reducing coordinate density while preserving shape. It implies when to use it, though it does not explicitly name alternatives or state when not to use it. For a tool with a specialized geographic purpose, that context is sufficient for an agent to choose it over 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?

No annotations are present, so the description carries full responsibility and satisfies it thoroughly. It discloses status values, the terminal flag semantics, metering/refund behavior, the NOT FOUND rather than forbidden privacy behavior, and the gateway requirement.

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 longer than average but every sentence contributes behavioral or operational context. The rationale-laden sections on free polling and refund reporting are slightly verbose, but they are purposeful and help an agent trust the behavior rather than ration calls.

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 single-parameter read tool with an output schema available, the description covers everything an agent needs: how to obtain the id, what statuses exist, how to know when to stop polling, cost implications, and auth/privacy edge cases. No critical gap remains.

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% for the id parameter, so the baseline is 3. The description adds meaningful semantics beyond the schema: the id must come from submit_optimise_job and belongs to the submitting key, with a privacy-motivated NOT FOUND response for foreign ids.

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 (read), a resource (asynchronous job from submit_optimise_job), and the exact payload (status, result inline, body the synchronous tool would return). This clearly distinguishes it from submission and other sibling tools.

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 when to call this tool (after submitting a job, while polling), how often to poll (every few seconds), and what to check (the terminal field). It also explicitly dismisses webhooks as unsuitable for agent loops, giving clear when-not 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?

No annotations are provided, so the description carries the behavioral burden. It does convey read-only intent through 'Fetch' and 'inspect before editing,' and it usefully distinguishes the editable theme document from the compiled style. However, it does not explicitly state side-effect-free behavior, permission requirements, or error handling, leaving some transparency gaps.

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 main fetch action is front-loaded, and the second sentence adds practical guidance. Every word earns 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 single-required-parameter read operation with an output schema present, the description is largely self-sufficient. It explains the two outputs and the intended editing context, though it could name related sibling tools or explicitly confirm the operation is non-mutating.

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%, including an explicit example for style_id. The description adds only a mild hosted-style framing and does not meaningfully enhance understanding 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 uses a specific verb ('Fetch') and names precise resources: the latest theme document and the URL of the compiled MapLibre style. It also ties the tool to an inspection-before-editing workflow, which clearly differentiates it from editing-focused siblings like set_palette and set_layer_paint.

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 clear usage context: use the theme to inspect current palette and layer overrides before editing. It does not explicitly name alternatives or state when not to use the tool, but the intended workflow is evident.

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 provided, the description carries the full burden, and it does so thoroughly. It discloses that the call costs no quota, that figures are weighted units rather than raw request counts, that identity_pooled may make the numbers shared across keys, and that only the authenticating key's usage can be read. It also warns against misreporting units as calls.

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 longer than a minimal one, but every extra sentence addresses a real interpretation risk: units vs. calls, pooled quota, and inability to query other keys. It is front-loaded with purpose and cost, then moves through parameters, return semantics, and caveats in a logical 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 two-optional-parameter read tool with an output schema, the description is exceptionally complete. It covers purpose, cost, default ranges, date-bound behavior, output semantics, unit weighting, pooled identity, authentication key ownership, and the required gateway setup. An agent has everything needed to call and interpret this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both optional parameters including defaults, format, inclusiveness, and the 92-day cap. The description repeats and lightly contextualizes this ('bound the report; omitted, it covers the current month to date') but does not add substantial new parameter-level 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 opens with a specific verb and resource: 'Check what your own API key has spent.' It also adds a clear use case ('decide mid-task whether to keep going') and is plainly distinct from all sibling tools, which concern routing, geocoding, style, or planning rather than quota usage.

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 exactly when to use the tool: mid-task to decide whether to continue. It also gives an explicit when-not: 'there is no way to read another caller's usage,' and clarifies that reading is free, so there is no quota cost concern. No alternative tool is relevant among siblings, so no alternative routing is needed.

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

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

With no annotations, the description fully carries the behavioral burden and does so exceptionally: no model runs, lines are pre-reviewed and identical for every driver, audio is never synthesised, deliberate omissions are listed, census semantics are explained, and the cost/unit and gateway requirement are stated. This is far beyond typical disclosure.

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 long and emphatic, but nearly every sentence earns its place by preventing a specific misuse or misinterpretation. The all-caps warnings hurt readability slightly, and the single dense paragraph could be better structured, but it remains information-dense 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?

For a tool with unusual coverage limits, silent-failure semantics, and deliberate omissions, the description is complete: it covers inputs, output expectations, coverage scope, census interpretation, cost, authentication gateway, and what not to add. Since an output schema exists, the tool's return structure does not need to be spelled out in the description.

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 baseline is 3, but the description adds cross-parameter meaning: `geometry_polyline6` and `duration_s` must come from the same `route` answer, and it explains why `duration_s` changes the silence budget from a distance to a time. It reinforces defaults and the no-synthesis meaning of `voice_format` beyond the schema's isolated 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?

The description names a specific deliverable ('three to five short spoken lines an hour'), ties it to a concrete resource (the route ground and plaque inscriptions), and sharply distinguishes it from a tour or chatbot. It also states the deliberate single-corridor coverage, which prevents an agent from treating it as a general narration 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?

The description gives explicit operational context: feed it `geometry_polyline6` and `duration_s` from the same `route` answer, and interpret no-lines as a correct answer outside the Chelsea corridor. It does not name a specific sibling alternative, but 'not a tour and not a chatbot' plus the corridor coverage effectively bounds when it should be chosen.

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 does so thoroughly. It discloses that the list is sorted, identical on every call, local, offline, quota-free, and that invalid category tokens silently return empty results. This goes well beyond a simple 'list' statement and gives the agent important behavioral expectations.

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 information-dense but every sentence earns its place: what the tool lists, what each entry contains, critical usage warnings, exclusions, and determinism. The most important purpose is front-loaded, and the warnings are positioned where they are most relevant.

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-parameter tool with an output schema, the description is complete. It covers purpose, return structure, relationship to sibling tools, failure mode for invalid tokens, excluded categories, determinism, and performance characteristics. Nothing an agent needs to decide whether to call it 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 has zero parameters, so there is no parameter schema to augment; the baseline is 4. The description still explains that the output entries are exact category tokens, aliases, and descriptions, which helps the agent understand how the category value is meant to be used in sibling tools.

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: it lists canonical place categories for use with nearby_places and search_along_route. It clearly distinguishes this from sibling tools like list_style_layers by tying it to place-category tokens and related geocoding workflows. The exact 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?

The description explicitly says to read this before guessing a category, and warns that unrecognized tokens return an empty result rather than an error. It also states that cuisines, brands, and names are not categories and should be searched as free text, giving clear guidance on when not to use this tool and what to do 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 assumes the behavioral disclosure burden. It states that lookup is local, requires no network, and always works, and it discloses that attribution is enforced on compiled styles and cannot be themed away. It does not describe the output shape, but an output schema exists, so that is not required.

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 one long, information-dense sentence, but every clause contributes either a content category, a consumer tool, or a behavioral caveat. It could be split into multiple sentences for readability, but there is no filler or repetition.

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 no-argument enumeration tool with an output schema, the description fully covers the returned categories, the downstream consumers of those categories, and the notable behavioral constraints. Nothing an agent needs 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 has zero parameters, making parameter-level explanation unnecessary. The description still adds semantic value by showing how the returned identifiers plug into create_style and set_layer_paint, which is more than the empty input schema can convey.

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?

Description opens with a concrete verb–resource pair ('List everything... can style') and enumerates four distinct content categories: named bases, palette slots, skeleton layer ids, and source-layers. It references sibling tools such as create_style, set_layer_paint, and the static-map API, making it easy to distinguish from the many nearby style/route tools.

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 explains what the listed values are for: pass a base to create_style or the static-map style= parameter, and pass skeleton layer ids to set_layer_paint. It does not explicitly frame when to use this tool over alternatives like get_style, but the usage context is clear and no exclusions are needed.

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 full burden of behavioral disclosure, and it does so thoroughly. It explains what is returned (snapped roads, not raw points), the roll-up caveat that segments need not sum exactly to distance_m, that unknown admin/surface areas are omitted rather than guessed, and the hard dependency on the MapMap gateway with no fallback. This is exemplary transparency for a complex 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 long but information-dense; every sentence adds operational or semantic value, including the honesty caveat and gateway requirement. It front-loads the core purpose and then layers in invocation details, output semantics, and limitations. Slightly verbose, but no filler—each clause earns 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 tool with three parameters, no annotations, and a rich output schema, the description is complete: it covers input formats, parameter interplay, output symbols, aggregation caveats, unknown-value handling, and the required gateway configuration. An agent has enough context to call it correctly and interpret results, even without the output schema in front of it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description adds genuine meaning beyond the schema. It clarifies that costing determines which roads the trace may match onto with a concrete example, explicitly says 'not both' for shape/encoded_polyline, and defines encoded_polyline as polyline6, the same format route and match_trace return. That extra context helps invocation without redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Snap a recorded GPS trace to the road network' and clearly explains the output is the matched path plus road-class and admin roll-ups. It explicitly distinguishes use from route planning by framing it as 'a dashcam or telematics log into a report', making it easy to tell apart from siblings like route or route_observations.

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 clear usage context: when you have a recorded trace and want to know what roads it travelled, with concrete costing guidance (a walked trace matched as 'auto' snaps to the carriageway rather than the footpath). It does not explicitly name sibling alternatives or state when not to use this tool, but the input-vs-route framing is clear enough to route an agent correctly.

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 full burden. It discloses the output format (durations_s, distances_m), the null-cell semantics for unreachable pairs, the 10,000-cell limit, and the engine-specific behavior of exclude_polygons. This is substantial behavioral context beyond the 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?

The description is dense but well-organized: it opens with the core function, then covers costing, output, limits, and the optional parameter. Every sentence adds value. It is slightly long but justified by the complexity of 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 tool's complexity (5 params, output schema, engine-specific behavior), the description covers the essential operational details: output units, null semantics, cell limit, and engine caveat. It does not explain how to interpret the output schema in detail, but the output schema exists and the description need not repeat it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics: it explains the row/column mapping of origins/destinations, the cell limit calculation, and the scenario-analysis use case for exclude_polygons. It also clarifies the coordinate order for polygons. This goes beyond the schema's field 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?

The description states a specific verb ('Compute') and resource ('travel time/distance matrix between origins (rows) and destinations (columns)'), and enumerates the supported costing modes. It clearly distinguishes this from sibling routing tools like 'route' and 'reachable_area' by focusing on the matrix structure and cell-based output.

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 clear context for when to use the tool (matrix computation, scenario analysis with exclude_polygons) and even names the engine-specific behavior (Valhalla vs GraphHopper). It does not explicitly name sibling alternatives or state when NOT to use it, but the context is strong enough for an agent to select it appropriately.

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 delivers: empty-list-not-error, case/accent-insensitive prefix matching, category normalization examples, fov_deg full-width semantics, heading fallback behavior, and out_of_view meaning. It even notes the gateway requirement. Exceptionally transparent.

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 long, but every sentence earns its place given the 8-parameter tool with complex matching/bearing logic. It front-loads the core purpose and then flows into parameter details and edge cases. A bit dense, but structurally organized and appropriately sized for the complexity.

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?

Covers input requirements, output result fields (name, distance, bearing, details), edge cases (empty list, out_of_view), and gateway prerequisites. With an output schema present, it still effectively explains all necessary call parameters and expected behavior. Nothing an agent needs 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%, so the baseline is 3. The description adds value beyond schema by clarifying the 'at least one of category or name' requirement (not in required collection), explaining the disambiguation strategy ('Lloyds' plus 'bank'), and mentioning the 'Prefer reading direction aloud' tip. Slight redundancy with schema, but meaningful extra context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Find places near a point, nearest first with distance in metres' and immediately scopes by category or name. It distinctly separates itself from geocode by explaining the proximity focus, so an agent can tell it apart from the sibling without ambiguity.

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 instructs to 'Use this instead of geocode whenever the question is about what is NEAR a location' and explains why geocode is unsuitable (returns far branches over nearby ones). This direct comparison gives clear when-to-use guidance with no left 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so comprehensively. It explains that reloads split the shift before the solve (making the plan conservative), that `max_trips` is a budget not a prediction, that relaxation runs at most one second solve and only returns the relaxed plan if it assigns more work, that breaks/capacities/skills/territories are never widened, and that the tool refuses to run when the MapMap gateway isn't configured. It also discloses billing (two solves) and the requirement to check `relaxation.relaxed_plan_used`. This is exemplary transparency.

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 long but exceptionally dense; every sentence carries actionable information. It is front-loaded with the core purpose and then logically proceeds through vehicles/jobs/shipments, costing, territories, reloads, relaxation, and emissions. There is no fluff or redundancy—each section earns its place by explaining behaviour or constraints an agent must know.

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 tool's complexity (9 parameters, nested specs, multiple optional subsystems), the description is remarkably complete. It covers input requirements, output structure (summary, unassigned, per-vehicle routes with steps), units, edge cases (unassigned tasks, relaxed plans), and failure modes (refusal without gateway). With an output schema also present, nothing an agent needs to call this tool 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?

Although schema coverage is 100% and the schema already documents each parameter, the description adds substantial meaning beyond the schema: it explains the semantic of `max_trips` as a budget, how territory bounding works, what the `relaxation` block reports, and how `emissions`/`avoid_zones` interact. It also clarifies units (seconds, metres) and response blocks. This goes far beyond the bare parameter descriptions, fully compensating for any gaps an agent might have from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb and resource: 'Optimise multi-vehicle, multi-stop delivery plans (VRP).' It immediately distinguishes itself from siblings by naming `cluster` and `submit_optimise_job` as alternatives for larger problems, and by referencing `replan_routes` for re-optimisation. The purpose is unambiguous and the scope is clear.

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 explicit when-to-use and when-not-to-use guidance, including hard limits (200 unique locations, 1,500 km matrix span) and concrete alternatives: 'cluster the stops with `cluster` and optimise each group, or submit the whole problem to the asynchronous lane with `submit_optimise_job`.' It also explains when to use optional features like reloads and relaxation, and warns about their consequences, so an agent can make an informed choice.

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 disclosure burden. It clearly discloses the output shape (ordered stops, arrival offsets, total duration/distance), round-trip behavior, and truck/costing semantics. It does not discuss error or failure behavior, but no hidden side effects or contradictions are left ambiguous.

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 sentences with the purpose front-loaded; every sentence adds required information about inputs, optional modes, costing, and output. There is no filler or redundant restating of the tool name.

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 description, combined with the detailed input schema and output schema, covers required and optional parameters, costing, truck profile, and return values. Nothing an agent needs to invoke this tool correctly is missing, and any remaining details live in 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 100%, and the schema already documents every parameter, including LatLon, OrderStopSpec, TruckSpec, and the end/round_trip mutual exclusivity. The description adds only shorthand notation and costing glosses, so it stays at the baseline 3.

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 operation ('Put a single run's stops in the best visiting order') and a concrete resource (stops with start/end). It is clear, but it does not explicitly differentiate from siblings like plan_errands or optimise_routes, so an agent must infer the scope from the phrase 'single run'.

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 communicates the single-run errand context and explains costing choices, but it never states when to prefer this tool over route, optimise_routes, or plan_errands, nor when not to use it. Usage guidance is therefore implied rather than explicit.

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 bears the full burden of behavioral disclosure, and it delivers: it explains the three visibility verdicts, instructs the agent to read the visibility block before speaking, warns that `unknown` must not be reported as visible, explains `basis`, `out_of_sector`, `coverage`, `caveat`, and the model's limits (trees, walls, scaffolding, weather). It even mentions the required MapMap gateway. This is exemplary transparency.

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 long but every clause earns its place: purpose, examples, sibling routing, parameter defaults, output-reading rules, and caveats are all packed densely without repetition. The most important direction semantics and visibility-reading instructions are front-loaded, and the auth requirement is saved for the end. Nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 10 parameters, an output schema, no annotations, and subtle output semantics, the description is complete: it tells the agent what inputs to supply, what the key output fields mean, how to react to `unknown` and `out_of_sector`, what the standing limitations are, and what infrastructure is required. An agent has everything needed to invoke 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 coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics beyond the schema: `bearing_deg` is clockwise from true north, `fov_deg` is the FULL cone width (30 degrees either side of default), `eye_height_m` has a standing-adult default, and `category=building` is a named-building shortcut. It doesn't explicitly discuss `visible_only` or `limit`, but the schema documents those well, so the added value receives a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific, memorable framing—'What is over THERE'—and states the exact inputs (position, facing direction) and outputs (places in the cone, visibility verdicts). It also explicitly names the sibling it is not: `nearby_places`. This makes the tool's identity and scope immediately distinguishable.

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 concrete example queries ('what is that over there', 'is there a pub in that direction') and an explicit routing rule: use `nearby_places` when the question is about proximity rather than direction. It also tells the agent that `category=building` reaches named buildings and warns about reading `out_of_sector`. The when-to-use guidance is 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?

With no annotations, the description carries the full burden. It discloses key behaviors: geocoding fallback, ambiguous resolution handling, VROOM optimisation, truck ADR restrictions, absolute ETAs with depart_at, and return geometry as polyline6. It also warns about ambiguous geocoding and tells the agent to re-run with explicit coordinates. This is strong behavioral disclosure beyond the 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?

The description is dense but well-organized: it front-loads the core purpose, then walks through parameters in a logical order, and ends with the geocoding caveat. Every sentence adds information. It's slightly long but justified given the tool's complexity and the absence of 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?

The tool has 7 parameters, an output schema, and no annotations. The description covers the main behaviors, return values, and edge cases (ambiguous geocoding). It doesn't mention error conditions (e.g., what happens if optimise is requested without the sidecar, or if truck is supplied without costing 'truck'), but the schema already notes the sidecar requirement. Overall, it's complete enough for an agent to call 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 coverage is 100%, so the baseline is 3. The description adds value by explaining how parameters interact: start + stops, dwell_minutes shifting ETAs, optimise reordering via VROOM, truck profile affecting the whole day, and depart_at enabling absolute ETAs. It also clarifies the return_to_start behavior. This goes beyond the schema's individual field 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?

The description opens with a specific verb and resource: 'Turn an itinerary into one navigable multi-stop route.' It clearly distinguishes this from siblings like route, optimise_routes, order_stops, and plan_errands by focusing on a full day's itinerary with stops, dwell times, costing, and return-to-start. The scope 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?

The description implies when to use it (planning a multi-stop day) and contrasts with alternatives by mentioning the VROOM solver and costing options. It doesn't explicitly say 'use X instead when...' but the context is clear enough for an agent to select it over route or optimise_routes. A small gap: no explicit exclusion of single-leg routing or when to prefer plan_errands.

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 does so richly: feasible:false is an answer not an error, blocking_errand/over_by_s/dropped semantics, hours being evidence not promise, closed places never proposed, stop provenance, usage_note, and gateway requirement. This goes well beyond a generic 'plans errands' statement.

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?

Long but dense and front-loaded with purpose and example, followed by critical call semantics and warnings. No filler; every sentence adds operational or safety 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?

For a complex 7-parameter tool with no annotations, it covers required inputs, optional inputs, output semantics, failure semantics, safety, and environmental dependency. An output schema exists for return values, so not restating them is appropriate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds meaning: convert colloquial times to RFC 3339 yourself, resolve named places via geocode before passing coordinates, use list_place_categories, 1-5 errands, dwell default 5. It does not mention max_detour_minutes, but the schema already documents it.

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 the verb+resource precisely: 'Order a handful of errands against a hard arrival time, and say honestly whether they fit.' The example ('pick up a prescription...') and domain-specific framing separate it from sibling routing/planning tools like route, order_stops, or plan_day.

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 operational context: use list_place_categories for vocabulary, geocode named places first, don't do ordering or arithmetic yourself, and never at the wheel. It does not explicitly name sibling alternatives or exclusions, but the when-not ('planned before setting off or by a passenger, never at the wheel') and task-specific framing are 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?

With no annotations provided, the description fully carries the behavioral burden, and it does so exceptionally. It discloses the charging-curve integration model, the critical `feasible: false`/`reason` behavior as an answer rather than a retryable error, `gradient_data` caveats, the need to always display `coverage_note`, the `availability_live` freshness condition, the MapMap gateway dependency, and the display requirement for `charging_attribution`. This goes far beyond the schema and gives an agent actionable expectations.

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 long but every sentence carries important operational information: inputs, model assumptions, infeasible-result handling, data caveats, and display instructions. It is front-loaded with the purpose and then packs in critical warnings. It could be better structured with bullets for the caveats, but for a tool with this complexity, the length is justified and not 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?

Given the tool's complexity, the high number of parameters, the existence of an output schema, and the absence of annotations, the description is remarkably complete. It covers inputs, vehicle semantics, failure modes, data quality caveats, live-status conditions, deployment prerequisites, and output display requirements. An agent has enough context to call the tool correctly and interpret results sensibly.

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 baseline is 3. The description adds extra semantic value by explaining relationships and defaults: 'reserve_soc' as the mid-route floor, vehicle profiles versus inline overrides, connector/min_kw filtering, and the key modeling caveat that charge time is integrated over the charging curve rather than energy divided by peak power. This is more than the schema provides, though not every parameter is individually elaborated in prose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Plan a whole electric-vehicle journey, charge stops included.' This clearly distinguishes it from generic routing tools like `route` or `optimise_routes` by emphasizing EV-specific charge-stop planning. It also covers the core inputs and output at a glance, so an agent can immediately identify what the tool does.

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 clear context for when to use the tool: planning a full EV journey with charge stops, vehicle specification, and charging constraints. It does not explicitly name sibling alternatives or say 'use route instead when no charging is needed,' so it stops short of a 5. However, the context is specific enough that an agent would not confuse this with non-EV routing tools.

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

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

No annotations exist, so the description carries the full burden, and it delivers: it discloses the return format (GeoJSON FeatureCollection, one feature per contour), the line-vs-polygon output switch, longitude-first coordinate ordering, and the critical engine caveat that exclude_polygons is silently ignored on GraphHopper. It stops short of discussing error conditions or performance, but these are minor for a read-only compute 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?

Front-loaded with the core purpose, then flows logically through costing, contours, polygons, exclusion, and engine caveat. Every sentence earns its place for a 5-parameter tool, though the exclude_polygons section is somewhat dense and partially mirrors schema text.

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 an output schema exists, 100% parameter coverage, and the tool's read-only nature, the description covers purpose, parameter intent, return format, and cross-engine behavior. The main gap is the absence of an explicit safety/read-only statement, which matters more because no annotations were provided.

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%, setting baseline at 3, and the description adds real value above it: it maps each costing enum value to an intent, explains polygons as a map-rendering convenience, and gives the exclude_polygons scenario meaning beyond the schema's literal definition.

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: 'Compute the area reachable from an origin within one or more travel-time budgets' and immediately grounds it with 'walkability/cyclability rings'. This clearly distinguishes it from siblings like route, matrix, nearby_places, and geo_area — no other sibling computes isochrones.

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 usage context: translates costing modes into user questions ('how far can I walk in 15 minutes?'), names delivery coverage as an auto/truck use case, and frames exclude_polygons as a before/after scenario ('close this bridge and recompute reachability'). However, it never explicitly names sibling tools or states when to prefer route/matrix 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It transparently explains that nothing is stored server-side, that the call is reproducible, that completed stops are locked by construction, that multi-trip problems are refused, that billing is on the remaining problem, and that the MapMap gateway is required.

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 long, but the tool is complex and no annotations or short schema can carry the needed context. It is front-loaded with the core purpose and major constraints, though the single-block prose style and some rhetorical flourishes add length without much structural aid.

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 a full output schema, the description is unusually complete. It covers prerequisites, input requirements, failure modes, response contents, limitations, and billing. An agent has everything needed to decide when to call it and how to construct a valid request.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful cross-parameter semantics beyond the schema: the original `optimise_routes` problem must be passed in full, at least one progress entry or change is required, `completed_stop_ids` are a locked prefix, and vehicles declaring `reloads` cannot be re-planned.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action and resource: "Re-plan a fleet part-way through its shift." It clearly distinguishes this from `optimise_routes` by explaining that the original problem plus `progress` and/or `changes` is sent back and a fresh plan for remaining work is returned.

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 explicit when-to-use context and clear exclusions: at least one progress entry or change is required, multi-trip vehicles cannot be re-planned, and a re-plan reporting nothing new is essentially the original problem. It references `optimise_routes` as the source of the problem shape but does not explicitly name an alternative tool to use 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 provided, the description carries the full burden and delivers: it discloses that the action is queued for human/agent review, NEVER changes routing immediately, and NEVER edits any map. It also states it returns the queued report_id. This fully informs the agent of the asynchronous, non-mutating nature of the call, which is critical for a reporting 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 front-loaded with the purpose, then gives usage instructions, then behavioral caveats. It is a bit longer than strictly necessary but every sentence contributes (categories, parameters, non-mutating guarantee, return value). It is well-structured and not redundant with the schema.

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 has 5 parameters (2 required) and a non-trivial LatLon type, but the schema fully documents them. The description adds the essential behavioral context (queued, non-mutating) and the return value. It does not describe error cases or the exact shape of the response beyond report_id, but that is sufficient for an agent to call it correctly. Minor gap: it does not mention that the array form of location uses longitude-first, but the schema does.

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% – every parameter and enum has a description, so the schema already carries the semantic weight. The description merely restates the required fields and lists the category enum values, adding no new meaning. It even says 'Provide `location` {lat, lon}' while the schema also allows a GeoJSON [lon, lat] array, which could slightly mislead, but the schema clarifies it. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Report that the live world disagrees with the map' and enumerates concrete mismatch types (closed road, wrong restriction, etc.). It is immediately distinct from all sibling tools, which are routing/geo utilities, and no other tool on the list performs reporting. The purpose is unambiguous and scoped.

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 explicitly states when to use it: 'Use it when you observe the mismatch mid-task.' It does not name alternatives because none exist among siblings, but it does clarify the tool is for first-party observations and that reports are queued, implying it is not for immediate routing changes. The context is clear, though it lacks an explicit 'do not use when…' clause.

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 provided, the description carries the full burden of behavioral disclosure and exceeds it. It details the output structure (name, label, lat/lon, type, address parts, distance_m, categories, details object, bearing_deg, direction), dynamic behavior (heading-based relative_bearing_deg, FOV-based out_of_view count), and even advises to 'Prefer reading direction aloud over coordinates.' This is exceptionally transparent about how the tool behaves across different inputs.

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 well-structured and front-loaded with purpose, then logically flows into output details, heading behavior, FOV, and a recommendation. However, it repeats the 'FULL width' explanation of fov_deg that already exists verbatim the schema description, and it restates the default/max for limit that is also in the schema. While not wasteful, these redundancies could be trimmed without losing value. The density is justified by complexity but slightly over-lengthy.

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?

This is a complex tool with 5 parameters and rich output behavior, and the description covers everything an agent needs: input requirements, output field descriptions, edge cases (FOV without heading), fallback behavior (cardinals vs relative), and even a usability recommendation. The output schema exists but the description still explains return fields in detail, which is helpful. No gaps are evident for correct invocation and interpretation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds substantial semantic value beyond the schema. It explains the interplay between fov_deg and heading_deg (a cone must point somewhere), the full-width vs. half-width interpretation of fov_deg, the default/max for limit, and the meaning of signed relative_bearing_deg. It also clarifies that out_of_view reports dropped results, which is not in the schema property descriptions. This enriches parameter understanding significantly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Turn coordinates into the nearest places: addresses, POIs and localities with distance in metres.' It explicitly frames itself as 'The inverse of geocode,' immediately distinguishing it from the sibling tool. This gives an agent a precise understanding of what it does and how it relates to geocode.

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 explicitly names geocode as the inverse, which guides when to use this tool. It also explains two usage modes (with or without heading_deg) and how that changes output phrasing. However, it does not mention any other sibling tools like nearby_places, nor does it state when NOT to use this tool. The inverse reference and mode explanations provide strong contextual guidance, but exclusions are absent.

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 does so exhaustively: gateway/auth requirements (GATEWAY_URL + GATEWAY_API_KEY), which flags incur extra metered route calls and their caps, the honest limits of `avoid` (Dartford Crossing example) vs `exclude`, ADR tunnel-flag caveats, and the distinction between 'no prettier way' and 'could not look'. This is unusually complete behavioral disclosure.

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 enormous prose block covering a dozen optional flags with no headers, bullets, or ordering by importance. Individual sentences are informative, but the structure forces the reader to parse a wall of text to find the core call, and much of the detail duplicates the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter routing tool with a nested schema and an output schema, the description leaves nothing an agent would need uncovered: costing semantics, ADR honesty, zone pricing, scenic/rationale cost models, and engine-specific limitations (Valhalla vs GraphHopper). It is complete to the point of excess.

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's own $defs already document every parameter (TruckSpec, BicycleSpec, PreferredSideKind, etc.) in depth. The description largely restates that material, adding little semantic detail the schema lacks, so the baseline of 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?

Opens with a specific verb+resource+scope: 'Compute a turn-by-turn route between origin and destination (optionally via waypoints).' An agent immediately knows this is the routing primitive, distinct from siblings like optimise_routes or reachable_area. It never names an alternative sibling explicitly, 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?

Rich conditional guidance: 'Use `exclude` when you mean a ban', 'scenic: true (auto costing only)', eligibility rules for avoid features, and repeated warnings about opt-in metered cost. However it gives no guidance on choosing this tool over routing-adjacent siblings (plan_ev_route, optimise_routes), so it lacks an explicit alternatives clause.

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 is exceptionally transparent. It discloses that the tool is a query and triggers nothing, costs 10 units flat, requires the MapMap gateway, and returns 501 without an archive. It also explains the silence-budget design, coverage semantics, deliberate exclusions like hills and junction numbers, and the meaning of `offset_m`.

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 long, but almost every sentence adds operational value, from budget behavior to coverage caveats to error conditions. It is front-loaded with purpose and then structured into distinct behaviors. The rhetorical framing is slightly excessive but not redundant.

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 description covers input provenance, output observation fields, the meaning of empty results with `tiles_read` and `uncovered_m`, cost, authentication via gateway environment variables, and error behavior. For a tool with four parameters and no annotations, nothing essential 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%, so the baseline is 3. The description repeats the parameter names and emphasizes passing `geometry_polyline6` straight from the route tool, but it does not add meaning beyond what the schema already provides. It therefore meets the baseline but does not exceed it.

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 precisely what the tool produces: spoken-style observations of what a journey passes, including rivers, roads, settlements, landscapes, and elevation, each tagged with a position. It also distinguishes itself from `route` by warning that none of this information is present in a route's movement list.

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 clear context: this tool annotates an already-chosen route, and `geometry_polyline6` must come directly from the `route` tool. It also gives an explicit when-not by saying 'a route is a list of movements and a river crossing is not a movement, so do not try to read it out of route's answer.' However, it does not explicitly name or compare alternatives such as `search_along_route`.

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