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 carries the full burden and does so unusually well: it discloses coverage limitations (no national registry, per-deployment operator scope, always show coverage_note), the meaning of an empty results set, availability staleness semantics (live only when availability_live is true), the refusal behaviour of available_only, gateway/dataset prerequisites, and how ranking and costing work. These are exactly the operational traits an agent cannot derive from 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 core purpose and input modes are front-loaded in the first sentence, and the density is high with little filler apart from the aphorism about kilowatts. It is on the long side for a tool description and mixes result-field enumeration with invocation guidance, but almost every sentence conveys actionable 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 10 parameters, no required fields, a rich schema, an output schema, and no annotations, the description covers everything an agent needs: input-mode selection, filtering semantics, coverage and staleness caveats, error conditions, the `say` field contract, and attribution requirements. Return fields are listed even though an output schema exists, which is mildly redundant but not a gap.

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

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

Schema description coverage is already 100%, so the schema does the heavy lifting and a 3 would be the baseline. The description adds real meaning on top: it enumerates the connector tokens inline, explains min_kw's intent (e.g. 50 for rapid only), gives max_detour_minutes' default and cap context, and clarifies that a truck profile makes detours respect dimensional/ADR restrictions and requires costing "truck".

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 precise verb and resource — find EV charge points along a route — and adds the distinguishing scope that detours are costed through the routing engine rather than estimated as straight lines, which is genuinely differentiating. However, it never names or contrasts against the obvious siblings that could be confused with it, notably plan_ev_route and cheapest_fuel_along_route, so an agent must infer the boundary itself.

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

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

It clearly states the input modes (origin+destination, or an existing route's geometry_polyline6, explicitly not both) and gives concrete filter conditions such as available_only requiring a live feed and being refused otherwise. It also tells the agent to prefer the returned `say` verbatim and to display charging_attribution. What is missing is any explicit when-not or alternative-tool routing against siblings like plan_ev_route or search_along_route.

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

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

With no annotations, the description carries the full burden and does so richly: it defines the ranking rule (freshest-priced first, cheapest within), the exact meaning of `stale` including the missing-timestamp case, the rule that a stale price is never the baseline and carries no saving, the attribution requirement, and the always-present `say` line. 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?

The purpose and the key differentiator are front-loaded, and the dense single paragraph mostly earns its length by covering stale semantics and the `say` contract. It is a long, information-dense block, and some clauses (fuel lists, attribution details) could be trimmed, but little is truly wasteful.

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

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

An output schema exists, so return values needn't be spelled out, yet the description still orients the agent on the important result fields (price, detour, saving, stale) and the `say` field's role. Combined with the routing, ranking, and dataset-prerequisite context, an agent has everything needed to call it correctly and interpret the answer.

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 goes beyond it by explaining that `truck` requires costing 'truck' and how it affects detours, that `geometry_polyline6` is the `route` tool's field and is mutually exclusive with origin/destination, the fuel default and aliases, and the effect of `fill_litres`. It adds real semantic relationships rather than restating types.

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 ('Find the cheapest fuel along a route') and immediately qualifies it with a distinguishing trait ('REAL extra travel time of stopping at each station, never a straight-line guess'). This clearly separates it from the sibling cheapest_charging_along_route and the generic route 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?

Gives explicit input alternatives ('Provide origin + destination ... or an existing route's geometry_polyline6'), states defaults for fuel and max_detour_minutes, and notes the gateway/dataset prerequisite with its error behavior. It does not explicitly name when to prefer a sibling (e.g. cheapest_charging_along_route for EVs), so it stops short of full routing guidance.

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

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

With no annotations, the description carries the behavioral burden and does so well: it discloses the conservative worst-case reading (over-restrict, never under-restrict), that no network access is needed, and that it answers instantly. It omits only peripheral details like negation semantics of a blocked vs permitted result.

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

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

Four tight sentences, front-loaded with the purpose, then inputs, then behavioral caveats. No wasted filler; slightly dense but appropriately sized.

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

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

An output schema exists so return values need not be explained, and the description covers inputs, edge cases (unknown code), and behavioral semantics thoroughly enough for a stateless, no-annotation check tool.

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 genuine value beyond the schema by giving example tunnel codes ("B", "C5000D", "B/D", "none") and the conservative default for an unknown code, clarifying real input expectations.

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 (check) and resource (tunnel passage) with the ADR category range, and the hazmat/ADR framing clearly separates it from geometric siblings like check_clearance_on_route. An agent can identify the operation 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 input guidance (provide hazmat, and the tunnel code when known), which implies usage, but never states when to reach for this tool versus alternatives such as check_clearance_on_route or route. Usage context is implied rather than spelled out.

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

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

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 delivers: it discloses that distances ignore the road network, that the answer carries a `basis` sentence that should be shown to the user, deterministic seeding across deployments, a MapMap gateway requirement, and that a load ceiling is a bin-packing problem that may have no solution. This is unusually rich behavioral context.

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

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

Purpose is front-loaded, then the critical straight-line caveat, then the input contract and return shape. It is long and occasionally repetitive (the straight-line limitation is restated), but nearly every sentence carries decision-relevant 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 6-parameter tool with an output schema, the description covers the sequencing recipe, the clustering limitation, the constraint modes, determinism, and the gateway requirement. An agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds cross-parameter meaning: the exactly-one-of constraint across `clusters`/`max_cluster_locations`/`max_cluster_load`, how `territories` isolates clustering, and how `seed` guarantees reproducibility. It goes beyond per-field schema 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?

States a specific verb and resource ('Group stops into balanced geographic clusters') and immediately scopes it as straight-line clustering. It explicitly distinguishes itself from `optimise_routes` and from order-deciding tools, so an agent can place it against siblings without opening a schema.

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

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

Gives explicit when-to-use ('front half of the recipe for a thousand-stop day'), the alternative and sequencing ('then call `optimise_routes` per cluster'), and an explicit when-not ('wrong one for deciding what ORDER to visit them in'). Nothing is 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 and does it well: it describes merge precedence (base laid down first, theme merged over), the no-argument default theme, and the worldview side effect on label naming. It does not cover persistence/ownership or any auth requirements for a 'hosted' write, leaving a small gap.

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-loads the purpose in the first sentence and then packs merge semantics, defaults, worldview, and return values into one dense paragraph. It is on the long side and could be split, but nearly every clause carries information an agent needs.

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 a write tool with no annotations and an output schema present, the description supplies everything needed to invoke it correctly: required vs optional inputs, composition/merge rules, default behavior, worldview options, and the returned style_id/URL chain to sibling tools.

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 genuine meaning: it enumerates the concrete base names (light, dark, streets, midnight, navigator-day, fleet, outdoor, dataviz, backdrop, print), spells out the theme document shape (base/palette/layers with slot: colour semantics), and gives the accepted worldview codes with their effect on labels.

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 ('Create a hosted map style') and immediately distinguishes itself from siblings like get_style, set_palette, set_layer_paint by describing creation plus what it returns. An agent can tell this is the style-creation entry point without reading further.

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?

Explains the composing cases clearly: base alone, theme alone, base+theme combined ('streets with darker water is one call'), and neither (default theme). It also points to list_style_layers for the catalogue and names set_palette/set_layer_paint as the follow-up tools. It stops short of stating explicit exclusions such as when to modify an existing style instead of creating one.

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 behavioral burden and does so well: it discloses ordering of results, that elevation_m is null rather than guessed where DEM coverage is absent, and that the polyline form returns resampled lat/lon plus cumulative range_km. It omits auth/rate-limit or failure-mode info, keeping it short of a 5.

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

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

Three dense sentences, front-loaded with the core action, then mode selection, then return semantics. No filler or redundancy with the title.

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

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

For a 3-param read tool with an output schema and full schema coverage, the description supplies the one genuinely agent-relevant behavior not captured elsewhere: how missing coverage is represented (null, never a guess) and result ordering. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema already states the mutual exclusivity and that resampling is ignored for points. The description reinforces this ('a bare list of coordinates') but adds little semantic detail beyond the structured fields, 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 ('Sample terrain elevation') and immediately names the two distinct sampling modes it supports. An agent can distinguish it from route/weather siblings 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?

Explicitly states the mutually exclusive usage condition ('Provide points ... or encoded_polyline ... not both') and what resample_distance_m applies to. It does not name alternative tools for related needs, but within this tool 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?

No annotations are provided, so the description carries the full burden and does so thoroughly: gateway dependency, data provenance (USGS, NASA FIRMS), freshness windows, the volcano-only monitoring limitation, fire cells being unconfirmed heat rather than confirmed fires, and revision warnings. These are exactly the behavioral traits an agent needs and which annotations would otherwise cover.

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

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

Purpose and bbox format are front-loaded and the dense caveats stay on-topic; nothing reads as filler. It is long and heavily packed, but each clause (attribution, acknowledgment, disclaimer requirements) 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?

With an output schema present, return-value detail is unnecessary, and the description instead supplies the non-schema essentials: gateway requirement, caveats about data reliability, status propagation, and required attribution text. Nothing an agent needs to call or responsibly relay this tool 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 bbox format, defaults, ranges and ordering; the description mostly restates these (bbox WGS84, defaults, quakes-only min_magnitude). It adds little semantics beyond the schema, so the baseline of 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?

Names a specific resource (earthquake/volcano/fire events) with an explicit spatial scope (bounding box) and a stated intent (for display). An agent can distinguish it from geo_bbox or space_weather_now without opening any schema.

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

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

Gives clear usage context and exclusions: 'for display, not a warning service and not safety-critical', and instructs that stale/unknown status must be passed on rather than presented as current. It does not name an alternative sibling to use instead, so it falls short of an explicit routing rule.

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

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

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?

No annotations, but the description carries the full burden well: it explains that components are hard requirements rather than ranking hints, that an invalid country is refused not silently ignored, that a bare city name lists airports/stations first, and that match/score_gap must be read before acting on an address. These are precisely the non-obvious behavioral traits an agent needs.

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 verb and resource, then builds through input modes and output interpretation. Dense but every sentence earns its place; slightly long, but the compression is intentional and mostly readable.

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

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

Given 9 params and output schema present, the description covers input semantics, result interpretation (match, score_gap, backend), and language behavior. It does not detail every output field, but the output schema covers that. 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 baseline is 3, but the description adds real semantic value beyond the schema: it explains the two input modes combine, that components are REQUIREMENTS not hints, the country format, and that bare city names surface airports/stations. The match/score_gap guidance is output-level, but limit/x default behavior is confirmed too.

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?

Specific verb+resource: 'Turn a place (address, POI, town) into coordinates.' Explicitly distinguishes itself from reverse_geocode (opposite direction) and points the agent at verify_places for checking addresses. No ambiguity against siblings.

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

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

Gives concrete when-to-use: pass components when the address already arrives in parts (form, CRM row, manifest); use verify_places instead when the address came from a model or user and needs verification. Also explains when to prefer query over components based on whether the input is free text or already structured.

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?

No annotations are provided, so the description carries the full burden, and it delivers the two facts an agent most needs: the computation is local with no network call and no quota, and the result is geodesic rather than routed. It does not discuss precision, edge cases (antipodal points), or units of the return value, but the output schema covers the return shape.

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

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

Three short sentences, front-loaded with the core definition, then the disambiguation, then the operational caveat. Every sentence carries distinct information and none is filler.

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

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

For a two-parameter pure-computation tool with a full output schema, the description covers purpose, unit, semantics, sibling routing, and cost profile. 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 description coverage is 100% and the nested LatLon definition thoroughly documents the coordinate formats, including the longitude-first GeoJSON array ordering. The description only says 'two coordinates' and adds no semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific resource (distance in metres between two coordinates) and immediately scopes it as geodesic straight-line distance on WGS84. It explicitly names the sibling tools that do something different (`route`, `matrix`), so an agent can distinguish it without opening a schema.

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

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

Gives both sides of the routing decision: use this for as-the-crow-flies distance, use `route` or `matrix` for travel distance and time. The condition that selects this tool versus the alternatives is stated directly rather than implied.

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 load and does well by disclosing that this is a local, quota-free computation and that the result is summed geodesically rather than routed. It could say more about edge cases such as antimeridian handling or minimum-point validation, but the core behavior is clear.

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

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

Three short sentences, front-loaded with the core computation and followed immediately by the key routing distinction and execution context. There is no filler, and everything needed is easy to scan.

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 geometry tool with an output schema and rich nested schema definitions, the description supplies everything an agent needs: what is measured, how it differs from `route`, units, and that there is no network or quota impact.

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 `points` structure, coordinate formats, and coordinate order are already fully documented in the schema. The description adds useful semantic context by specifying that a polyline requires 2+ coordinates and that measurements are geodesic, going beyond the schema’s brief 'The coordinates to consider.'

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 computed quantity: total polyline length in metres, summed geodesically, for a supplied set of 2+ coordinates. It also explicitly distinguishes this from a driven route by naming `route` as the correct alternative, which is the main sibling confusion.

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 when-not rule: use `route` for driven routes, while this tool measures the line you supply. It also states a key usage condition: local computation with no network call and no 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?

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?

With no annotations, the description carries the full burden and delivers: reads are unmetered while the submission is charged, `units_charged`/`refunded` semantics on failure, and strict ownership rules where another key's id returns NOT FOUND rather than forbidden to avoid disclosing existence. These are non-obvious gateway behaviors an agent could not infer from 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?

Purpose is front-loaded and almost every clause adds operational value, but the justification of the free-polling design ('a poll that costs quota is a poll a caller rations...') runs two clauses longer than the guidance it supports. Dense and useful, slightly discursive.

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

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

An output schema exists, yet the description still explains the state machine (`queued`/`running`/`succeeded`/`failed`), the `terminal` polling signal, and the charge/refund fields in a way an agent can act on. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% with a single required `id`, and the schema already says it comes from `submit_optimise_job`. The description adds no format, validation, or expiry detail about the id beyond that, so this is the standard baseline when the schema does the work.

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

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

States a specific verb+resource ('Read an asynchronous job submitted with `submit_optimise_job`') and names the sibling that creates such jobs. It goes further by specifying exactly what is returned (status, then result inline identical to the synchronous tool), so the agent knows the contract 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?

Explicit when and how: poll while `terminal` is false, check every few seconds rather than guessing a duration, and it names the alternative (webhooks) while excluding it for agents in a loop. This is a textbook when/when-not/alternative routing statement.

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

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

No annotations are provided, so the description carries the full behavioral burden. "Fetch" implies a read-only operation and it clarifies that the theme document is the editable source while the MapLibre style is a compiled artifact, but there is no explicit statement about side effects, permissions, or rate limits.

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

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

Two tight sentences with zero filler, front-loading what is returned before the usage hint. Every 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?

With one fully documented parameter and an output schema covering return values, the description is essentially complete for an agent to call it correctly. It omits error/not-found behavior and any sibling routing, which are minor gaps for a simple fetch.

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

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

Schema coverage is 100% and the single style_id parameter is already documented with a concrete example, so the schema does the heavy lifting. The description adds no syntax, format, or default details beyond what the schema provides, making the baseline 3 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?

States a specific verb (Fetch) and a precisely scoped resource (a hosted style's latest theme document plus the URL of its latest compiled MapLibre style). This cleanly separates it from siblings like create_style, set_palette, list_style_layers, and check_style_contrast 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?

"Use the theme to inspect current palette and layer overrides before editing" gives a clear read-before-write workflow context. It does not name alternative tools (e.g. list_style_layers) or state when not to use it, so it stops short of full when/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?

With no annotations, the description carries the full behavioral burden and does so richly: reading is free and consumes no quota, the authenticating key is the only key reported, pooled quota (identity_pooled) may include other keys, and it requires the MapMap gateway env vars. It also clarifies that units are weighted, not call counts, which is a critical behavioral caveat.

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 dense and front-loaded, leading with the purpose and cost profile before parameters and return semantics. The sentences are long but each carries distinct, non-redundant information, though the return-field enumeration partly duplicates the 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?

For a read-only reporting tool, it covers purpose, cost model, range constraints, quota semantics, and auth requirements. Since an output schema exists, its description of return fields is supplementary rather than required, and nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both optional params including the YYYY-MM-DD UTC format and 92-day cap. The description restates these rather than adding new syntax or format meaning, 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?

The description names a specific verb+resource ('Check what your own API key has spent') and immediately frames the scope (self-usage only, no other caller's usage). No sibling tool covers this domain, so there is nothing to confuse it with, and the purpose is unambiguous.

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

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

It states the motivating context clearly ('so you can decide mid-task whether to keep going') and highlights the free/non-quota nature that would drive selection. It stops short of naming an explicit alternative or when-not-to-use condition, but for a self-contained diagnostics tool that context is clear enough.

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: it discloses the silent-failure mode (an off-list token matches nothing and returns an empty result rather than an error), the cost profile (local lookup, no network, no quota), and determinism (sorted by category, identical on every call). It also pre-describes the shape of each returned entry (token, aliases, description).

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?

Five sentences, each load-bearing: purpose and consumers first, then return shape, then the failure warning, then the exclusion rule, then cost/determinism. No repetition of the title or filler, and the most important warning 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?

An output schema exists so return values need not be re-explained, yet the description still summarises the entry structure helpfully. For a zero-parameter, offline enumeration tool, nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero input parameters, so the baseline is 4. The description usefully explains the semantics of the values the tool *returns* and that they must be passed verbatim as `category` elsewhere, but there is no input schema to enrich.

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

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

States a specific verb and resource (list the canonical place categories) and immediately names the sibling tools that consume the output (`nearby_places`, `search_along_route`, `geocode`), so an agent can place it in the tool graph without opening any schema. It also distinguishes itself from free-text search by excluding cuisines, brands and names.

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 'read this before guessing a category' directive with the consequence spelled out, plus a clear when-not rule (cuisines, brands and names are NOT categories, search those as free text). The alternative behaviour and the condition selecting it are both stated, not implied.

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 real behavioral facts: local lookup, no network, always works, and the non-obvious invariant that attribution is enforced on every compiled style and cannot be themed away. Return shape is not described, but an output schema exists, so that omission is acceptable.

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 scope statement is front-loaded and each enumerated clause carries a distinct, useful vocabulary item rather than filler. It is a dense run-on sentence, but the density is information rather than padding.

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 discovery tool with a full output schema and no annotations, the description covers what it enumerates, how to consume the results, and its operational guarantees. Nothing an agent needs before calling 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 takes zero parameters, so the baseline is 4. The description nonetheless adds meaning to other tools' parameters by naming `base`, `style=`, insertion slots (bottom/middle/top), and set_layer_paint's accepted layer ids, which helps the agent chain calls correctly.

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

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

The description gives a concrete verb and resource ("List everything a MapMap style theme can style") and enumerates the exact vocabularies returned — bases, palette slots, skeleton layer ids, source-layers, insertion slots, sources rules. It implicitly distinguishes itself from get_style/set_layer_paint by naming those tools as consumers of the values, though it never states what those siblings do differently.

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 what to do with the results (pass a base to create_style's `base` or the static-map API's `style=`; use skeleton layer ids with set_layer_paint), which is clear usage context. It stops short of an explicit when-to-use-this-vs-get_style statement or any exclusion.

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 well: it discloses the exact input alternatives and mutual exclusion, the return shape, the honesty caveat that roll-ups may not sum to `distance_m`, how unattributed segments are handled, and the hard dependency on the MapMap gateway with no fallback.

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 front-loaded, with the core action in the first sentence and parameters, returns, caveats and prerequisites following in order. It is long, but nearly every sentence carries usable information, so only mild trimming is possible.

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 three-parameter matching tool with an output schema and no annotations, the description is complete: inputs, costing semantics, return fields, data-quality caveats and the gateway prerequisite are all covered, leaving no gap an agent would need to fill.

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 meaning beyond the schema: the 'provide this or that (not both)' mutual exclusion (not enforced at the top level of the schema), the 2-2000 point range, and an example of how costing changes physical matching (a walk matched as auto snaps to the carriageway).

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+resource: snap a recorded GPS trace to the road network and report what was travelled. It clearly separates itself from routing siblings like `route` and `route_observations` by emphasizing matching an already-recorded trace rather than computing a path.

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

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

Gives clear context ('turn a dashcam or telematics log into a report') and explains the costing choice that governs matching. It does not explicitly name alternatives or when-not-to-use (e.g. vs `route` or `route_observations`), 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 at all, the description carries the full burden and does so: it documents the return shape (durations_s in seconds, distances_m in metres, null for unreachable pairs), a hard limit of 10,000 cells per call, and engine-specific behaviour (exclude_polygons honoured on Valhalla, silently ignored on GraphHopper). Those are exactly the operational facts an agent needs before calling.

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 verb and matrix orientation, then costing, output contract, limits, and the optional scenario parameter. Dense but every sentence contributes; the only redundancy is the exclude_polygons explanation largely duplicating the schema's own description, including its wording and the engine caveat.

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

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

An output schema exists, yet the description still supplies what the schema alone cannot convey: null-cell meaning, the cell-count ceiling, and engine-dependent support for `exclude_polygons`. Combined with the 100%-covered input schema, an agent has everything needed to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it repeats the longitude-first requirement for polygons, explains that exclusion is applied to every cell's pathfinding (intersecting roads), and links the `truck` profile semantics back to `route`. It does not, however, clarify units or defaults for the truck dimensions.

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 sentence states a specific verb and resource (compute travel time/distance matrix) and defines the row/column semantics of origins and destinations, which immediately distinguishes it from row-per-route siblings like `route` and `optimise_routes`.

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 one clear use case (before/after scenario analysis with `exclude_polygons`) and a compatibility caveat, but never states when to prefer this over `route`, `optimise_routes`, or `reachable_area`. Usage is implied by the many-to-many shape rather than explicitly contrasted with alternatives.

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: it discloses the MapMap gateway auth requirement (GATEWAY_URL + GATEWAY_API_KEY), that unknown categories/names return an empty list rather than an error, default/max values, the direction-vs-cardinal fallback, and the meaning of out_of_view. The note about preferring to read `direction` aloud and reporting out_of_view rather than "nothing nearby" is behavioral guidance an agent could not infer elsewhere.

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 purpose and the geocode contrast, then required inputs, then optional params and return shape; each sentence is informative. It is, however, a dense wall of prose with some duplication of the schema (fov_deg, category normalisation), which costs it the top mark.

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 8-parameter tool with no annotations, the description covers auth, required inputs, defaults, ordering, units, edge-case error behavior and viewpoint-dependent phrasing. An output schema exists, yet the description still orients the agent on how to use results, so nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including colloquial category normalisation and fov_deg width semantics. The description adds some cross-parameter meaning (combining category+name to disambiguate a brand), but largely restates schema content, so the baseline 3 applies.

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

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

Opens with a specific verb+resource+ordering+units: "Find places near a point, nearest first with distance in metres, by category ... by name ... or both." It explicitly contrasts itself with the sibling geocode, so an agent can distinguish the two without opening a schema.

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

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

States the exact condition for choosing this tool over geocode ("whenever the question is about what is NEAR a location") and explains the failure mode geocode has (returns a branch in another city over the one 100 m away). It also states the input precondition: provide lat, lon and at least one of category or name.

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 and does so well: it discloses coverage (England plus border stops), the gateway dependency and the exact failure behavior ('a deployment without the stops index answers a clear error'), and the attribution/licence obligation. That is richer than a typical read-only tool description.

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

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

Purpose and required inputs are front-loaded in the first two sentences, and each sentence carries real information. It is dense to the point of enumerating every returned field even though an output schema exists, which is the one place words could be spared.

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 4-parameter lookup with an output schema, the description covers everything an agent needs: input contract, mode and geographic coverage, error posture, downstream chaining, and display obligations. Nothing material is left to inference.

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 spells out WGS84, the 1-to-50 limit and default 10, and the radius default 500, so the description's parameter text is largely a restatement. It adds the tighter '1 to 50' bound for limit versus the schema's declared maximum of 255, which is informative but also a minor inconsistency.

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+resource ('bus and coach stops near a point, nearest first') plus geography and mode scope, which cleanly separates it from nearby_places and next_departures in the sibling list. An agent can tell what it 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?

Gives the invocation condition (pass lat/lon), the exclusions (rail, tram, metro, ferry not included) and a chaining instruction (pass the returned id to next_departures). It never names a sibling as the alternative for the excluded modes, so it stops just short of full when/when-not/alternatives guidance.

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

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

With no annotations, the description carries the full load and does so well: `basis` is always 'timetable', a `live` entry is an observation (within 3 km and heading towards the stop) never an arrival time or delay, the tool never predicts arrivals, the index spans three service days, and the gateway error behavior is disclosed.

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 params, then the critical 'do not present as arrival times' caveat. It is a dense single paragraph and slightly long, but nearly every sentence earns its place (semantics, limitation, attribution requirement).

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 an output schema existing, the description supplements it with usage-critical semantics (what `live`/`basis` mean) and obligations (attribution display, verbatim label/coverage). Nothing an agent needs to call and interpret this 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 four parameters including defaults and ranges. The description largely repeats these (stop code source, three-day index, 1-180/default 60, 1-30/default 8) without adding format or syntax beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Timetabled bus departures at one stop') and names its data source (BODS timetables). This clearly distinguishes it from nearby_stops (stop lookup) and route_observations (live positions), so an agent can pick it without opening schemas.

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

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

It chains to a sibling ('the NaPTAN ATCO code nearby_stops returns'), states the gateway prerequisite, and warns that a deployment without the index errors out. It does not explicitly contrast when to prefer this over other departure/route tools, but the usage context is clearly conveyed.

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

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

No annotations are supplied, so the description carries the full burden and does so unusually well: it discloses billing ('bills as two solves when the second one runs'), the fact that the tool refuses rather than silently ignoring gateway features, that the reload split is fixed before the solve and therefore conservative, that max_trips is a budget not a prediction, and that relaxation is capped at one extra solve and only returned if it assigns more work. Auth/permission requirements and any rate limits beyond 'fair use' are not stated, which keeps it short of a 5.

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

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

The critical facts are front-loaded (what it is, then inputs, then limits), but the body is a dense wall of text with conversational asides ('cargo-bike and courier fleets welcome', 'the tipping round', 'it cannot put a lorry in two places at once') that cost scanning time. Much of the reloads/relaxation material is also duplicated in the schema field descriptions, so the length is not fully earned.

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 VRP tool with nested specs, an output schema, and no annotations, the description covers every capability surface an agent needs: input shapes, the truck/ADR legality consequence, territories, reloads, relaxation, emissions zones, the gateway precondition, billing, and the returned view_url. Nothing material to a 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 baseline is 3; the description climbs above it by explaining cross-parameter semantics the schema cannot state per-field — how territory_ids interacts with territories (unrestricted when empty), how emissions+avoid_zones changes the matrix rather than merely annotating, and how relax_if_unassigned interacts with the first solve. This is interpretive value on top of documented 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?

Opens with a specific verb+resource and scope: 'Optimise multi-vehicle, multi-stop delivery plans (VRP)', then enumerates the input shapes (vehicles/jobs/shipments). It explicitly distinguishes itself from three siblings by name — cluster for splitting oversized problems, submit_optimise_job for the async lane, and replan_routes for post-tip tightening — so an agent can route to the right tool without opening a schema.

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

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

Gives concrete when-to-use and when-not guidance: the 200-location / matrix-span fair-use ceiling and the fallback ('cluster the stops … or submit the whole problem to the asynchronous lane'), plus the requirement to re-plan with replan_routes after each reload. It also states the precondition that territories/reloads/relaxation/zones need a configured MapMap gateway.

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 the output shape (visit order, arrival offsets in seconds, total duration/distance) and the end-vs-round_trip relationship, but says nothing about permissions, rate limits, cost of computation, or solver behavior on infeasible 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?

Front-loaded with the core action, then inputs, then return values, in a compact block with no filler. Slightly dense but every clause carries purpose or usage 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?

An output schema exists and the rich input schema is fully described, so the description's remaining need is minimal. It covers inputs and outputs adequately, though it omits failure modes and invocation prerequisites.

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 six parameters thoroughly. The description restates the costing values and stop structure rather than adding new semantics beyond what the schema provides, so it sits at 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 gives a clear verb+resource ('Put a single run's stops in the best visiting order') and scopes it to a single vehicle run. However, it never distinguishes itself from plausible siblings like plan_errands, optimise_routes, or matrix, so an agent must infer the boundary.

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

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

Usage context is implied via 'single run's stops' and the reference to passing `truck` as in `route`, but there is no explicit when-to-use guidance, no exclusion of the multi-route siblings, and no note on inputs that make it fail (e.g. >100 stops).

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 and does reasonably well: it discloses that `optimise` depends on the VROOM solver ("requires the optimisation sidecar"), that geocoded names return a `resolution` and should be re-run with explicit coordinates when `ambiguous`, and that `view_url` encodes stop coordinates/names with no key required. It does not mention rate limits, quota, or error behavior, keeping it short of a 5.

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

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

Front-loaded with the purpose, then walks through inputs and return shape in a logical order, and every clause carries information. It is dense and somewhat long, with some redundancy against the schema (re-listing costing values and truck restrictions), which keeps it from a 5.

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 7-parameter planning tool with an output schema, the description is comprehensive: inputs, ordering behavior, geocoding ambiguity handling and the map link are all covered, and return values are explained (though the output schema already covers them). With no annotations, a brief note on permissions/cost or failure modes would be the only remaining gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the same parameter facts already documented in the schema (costing list, truck profile, optimise/VROOM, depart_at semantics) rather than adding new syntax or default guidance, so it earns no more than 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?

Opens with a specific verb+resource+scope: "Turn an itinerary into one navigable multi-stop route," which is immediately distinguishable from siblings like `route` (single route), `order_stops`/`optimise_routes` (pure ordering) and `plan_errands`. The description also enumerates the distinguishing capabilities (dwell time, ETAs, optimise via VROOM) so an agent can tell what makes this tool different without opening a schema.

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

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

Usage is implied rather than stated: the feature set (multi-stop itinerary, dwell_minutes, depart_at, return_to_start) makes the intended scenario inferable, but there is no explicit "use this when / use X instead when" routing against close siblings such as `plan_errands`, `order_stops`, or `route`. No exclusions or prerequisites are given.

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, the description carries the full burden and does so: it discloses that infeasible outcomes are answers (`feasible: false`, `reason`, furthest reachable point) not retryable errors, warns about `gradient_data` = absent, mandates surfacing `coverage_note` and `charging_attribution`, and notes `availability_live` for status currency plus the MapMap gateway dependency and no-dataset error. This is exactly the operational context an agent needs.

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 purpose and required inputs, then tiers down into modelling detail and output caveats. It is long and occasionally dense, but nearly every sentence carries distinct behavioural information rather than padding.

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 an 11-parameter schema and a nested vehicle object, the description covers what the agent must know that structured fields cannot express: infeasibility semantics, coverage limitations, elevation caveat, and the required display of attribution. With an output schema present, it rightly avoids explaining return values and focuses on 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 genuine meaning beyond it: it clarifies that `reserve_soc` is the mid-route floor distinct from arrival SOC, that `connectors` only narrows the vehicle's own set, and that `profile` acts as a base overridden by inline figures. The numeric defaults it repeats are already in the schema, so it does not reach the top band.

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 first sentence states a specific verb and resource ("Plan a whole electric-vehicle journey, charge stops included") and the follow-up distinguishes it from plain routing by emphasizing charge-stop insertion and physics-based energy modelling. An agent can tell this apart from `route`, `optimise_routes` and `cheapest_charging_along_route` without opening any schema.

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

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

The description gives clear context for invocation (give origin/destination plus a vehicle, defaults for the SOC knobs) and strong when-not guidance around infeasible results. It stops short of explicitly naming sibling alternatives such as `cheapest_charging_along_route` or `route`, so the routing is implied through scenario rather than stated.

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: origin snapping to the nearest usable road (ferries excluded, 5 km cap), snapped_origin reporting on collection and features, the refusal case 'no roads near this point' with the notable detail that it is not billed, and engine applicability (Valhalla-only, ignored on GraphHopper). These are exactly the behaviors an agent cannot infer from 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?

Purpose and primary parameters are front-loaded, and most sentences earn their place by adding behavioral detail. It is dense and long for a single paragraph, and the exclude_polygons engine caveat is echoed twice, which slightly dilutes the structure.

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 spatial tool with 5 parameters, required fields, and an output schema already covering return values, the description still supplies all the preconditions an agent needs: snapping, refusal semantics, engine support, and output feature granularity (one feature per contour). 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the before/after scenario rationale for exclude_polygons ('close this bridge and recompute'), the longitude-first ring convention, and the polygons true/false render-layer distinction. It goes past restating the schema rather than just duplicating 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 opens with a precise verb+resource: 'Compute the area reachable from an origin within one or more travel-time budgets.' It further grounds this with concrete framing (walkability/cyclability rings, isochrone-style output) that separates it from geometric siblings like geo_area, geo_bbox or geo_length.

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 strong contextual guidance via concrete questions ('how far can I walk in 15 minutes?', delivery coverage) and explains what each costing selects. However, it names no alternative sibling tool or an explicit when-not-to-use condition (e.g. single-point routing should use route instead), so it stops short of full routing guidance.

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

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

No annotations are provided, so the description carries the full burden and discharges it: statelessness ('nothing is stored', no dispatch state/plan/position/log), the reason for the round-trip cost (stale/leaking server-side plan), reproducibility guarantees, the locked-prefix invariant, the required MapMap gateway, and the billing model ('Billed on the remaining problem'). This is unusually complete behavioral disclosure for an unannotated mutation 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 correctly — purpose in sentence one, mechanics after — but it is roughly twice as long as needed, with rhetorical filler ('rather than left for a dispatcher to notice at four in the afternoon', 'a guarantee the solver cannot break, rather than a hint it is free to ignore') that a dispatcher-facing agent does not need to select or call 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?

For an 11-parameter, stateful-ish tool with no annotations, the description covers selection, prerequisites, refusals, billing, and even previews the non-standard `replan` output block (prefix, releases, forced-unassigned, unresolved ids). An output schema exists, so return values need not be fully specified, yet the description still gives the agent enough to interpret the response.

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 structured baseline is 3, but the description adds framing the schema does not: that the ORIGINAL problem must be passed in full (not a delta), and how progress/changes interact with the gating rule. It restates some schema-documented field semantics (ordered completed_stop_ids), so it edges just above baseline rather than fully compensating.

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: 'Re-plan a fleet part-way through its shift,' immediately distinguishing it from the sibling optimise_routes by framing it as a mid-shift variant. An agent can select this tool from the name-plus-first-sentence 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?

Explicitly states the preconditions ('you pass the ORIGINAL optimise_routes problem in full, plus progress and/or changes'), the gating rule ('At least one progress entry or one change is required'), and an exclusion ('Multi-trip vehicles cannot be re-planned... refused with what to send instead'). It names the alternative tool and the conditions that select this one over it.

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