MapMap

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

With no annotations provided, the description carries the full burden, and it does so thoroughly. It discloses the operator-feed limitation, the absence of a national registry, the meaning of empty results, stale vs live statuses, the need to show coverage_note and charging_attribution, and the gateway/dataset error case. This is exemplary behavioral disclosure for a tool with no annotations.

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

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

The description is dense but every sentence contributes: purpose, input modes, filtering options, behavioral caveats, output fields, and mandatory display instructions. It is front-loaded with the core value proposition and structures the key usability warnings (empty results, stale statuses, attribution) clearly. Length is appropriate for the tool's complexity.

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

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

For a 10-parameter tool with no annotations, the description covers everything an agent needs: how to specify the route, filter options, detour semantics, coverage limitations, live-data conditions, error behavior, and required display of coverage_note and charging_attribution. An output schema exists and the description even summarizes the returned fields, so no critical context 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?

Input schema coverage is 100% and the schema already documents each parameter, so the baseline is 3. The description adds genuine integration logic beyond the schema: origin+destination vs geometry_polyline6 as alternatives, truck profile making detours respect dimensional/ADR restrictions, ranking by power, and the availability_live caveat for returned statuses. It does not add much beyond the schema for max_results and costing, but the added recipe-level guidance justifies a 4.

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

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

The description names a specific verb and resource: finding EV charge points along a route, with real detour time rather than straight-line estimates. The phrase 'best EV charge points along a route' clearly differentiates it from fuel, geospatial, and nearby-place siblings, and the output focus on detour_minutes/detour_km gives it a distinctive 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 clearly explains when to call it: given origin+destination or an existing route's geometry_polyline6, with optional filters. It also gives important context such as available_only requiring a live feed and the MapMap gateway/no-dataset error behavior. It does not explicitly name alternatives like plan_ev_route or cheapest_fuel_along_route, so it lacks explicit when-not-to-use guidance.

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

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

With no annotations at all, the description carries the full burden of behavioral disclosure, and it delivers: it names live open-data feeds, defines the stale flag as 'not verifiably fresher than 24 h', explains ranking by cheapest first, documents the error when no dataset exists, and states how truck costing affects detour restrictions. It also surfaces the 'never a straight-line guess' guarantee.

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

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

The description is dense but well-organized: value proposition first, then route input, then data sources, then output fields and error behavior. Every sentence adds useful context, though it is somewhat long and partially echoes schema descriptions.

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 9 optional parameters and an output schema, the description covers the essential invocation modes, defaults, data provenance, result fields, error handling, and even an agent-facing display instruction. Minor omissions like max_results are already fully documented in the schema, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds extra meaning beyond the schema: it explains the mutual exclusivity of geometry_polyline6 vs origin+destination, that fill_litres produces saving_total, the effect of truck profiles on detours, and the default/alias behavior of fuel codes. Some repetition of schema text prevents a 5.

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

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

The description opens with a specific verb and resource: 'Find the cheapest fuel along a route', and immediately distinguishes itself from any generic routing or place-search tool by emphasizing real detour times rather than straight-line guesses. This clear scoping separates it from siblings like search_along_route and nearby_places without needing to open 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 concrete invocation guidance: provide origin+destination, or geometry_polyline6, plus fuel code and max_detour_minutes, and states the MapMap gateway prerequisite. It does not explicitly name alternatives or provide when-not conditions, so it stops short of a 5, but the usage context is otherwise clear.

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

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

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

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

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

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

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

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

The description covers purpose, parameter usage, interpretation semantics, and operational behavior, while the output schema covers return values and the input schema covers all parameters. Slightly more could be said about edge-case handling (e.g., unrecognized tunnel codes), but nothing essential to selecting or invoking the tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters; baseline is 3. The description adds marginal value by reinforcing which parameters to supply and giving code examples ('B', 'C5000D', 'B/D', 'none'), though these overlap with the schema's own examples.

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

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

States a specific verb and resource: 'Check whether a vehicle may pass through a tunnel of a given ADR category ("A"–"E")'. The ADR tunnel category scope clearly differentiates it from geo siblings like check_clearance_on_route, which concerns route clearance rather than hazmat tunnel restrictions.

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

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

The description implies its use case (determining hazmat tunnel passage) and instructs what to provide ('Provide hazmat and, when known, the load's ADR 8.6.4 tunnel restriction code'), but it never explicitly contrasts with alternatives such as check_clearance_on_route or states when not to use it. Usage context is present but left to inference.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses dated-survey limitations, that route_certified is always false, how coverage gaps return not_surveyed_m and insufficient_data_m, and how pass/fail/indeterminate/no_verdict correspond to physical evidence. It even flags that a pass may have no limiting point and that width can return not_assessed.

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 is front-loaded and nearly every sentence adds functional or caveat information. It is quite long and has rhetorical and grammatical turns ('Honesty, and it matters here'; 'Routes with truck costing... then measures that corridor') that keep it from being optimally concise.

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 lack of annotations, the description is remarkably complete: it names all required and optional inputs, explains verdict semantics, uncertainty fields, coverage handling, authentication requirements, and where to find further guidance. An agent has enough information to call the tool correctly and interpret all answer types.

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 covers parameters at 100%, so the baseline is 3. The description adds useful meaning by explaining that margin_m is applied to the measurement rather than the routing step, that width_m is reported separately and never as headroom, and that there is no default vehicle height, though it adds little new detail for origin and destination.

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: 'Measure a vehicle's overhead clearance along a route against surveyed point cloud geometry.' It also distinguishes itself from map-tagged height restrictions and sibling tools like check_adr_tunnel by clarifying it measures physical surveyed geometry, not posted or signed heights.

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 trigger: 'Reach for this when a truck route came back unchanged' and states prerequisites (MapMap gateway, no fallback). However, it does not explicitly name an alternative sibling tool or say 'do not use this for posted height checks,' so the when-not guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses the two palette variants checked, the exact thresholds, that failing pairs list slots to adjust, and that contrast never blocks publishing. It does not explicitly state it is read-only, but 'Audit' and 'Advisory' imply no mutation.

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

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

Three front-loaded sentences carry purpose, input, thresholds, and advisory behavior with no filler. Every sentence earns its place.

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

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

The tool has only two parameters, an output schema exists, and the description supplies thresholds, input alternatives, palette variants, and follow-up guidance via set_palette. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents the exactly-one-of style_id/theme rule and theme format. The description adds only a concise restatement and a pointer to create_style, which is useful but not a major increment over the schema.

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

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

The description opens with a specific verb ('Audit'), a precise resource ('a map style's colour contrast'), and an explicit standard (WCAG 2.1 thresholds for label text and graphics). This clearly distinguishes it from sibling tools like check_adr_tunnel or set_palette.

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

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

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

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

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

With no annotations, the description carries the full burden, and it delivers richly. It discloses the key behavioral trait: 'STRAIGHT-LINE clustering' with no road, river, or one-way system consulted, including the estuary example. It also discloses determinism across deployments, the bin-packing relaxation behavior, the `basis` output caveat, and the MapMap gateway requirement.

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents every parameter thoroughly. The description adds emphasis (e.g., 'EXACTLY ONE of') and restates the derived-count logic, but it does not add materially new meaning beyond the schema's own parameter descriptions. A score of 3 reflects that the schema does the heavy lifting.

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

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

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

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

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

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

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains default-theme behavior, optional worldview filtering with accepted ISO codes, fallback to OSM on-the-ground names, and the return format. It does not cover auth, persistence, or rate limits, but the core side effects are clearly described.

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 a dense but efficient paragraph with the main purpose front-loaded. It is slightly long because of the worldview detail and return-value explanation, but every sentence contributes actionable information rather than 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 tool with no annotations and a schema that under-describes the theme object, the description is self-sufficient. It covers required input, optional theme structure, accepted worldview codes, default behaviors, output values, and even names sibling tools that consume the returned style_id.

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 high, placing the baseline at 3, but the description adds meaningful detail: it expands the theme parameter into its structure ({base, palette, layers}), enumerates accepted worldview values, and clarifies what happens when each optional parameter is omitted. This goes beyond the schema's generic theme description.

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

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

The opening phrase 'Create a hosted map style' is a specific verb+resource pair that clearly distinguishes this from sibling tools such as get_style, list_style_layers, set_palette, and set_layer_paint. It also states the main output (style_id and compiled style URL), removing ambiguity about the tool's role.

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 provides clear usage context: provide a name, optionally supply a theme document, and rely on defaults when omitted. It even tells the agent that the returned style_id should be passed to set_palette/set_layer_paint, which implies a create-then-modify workflow. It does not explicitly list when not to use the tool, but the workflow guidance is strong.

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

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

With no annotations present, the description carries the full disclosure burden. It states that one sample is returned per input point in order, that `elevation_m` is null for missing DEM coverage 'never a guess,' and that polyline inputs additionally return resampled lat/lon and cumulative `range_km`. This is unusually honest and useful behavioral detail for an unannotated 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?

Three tightly written sentences cover the operation, the two input modes, mutual exclusivity, output ordering, missing-data behavior, and polyline-specific outputs. The high-level purpose is front-loaded, and every clause adds information. There is no filler or repetition of schema text.

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

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

The description is complete for a terrain sampling tool: it covers both input modes, the output contract, missing-data semantics, and extra polyline outputs, while the output schema handles return fields. Nothing an agent needs to invoke 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 input schema already documents each parameter, including mutual exclusivity and the meaning of `resample_distance_m`. The description adds a small amount of relational context by grouping the parameters into 'point elevation' and 'along-route profile,' but it does not substantially extend what the schema already provides.

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 the exact verb and resource: 'Sample terrain elevation.' It immediately distinguishes the tool's two modes (point sampling and along-route profile), which sets it apart from nearby routing and geospatial analysis tools. The phrasing is specific enough that an agent can match the tool to elevation queries without inspecting 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 clearly instructs when to provide `points` versus `encoded_polyline` and explicitly warns 'not both.' It also notes that `resample_distance_m` only applies to polyline input. It does not mention alternative sibling tools or state when not to use this tool, but the mode-selection guidance gives agents a clear operational 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 behavioral load and does it well: geodesic computation, always-positive sign, winding-order independence, and local computation with no network or quota impact. It does not mention behavior on invalid input such as fewer than 3 points, but this is a minor gap for such a simple pure function.

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 compact, front-loaded sentences each earn their place: result and units, sign behavior, intended scope, and execution characteristics. There is no filler or redundancy.

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

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

The tool has a single required parameter and an output schema, so the description doesn't need to explain return conventions. It supplies the key contextual facts—geodesic method, area unit, positive result, half-globe limitation, and local execution—leaving only minor edge-case behavior unstated.

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 `points` and the `lat`/`lon` fields completely, so the baseline 3 applies. The description adds useful context like 'ring' and the 3+ requirement, but it doesn't elaborate on ordering, precision, or repeated closing coordinates—details that would be extra value beyond the schema.

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

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

The description states a specific operation—computing enclosed area in square metres from a geodesic ring of 3+ coordinates—making it instantly distinguishable from line-measurement siblings like geo_distance and geo_length. The '3+ coordinates' condition further defines the expected input resource.

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 clear intended use ('zones and boundaries') and an explicit exclusion ('not for polygons covering more than half the globe'). It stops short of naming alternative tools for that exclusion, but the guidance is sufficient for an agent to understand when this tool applies.

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 behavioral burden. It adds valuable context by stating that the computation is local, involves no network call, and consumes no quota. It does not cover edge cases like empty input, but the '1+' constraint mitigates that concern.

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 deliver the output format, primary use case, and key performance trait without any filler. The essential definition is front-loaded, making it easy for an agent to parse quickly.

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 pure local computation with a single well-documented parameter and an output schema, the description is complete. It explains what the tool returns, why an agent would use it, and that it has no network or quota implications. Nothing critical is missing for correct invocation.

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 documents the single `points` parameter at 100% coverage, including the LatLon structure. The description adds little parameter-level meaning beyond the '1+' minimum, so the schema does the heavy lifting. This matches the baseline score for high schema coverage.

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

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

The description clearly defines the tool as computing an axis-aligned bounding box and explicitly gives the output shape {min_lat, min_lon, max_lat, max_lon}. This distinguishes it from sibling geo tools like geo_centroid, geo_area, and geo_distance with specific, non-tautological language.

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 provides a concrete use case: fitting a map view to a set of stops. It does not explicitly name alternatives or say when not to use this tool, but the context is clear and actionable enough for an agent to select it appropriately among geometry 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 provided, the description carries the full burden. It transparently discloses that the computation is local (no network call, no quota) and explains a key behavior: the bearing changes en route over long distances. It does not mention error handling, but for a pure calculation the disclosed behavior is sufficient.

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 fluff. The core purpose is front-loaded, and the important caveat about initial bearing follows immediately. The local computation note is a useful extra. 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?

For a simple calculation tool with an output schema, the description covers the essential aspects: what it computes, the unit, the geodesic nuance, and the local nature. It doesn't mention potential edge cases (e.g., antimeridian), but that is minor and not expected for such a tool. The provided context is sufficient for correct invocation.

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% — both 'from' and 'to' are described in the schema as start/end coordinates, and the LatLon object defines lat/lon. The description adds no new parameter semantics beyond restating the schema. Given the high coverage, 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 states a specific verb (calculate initial bearing) with a clear resource (one coordinate to another) and defines the output in degrees clockwise from true north. It is unambiguous, but it does not explicitly differentiate from sibling tools like geo_destination or geo_distance, despite the clarity of the purpose.

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

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

The description implies usage by clarifying that the bearing is at the START of the geodesic, which hints that this is not for constant bearing over long distances. However, it does not explicitly mention when to use this tool versus alternatives, nor does it name any sibling tools. The guidance is implicit rather than direct.

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 behavioral disclosure burden. It explicitly states local computation with no network call and no quota, which is valuable transparency for an agent deciding whether invocation is safe or costly. It does not discuss edge cases such as antimeridian handling, but the simple pure-computation nature and available output schema mitigate the 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?

The description is two sentences with no wasted words. The core definition and example are front-loaded, and the computational transparency is stated succinctly at the end.

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 pure function with one well-documented parameter and an output schema, the description is largely complete: it covers purpose, input cardinality, use cases, and local execution. It could still mention what happens with a single coordinate or edge-case behavior, but the low complexity means these are minor omissions.

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 semantic meaning beyond the schema by specifying '1+ coordinates' and clarifying that they are combined as a geometric mean. This helps the agent understand constraints and intended input semantics beyond the raw parameter 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 clearly identifies the operation as computing the centroid, or geometric mean position, of coordinates. The examples of picking a depot or centring a map make the purpose immediately understandable, and it is distinct from sibling geometry tools like geo_bbox, geo_area, and geo_bearing.

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 example use cases ('pick a depot location or centre a map') which imply when to use it. However, it does not explicitly contrast this tool with related siblings or state when not to use it, so the guidance is implied rather than direct.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains that structured components are REQUIREMENTS not hints, that invalid countries are refused, that English exonyms resolve under the default lang, and that each result includes match verdicts, score_gap, and backend. This goes far 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 each sentence carries substantive guidance: operation, dual query modes, strictness semantics, result fields, match interpretation, and language behavior. It is front-loaded with the core purpose and maintains a logical progression from invocation to interpretation.

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 zero annotations and nine parameters, the description is remarkably complete. It explains return contents, candidate ranking, match semantics, language handling, and when to prefer a sibling tool. With a rich input schema and output schema also present, nothing essential appears missing for an agent to call and interpret this tool correctly.

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

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

Schema coverage is 100% and the schema already explains most parameters, so the baseline is 3. The description adds valuable semantics on top: the requirement that at least one of query/structured components is supplied, the contrast between requirements and hints, and the practical implications of focus and language choice. Some parameter detail duplicates the schema, so it is not a perfect 5.

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

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

The description opens with a specific verb and resource: 'Turn a place (address, POI, town) into coordinates.' It clearly distinguishes geocode from sibling tools by naming verify_places as the alternative for checking addresses and framing this tool as the conversion of places into coordinates.

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

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

The description gives explicit when-to-use guidance: pass structured parts when you already hold an address in parts, use verify_places when the address came from a model or user and needs checking, and show alternatives instead of picking a top hit when score_gap is small. This is direct usage routing, not just implied 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 provided, the description carries the burden of behavioral disclosure. It adds 'Local computation: no network call,' informing the agent that this is a fast, offline operation. It also describes the mathematical behavior (inverse of distance+bearing). It does not discuss edge cases (e.g., invalid ranges), but for a simple geometric function the provided information is sufficient.

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 wasted words. The functional definition is front-loaded, and the inverse relationship plus local computation note are appended efficiently. Every word contributes.

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 local calculation with complete schema descriptions and an assumed output schema, the description covers all essential aspects: what it computes, the inverse relationship, and the local/network behavior. It does not mention precision or error handling, but those are not critical for this straightforward 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% and every parameter is already described in the schema (start coordinate, distance in metres, bearing clockwise from true north). The description essentially restates these values without adding new meaning, so it does not go beyond the baseline for fully covered parameters.

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 (travel) and resource (coordinate), and precisely defines the output as the coordinate reached by traveling a given distance and bearing. It explicitly identifies itself as the inverse of `geo_distance` and `geo_bearing`, which distinguishes it from those sibling tools immediately.

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 indicates the relationship to `geo_distance` and `geo_bearing` by calling itself the inverse, which implies the appropriate usage context (i.e., when you need a destination point rather than distance or bearing). It does not explicitly state 'use this when...' or give exclusions, but the inverse relationship provides adequate context for an agent to route correctly.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It conveys several behavioral traits: geodesic computation on the WGS84 ellipsoid, straight-line semantics, local computation (no network call), and no quota impact. While it does not discuss edge cases like identical or antipodal coordinates, the disclosed traits go well beyond a minimal description and there is no contradiction with any annotation.

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

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

The description is two short sentences with zero filler. The core result (distance in metres) is front-loaded, followed by the critical driving-distance distinction and the network/quota qualifier. Every sentence earns its place, and the structure is easy for an agent to parse.

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

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

For a simple two-parameter tool with an output schema present, the description is complete. It covers what the tool computes, its geographic model, the distinction from route/matrix, and performance characteristics. The output schema handles the return value, so the description doesn't need to explain it. No important decision-relevant information 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%—the schema already documents `from` and `to` as start/end coordinates and fully describes the nested lat/lon fields with ranges and a WGS84 note. The description adds little parameter-level meaning beyond naming two coordinates. This aligns with the baseline 3 for high schema coverage, where the schema does the heavy lifting.

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

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

The description immediately states a specific verb and resource: 'Distance in metres between two coordinates.' It further specifies the computational model ('geodesically on the WGS84 ellipsoid') and explicitly distinguishes itself from driving distance, which also differentiates it from sibling tools like route and matrix. Even without seeing the schema, an agent knows exactly what this tool does.

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

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

The description gives explicit guidance on when to use this tool versus alternatives: 'NOT a driving distance — use route or matrix for travel distance and time.' It also adds a decisive performance qualifier—'Local computation: no network call, no quota'—which helps an agent choose it when avoiding network latency or quota concerns.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the computation is local ('no network call, no quota') and that the measurement is geodesic and summed over a 2+ point polyline. It does not detail error behavior for fewer than 2 points, but for a simple calculation tool this is adequate 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?

Three short sentences with no filler. The core measurement is front-loaded, the route distinction follows, and the local-computation note is compact and useful. 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?

For a one-parameter tool with an output schema, the description covers the essential context: units (metres), geodesic method, line-vs-route distinction, and the side-effect-free local computation. Nothing critical is missing for selecting and invoking it correctly.

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

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

The schema provides 100% coverage for the `points` parameter but only says 'The coordinates to consider.' The description adds meaningful semantics: a polyline must have 2+ coordinates and the calculation is geodesic and summed. This goes beyond the schema's bare description.

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

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

The description clearly states the tool computes 'Total length in metres of a polyline through 2+ coordinates, summed geodesically', specifying both the resource (a supplied polyline) and the operation (length measurement). It also explicitly distinguishes itself from a driven route by pointing to the `route` sibling tool, eliminating 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?

It provides explicit guidance: 'This measures the line you supply, NOT a driven route — use `route` for that.' This tells an agent exactly when to use this tool versus the alternative sibling, making the selection criterion 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 present, the description carries the full burden and does so well. It discloses that the computation is local, requires no network or quota, returns geodesic distance in metres, and that the closest point may lie between vertices. These are non-obvious behaviors that the schema does not convey.

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

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

Three sentences, each earning its place: the first states the primary output, the second clarifies a subtle geometric behavior, and the third gives a use case and performance characteristic. Information is front-loaded and there is no redundant 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 simple two-parameter geometry calculation, the combination of a 100% documented schema, an output schema, and a description covering purpose, behavior, units, and execution context is complete. An agent has enough information to select and 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?

The input schema documents both parameters fully with descriptions of the coordinate and polyline, so schema coverage is 100%. The description adds contextual framing ('coordinate' and 'polyline') but no additional parameter-level meaning beyond what the schema already provides, 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?

Clearly states what the tool does: finds the closest position on a polyline to a given coordinate and returns the geodesic distance in metres. The added detail that the result may fall between vertices, not only on them, helps distinguish it from simpler point-in-polygon or point-to-point distance tools.

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

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

Gives a concrete use case ('how far is this address from the route?') and highlights that it is a local computation with no network call and no quota, which helps an agent decide when to prefer it. It does not explicitly name alternative tools or state when not to use it, but the 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 carries the full behavioral disclosure burden. It reveals two non-obvious behaviors: boundary points are treated as OUTSIDE, and the polygon closes automatically if the last coordinate doesn't repeat the first. It also reassures about local computation with no network or quota. A brief statement about being read-only is absent but implied by the query phrasing.

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?

Every sentence earns its place: a clear purpose statement, concrete use cases, required inputs, the boundary caveat, and the local-computation guarantee. The information is front-loaded and there is no wasted wording.

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

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

For a two-parameter boolean geospatial predicate with an output schema, the description covers all necessary behavioral context: input shape, closure behavior, boundary semantics, and cost characteristics. Nothing an agent needs to invoke and interpret 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 coverage is 100%, so the baseline is 3. The description restates the point and polygon shape plus the 3+ coordinate requirement, but the schema already documents the LatLon fields, required minimum, and automatic closure. The description adds minimal semantic value beyond the structured 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 begins with a precise predicate — 'Whether a coordinate lies inside a polygon' — and names concrete use cases (delivery zones, catchments, clean-air zones, site boundaries). This clearly distinguishes it from sibling geometry tools like geo_distance, geo_area, or geo_bbox.

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 context is clear: use this when the question is point-in-polygon containment, with examples of typical polygon types. It does not explicitly list sibling alternatives or when-not-to-use it, but the predicate itself makes the applicable situation obvious. The 'local computation, no quota' note further helps selection.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that tolerance is in degrees, not metres, that endpoints are always kept, the nature of the return value, and that no network call or quota is involved. It does not cover edge cases or error behavior, but the provided details are useful and non-obvious.

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?

Every sentence in the description earns its place: the core purpose, the unit warning, the endpoint guarantee, the return value, and the local-computation note. It is compact, front-loaded, and free of 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 tool with full schema coverage and an output schema, the description provides all essential information: how to interpret tolerance, the guarantee about endpoints, and what the return contains. No critical gap remains for an agent to invoke it correctly.

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

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

The schema already documents both parameters fully, so the baseline is 3. The description adds value by clarifying the tolerance unit conversion (degrees vs metres, with a concrete equivalence) and by stating 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 uses a specific verb and resource ('Reduce the number of coordinates in a polyline while keeping its shape') and names the Douglas-Peucker algorithm. It clearly distinguishes geo_simplify from geometric calculation or measurement siblings like geo_length, geo_area, and geo_centroid.

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 use: simplifying a polyline by reducing coordinates while preserving shape. It also notes 'Local computation: no network call, no quota,' which is a practical usage consideration, though it does not explicitly mention alternatives or when not to use the tool.

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

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

With no annotations, the description carries the full transparency burden and exceeds it. It discloses status values, the terminal field's meaning, free polling, units_charged and refunded semantics, key ownership, and the deliberate NOT FOUND rather than forbidden behavior. This is unusually rich 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 description is long but every sentence earns its place: purpose, status semantics, polling cadence, billing behavior, auth behavior, and gateway requirement. It is front-loaded with the core purpose and then layers contextual details in a logical order.

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

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

The output schema can carry return-shape details, freeing the description to cover everything else an agent needs: job states, terminal polling semantics, cost behavior, auth boundaries, error semantics, and the gateway requirement. Nothing essential is left 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 'id' fully at 100% coverage, so the baseline is 3. The description adds meaningful context beyond the schema by explaining that the id belongs to the submitting key or another key of the same identity, and that another party's id yields NOT FOUND rather than forbidden.

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: 'Read an asynchronous job submitted with submit_optimise_job' and clarifies that the result is 'exactly the body the synchronous tool would have returned.' This clearly distinguishes get_job from its submission sibling and from synchronous variants.

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 explicit operational guidance: poll while the 'terminal' field is false, check every few seconds rather than guessing at a duration, and treat webhooks as unsuitable for agents in a loop. This tells the agent exactly when and how to use the tool.

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

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

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

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

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

Two sentences with no filler: the main fetch action is front-loaded, and the second sentence adds practical guidance. Every word earns its place.

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

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

For a single-required-parameter read operation with an output schema present, the description is largely self-sufficient. It explains the two outputs and the intended editing context, though it could name related sibling tools or explicitly confirm the operation is non-mutating.

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

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

Schema description coverage is 100%, including an explicit example for style_id. The description adds only a mild hosted-style framing and does not meaningfully enhance understanding beyond the schema.

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

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

The description uses a specific verb ('Fetch') and names precise resources: the latest theme document and the URL of the compiled MapLibre style. It also ties the tool to an inspection-before-editing workflow, which clearly differentiates it from editing-focused siblings like set_palette and set_layer_paint.

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

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

The description gives clear usage context: use the theme to inspect current palette and layer overrides before editing. It does not explicitly name alternatives or state when not to use the tool, but the intended workflow is evident.

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

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

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

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

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

The description is longer than a minimal one, but every extra sentence addresses a real interpretation risk: units vs. calls, pooled quota, and inability to query other keys. It is front-loaded with purpose and cost, then moves through parameters, return semantics, and caveats in a logical order.

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

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

For a simple two-optional-parameter read tool with an output schema, the description is exceptionally complete. It covers purpose, cost, default ranges, date-bound behavior, output semantics, unit weighting, pooled identity, authentication key ownership, and the required gateway setup. An agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so the schema already documents both optional parameters including defaults, format, inclusiveness, and the 92-day cap. The description repeats and lightly contextualizes this ('bound the report; omitted, it covers the current month to date') but does not add substantial new parameter-level meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Check what your own API key has spent.' It also adds a clear use case ('decide mid-task whether to keep going') and is plainly distinct from all sibling tools, which concern routing, geocoding, style, or planning rather than quota usage.

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

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

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

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses that the list is sorted, identical on every call, local, offline, quota-free, and that invalid category tokens silently return empty results. This goes well beyond a simple 'list' statement and gives the agent important behavioral expectations.

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

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

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

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

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

For a zero-parameter tool with an output schema, the description is complete. It covers purpose, return structure, relationship to sibling tools, failure mode for invalid tokens, excluded categories, determinism, and performance characteristics. Nothing an agent needs to decide whether to call it is missing.

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

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

The tool has zero parameters, so there is no parameter schema to augment; the baseline is 4. The description still explains that the output entries are exact category tokens, aliases, and descriptions, which helps the agent understand how the category value is meant to be used in sibling tools.

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

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

The description uses a specific verb and resource: it lists canonical place categories for use with nearby_places and search_along_route. It clearly distinguishes this from sibling tools like list_style_layers by tying it to place-category tokens and related geocoding workflows. The exact purpose is unambiguous.

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

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

The description explicitly says to read this before guessing a category, and warns that unrecognized tokens return an empty result rather than an error. It also states that cuisines, brands, and names are not categories and should be searched as free text, giving clear guidance on when not to use this tool and what to do instead.

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

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

With no annotations, the description carries the transparency burden and does well: it explicitly states attribution is enforced and cannot be themed away, and that lookup is local with no network and always works. It could have explicitly said the operation is read-only, but 'List' plus the output schema largely covers that.

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

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

The description is compact and front-loaded with the tool's core purpose, immediately enumerating the three categories of things it lists. The two follow-up sentences about attribution and local lookup earn their place by adding important behavioral context without 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 listing tool with an output schema, the description is fully adequate: it specifies what categories of data are returned, mentions an important constraint (attribution), and reassures about availability. Nothing needed to invoke it correctly is missing.

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

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

The tool has zero parameters and 100% schema description coverage, so the baseline is 4 per the rubric. The description adds no parameter-specific detail, but none is needed because there is nothing to configure.

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

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

The description uses a specific verb ('List') and identifies the exact resource: everything a MapMap style theme can style, broken into palette slots, skeleton layer ids, and OpenMapTiles source-layers. This makes it clearly distinct from sibling tools like set_layer_paint, set_palette, and get_style.

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 provides clear context by stating that skeleton layer ids are what set_layer_paint accepts and source-layers are what extra layers may reference, making the tool's role as a reference/discovery tool obvious. It does not explicitly name alternatives or give when-not-to-use conditions, but the context is sufficient for a listing tool.

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

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

With no annotations, the description carries the full burden and meets it: it discloses the costing mismatch effect, the roll-up summation caveat, omission of missing surface/admin data, and the hard gateway/auth requirement with no fallback. This goes beyond basic operation and helps an agent set expectations.

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

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

The description is long but every sentence earns its place: it flows from purpose to input to output semantics, then caveats and infrastructure. The 'Honesty:' paragraph front-loads important accuracy caveats rather than burying them.

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 map-matching tool with three parameters and an output schema, the description covers input selection, output composition, aggregation caveats, and deployment prerequisite (gateway). Nothing critical to correct invocation or interpretation 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 already 100%, so the baseline is 3. The description adds value beyond the schema with the 'not both' rule, the costing consequence example (walk as auto snaps to carriageway), and the polyline6 format clarification. It reinforces rather than merely restates the schema.

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

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

The description opens with a specific verb and resource: 'Snap a recorded GPS trace to the road network' and states it reports what was travelled over. It also frames the tool's purpose for dashcam/telematics logs, which distinguishes it from route-planning siblings like `route`.

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 identifies the target use case ('turn a dashcam or telematics log into a report') and explains input constraints (shape OR encoded_polyline, costing must match travel mode). It does not explicitly name alternatives or state when not to use it, but the recorded-trace framing is enough to route an agent appropriately.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It responsibly reveals the exact output units, null cells for unreachable pairs, the 10,000-cell cap, and the engine-specific behavior of exclude_polygons (Valhalla supported, GraphHopper ignored). This is strong transparency for a read-only compute tool, though it stops short of discussing timeout/error handling.

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, front-loaded with the core action and followed by essential operational details. Every sentence contributes useful information (costing modes, return fields, cell limit, polygon behavior) with no filler. It could be tightened slightly for readability but is well within acceptable density.

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 is nearly complete: it specifies what is returned, limits, engine compatibility, and the purpose of the optional parameter. The only minor omissions are edge-case behavior (e.g., what happens when exceeding the cell limit) and explicit auth/rate-limit info, but these are not critical for invoking 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 description coverage is 100%, so the baseline is 3. The description adds some conceptual framing—'origins (rows)' and 'destinations (columns)'—and the engine caveat for exclude_polygons, but this largely mirrors what the schema already says. It does not materially deepen parameter understanding beyond the structured definitions.

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

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

The description opens with a precise verb and resource: 'Compute a travel time/distance matrix between origins (rows) and destinations (columns).' It clearly distinguishes this from the sibling 'route' tool by focusing on multi-origin/multi-destination matrix output, and the mention 'as in route' only serves as a cross-reference for the truck profile. No ambiguity about what the tool does.

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

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

The description implies the use case ('before/after scenarios' for exclude_polygons) and states hard limits (10,000 cells) but never explicitly says when to choose this over alternatives like 'route' for single pairs or 'reachable_area' for isochrones. An agent must infer the matrix-vs-route distinction from the tool name and purpose rather than from explicit 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 burden and delivers: empty-list-not-error, case/accent-insensitive prefix matching, category normalization examples, fov_deg full-width semantics, heading fallback behavior, and out_of_view meaning. It even notes the gateway requirement. Exceptionally transparent.

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

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

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

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

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

Covers input requirements, output result fields (name, distance, bearing, details), edge cases (empty list, out_of_view), and gateway prerequisites. With an output schema present, it still effectively explains all necessary call parameters and expected behavior. Nothing an agent needs is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond schema by clarifying the 'at least one of category or name' requirement (not in required collection), explaining the disambiguation strategy ('Lloyds' plus 'bank'), and mentioning the 'Prefer reading direction aloud' tip. Slight redundancy with schema, but meaningful extra context.

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

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

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

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

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

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

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

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

No annotations were provided, so the description carries the full burden. It discloses the most important behavioral trait: `relax_if_unassigned` re-solves exactly once, returns the relaxed plan only if it assigns more work, and bills as two solves. It also warns that reloads is an approximation, that max_trips is a budget not a prediction, and that the user must check `relaxation.relaxed_plan_used` before claiming the day fits. This is rich, honest 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?

The description is long, but every sentence earns its place — it explains the VRP inputs, costing profile rules, fair-use limits, territory semantics, reload behavior, relaxation guarantees, emissions effects, and the gateway prerequisite. It is front-loaded with the core purpose and returns. It loses one point for being quite dense and long; an agent may need to re-read parts, but the density is justified by the tool's complexity.

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

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

Given the tool's high complexity (9 parameters, nested specs, output schema), the description covers all the critical decision points: when to use alternatives, what happens with reloads, what relaxation actually changes, the MapMap gateway dependency, the 200-location/400 km limit, and the honest-check caveats. The output schema exists, so the description need not enumerate return fields; it adds the operational context the schema cannot.

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 description coverage is 100%, so the baseline is 3; however, the description adds semantic value beyond the schema by explaining how `vehicles`, `jobs`, and `shipments` interact, what `territories` polygon order requires (longitude first), how `reloads` splits the shift, what `relax_if_unassigned` actually does, and how `emissions` with `avoid_zones` changes the plan. This goes well beyond what the JSON Schema provides.

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 clear, specific statement — 'Optimise multi-vehicle, multi-stop delivery plans (VRP)' — and then details the core inputs (vehicles, jobs, shipments), costing modes, and return shape. It also explicitly differentiates itself from nearby siblings like `cluster`, `submit_optimise_job`, and `replan_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 explicit routing guidance: use `cluster` then optimise each group when exceeding 200 unique locations or 400 km span, use `submit_optimise_job` for 2,000 locations, and use `replan_routes` after each tip. It also states the tool refuses to run without a MapMap gateway for territories/reloads/relaxation/zones, which is important when-to-use/not-use information.

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. It clearly discloses the output contract: stops in visit order, arrival offsets in seconds, plus total duration and distance, and it clarifies truck mode produces a truck-legal order. It does not mention statelessness or failure behavior, but as a pure computation tool the disclosure is adequate.

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-load the purpose before parameter details, with no filler. Each sentence adds distinct information while keeping the whole description readable and scannable.

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 that an output schema exists and the input schema fully documents each parameter, the description is complete enough for correct invocation. It covers required inputs, the 1–100 stop limit, optional end/round_trip behavior, costing selection, truck-legal ordering, and the return value shape without needing to repeat schema details.

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 documents all parameters (100% coverage), so the baseline is 3. The description adds human-readable meaning: auto=car, truck=lorry, a compact stop shape of {location, label?, service_s?}, and a pointer to route's truck syntax, all of which help an agent map intent to parameters.

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

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

States a specific operation: "Put a single run's stops in the best visiting order," reinforced by the quoted user intent "order my errands". The phrase "single run's stops" separates it from broader fleet tools like optimise_routes and from route geometry tools, so an agent can identify what it does precisely.

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 practical configuration guidance: optional end vs round_trip, costing auto vs truck, and passing truck as in route. However, it never explicitly says when to choose this tool over optimise_routes, route, or matrix; the use case is implied rather than stated with when-not-to-use conditions.

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 explains the output structure (visit order, per-leg duration/distance, arrival/departure times, totals, polyline6), the side effects of dwell_minutes and depart_at, the VROOM solver behavior, truck restrictions, and the geocoding ambiguity handling. This is unusually transparent.

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

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

The description is dense but every clause carries information: core behavior, required and optional inputs, costing options, output details, and geocoding caveats. It is front-loaded with the primary purpose and contains no filler or repetition of schema text.

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

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

For a complex tool with an output schema, the description covers everything an agent needs to invoke it correctly: required start/stops, optional parameters, costing semantics, special truck handling, optimisation behavior, return structure, and geocoding failure handling. Remaining details like stop count limits are already in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: it explains what optimise does with VROOM, how truck costing interacts with dimensional/ADR restrictions, how dwell_minutes shifts ETAs, how depart_at yields absolute timestamps, and how to react to ambiguous geocoding results. This elevates it above 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: 'Turn an itinerary into one navigable multi-stop route.' It clearly distinguishes itself from siblings like 'route' or 'order_stops' by combining multi-stop planning, optional optimisation, costing modes, and return-to-start behavior in one call.

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 establishes a clear usage context: when you need an entire day's itinerary as one route with stops, departure time, optimisation, and multiple costing options. It does not explicitly name alternatives or state when-not-to-use it, but the multi-stop framing makes selection 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 provided, the description carries the full burden and does so impressively. It explains the physics-based energy model, warns that charge time is not energy divided by peak power, and details infeasible-answer semantics ('feasible: false' is an answer, not an error). It also covers gradient-data caveats, coverage_note display requirements, availability_live status, and the MapMap gateway dependency.

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 front-loaded with the core purpose and has no filler; each sentence adds a meaningful caveat or behavioral clarification. It uses an 'IMPORTANT' marker and 'ALWAYS' to emphasize critical operational guidance. It could be tightened into shorter paragraphs or bullets for easier scanning, but it earns its length given the complexity.

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

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

For an 11-parameter tool with an output schema, the description covers everything an agent needs: input composition, defaults, infeasible-result handling, data caveats, coverage note requirements, and even display instructions for charging_attribution. It also warns about deployment environments without a charge-point dataset. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by explaining reserve_soc as the mid-route floor, clarifying connectors/min_kw as filters, and describing how vehicle profiles and inline figures interact. It also clarifies defaults for start_soc, min_arrival_soc, and reserve_soc in the flow of the description. The rich schema still does most of the parameter documentation work, but the description genuinely supplements 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 specific verb and resource: 'Plan a whole electric-vehicle journey, charge stops included.' This clearly distinguishes it from general routing siblings like route or optimize_routes by emphasizing the EV-specific charge-stop planning scope. It also states exactly what it returns: stops, state-of-charge traces, and driving/charging times.

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 usage context is clear: this tool is for planning a full EV journey with charge stops, including vehicle specification, SOC thresholds, and connector filters. The description implies it is the right choice when charge stops, charging curves, and EV-specific feasibility matter, while siblings like route or reachable_area serve other purposes. It does not explicitly name alternatives or state when not to use it, so it stops 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?

No annotations are provided, so the description carries the behavioral burden. It discloses the GeoJSON FeatureCollection return shape, filled polygons versus contour lines, the 'longitude FIRST' ordering requirement for exclude_polygons, and the Valhalla-only / GraphHopper-ignored engine behavior. It does not explicitly state read-only/no side effects, but the compute-oriented phrasing makes that risk low.

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 text is dense and every clause earns its place: purpose, costings, contours_minutes constraints, polygon rendering, output format, exclude scenarios, and engine support. The core purpose is front-loaded and there is no filler.

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

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

With an output schema present and all five parameters documented in the input schema, the description covers the remaining practical knowledge: output feature count, rendering-ready polygons, scenario use, and engine limitations. Nothing needed to call the tool 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; the description adds value above the schema by turning costing modes into practical questions and by highlighting when polygons and exclude_polygons are useful. The engine caveat for exclude_polygons is also conveyed in prose beyond the schema.

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

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

The description opens with a specific verb and resource: 'Compute the area reachable from an origin within one or more travel-time budgets', then clarifies the concept as walkability/cyclability rings. This clearly distinguishes the tool from point-based route/matrix siblings by emphasizing areal coverage.

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 supplies concrete use cases: 'how far can I walk in 15 minutes?', cycling equivalents, delivery coverage, and before/after scenarios using exclude_polygons. It gives clear context but does not explicitly name alternatives or say when not to use this tool versus route or matrix.

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 richly: statelessness ('nothing is stored', 'MapMap holds NO dispatch state'), the need to pass the full original problem, the locked-prefix guarantee by construction, refusal of `reloads` vehicles, billing on the remaining problem, and the contents of the `replan` response block. No annotation contradiction exists since no annotations were provided.

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 and every sentence carries genuine behavioral information, but the description runs roughly 280 words. Passages like 'left for a dispatcher to notice at four in the afternoon' and 'go stale, leak, or fall out of step' are colorfully worded and could be tightened without losing meaning. Dense and valuable, but not concise.

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?

Complete for a complex 11-parameter tool: it covers the required input (full original problem), the qualifying condition, locked-stop behavior, the output shape (`optimise_routes` shape plus `replan` block), refusal cases, billing, and the gateway requirement. The output schema exists, and the description still adds the `replan` block semantics on top.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it names and interrelates the replan-specific parameters (`progress`, `changes`), stresses the strict serving order of `completed_stop_ids`, states the 'at least one of progress or changes' requirement, and explains that vehicles with `reloads` cause a refusal. This goes beyond what the JSON Schema alone communicates.

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 pairing: 'Re-plan a fleet part-way through its shift.' It clearly distinguishes itself from the sibling `optimise_routes` by defining what a re-plan is (original problem plus progress/changes) and what it is not (a delta against stored state).

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 frames the trigger condition: part-way through a shift, and 'At least one progress entry or one change is required' — a re-plan reporting nothing new is 'the original problem' (i.e., call `optimise_routes`). It also names a hard exclusion: multi-trip vehicles declaring `reloads` are refused, with direction on what to send instead.

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

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

With no annotations, the description carries the full behavioral burden. It clearly states the report is QUEUED for human/agent review, NEVER changes routing immediately, and NEVER edits any map, plus it names the return value (report_id). This prevents the agent from assuming immediate side effects.

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

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

The description is compact and front-loaded with purpose, then moves to usage trigger, parameter requirements, and side-effect caveat. Every sentence contributes needed information; there is no filler or repetition of 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 5-parameter tool with no annotations, the description covers purpose, when to use it, parameter requirements, behavioral consequences, and return value. The output schema exists and the description explicitly names the queued report_id, so nothing needed to invoke 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 coverage is 100% with per-parameter descriptions and category enum semantics, so the baseline is 3. The description usefully compresses required vs optional parameters and lists category values, but adds little meaning beyond what the schema already provides.

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: 'Report that the live world disagrees with the map' and enumerates seven concrete mismatch types. None of the 33 sibling tools covers map-issue reporting, so this is unambiguously distinct.

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 trigger: 'Use it when you observe the mismatch mid-task.' It doesn't name exclusions or alternatives, but there are no obvious sibling alternatives, and the queued-observation framing helps the agent understand the tool's role.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no annotations, the description carries the full behavioral burden and meets it extensively: it discloses that avoid is a preference not a guarantee (Dartford example), exclude is requested never promised, rationale costs up to 1+N calls, preferred_side is a snapping preference needing an offset coordinate, landmarks may return none, and ADR tunnel_applied describes the load not the route. It also explains engine/GraphHopper differences and gateway dependency.

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 has 13 parameters and many caveats, and nearly every sentence earns its place by adding behavioral nuance or a failure mode. It is front-loaded with the core computation before the option deep-dives. It could be tightened in places, but the length is defensible for this complexity.

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

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

Given a 13-parameter tool, a complete output schema, and no annotations, this description covers everything an agent needs to call the tool correctly: required locations, optional waypoints, engine support, external gateway requirements, cost implications, honest limitations, and feature-specific behavior. There are no obvious gaps that would cause incorrect invocation.

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?

Even though schema coverage is 100%, the description adds meaning beyond the schema: it maps costing names to everyday vehicles, spells out truck/pedestrian/bicycle tuning intent, distinguishes avoid vs exclude with consequences, explains 'longitude FIRST' for polygons, and clarifies that preferred_side aliases resolve against the locale's driving side. This is substantive semantic enrichment, not restatement.

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: 'Compute a turn-by-turn route between origin and destination (optionally via waypoints).' It also lists concrete outputs (distance, duration, maneuvers, polyline6 geometry) and costing options, so an agent can clearly tell this is the point-to-point routing tool rather than matrix/geocoding or other 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?

There is rich guidance for when to use individual features (truck ADR, pedestrian accessibility, rationale, landmarks, exclude_polygons, emissions) and clear warnings about engine support. However, the description never names sibling tools or states when to use route instead of matrix, plan_ev_route, match_trace, search_along_route, or reachable_area; usage vs alternatives is only 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 of behavioral disclosure and does so thoroughly: it gives the exact detour formula, the candidate cap of 25, result fields, costing modes, truck ADR/dimensional restrictions, and server-side category normalization. It also explains how query alone can promote a category phrase to category browsing, making the tool's behavior predictable.

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, and the key differentiator is front-loaded: real detour time, never a straight-line guess. The content is organized around input modes, query/category behavior, detour computation, costing, and output, which makes even a dense description navigable.

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 tool with no annotations and rich semantics, the description covers input alternatives, defaults, limits, category vocabulary, detour mathematics, costing behavior, and returned fields. Since an output schema is present, return-structure details are already covered structurally, and nothing necessary 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?

Although schema coverage is 100%, the description adds substantial semantic value beyond the schema: it clarifies the query/category distinction, the mutual exclusivity of geometry_polyline6 versus origin+destination, the default and maximum detour minutes, and how costing profiles influence detour computation. This materially improves an agent's ability to choose and format parameters 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 opens with a specific verb and resource: 'Find places (POIs) along a route' and immediately distinguishes the tool by emphasizing real detour time rather than a straight-line guess. It also signals how it relates to nearby_places through shared category vocabulary, making the tool's scope clear.

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

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

The description explicitly covers two input modes (origin+destination vs geometry_polyline6) and gives detailed guidance on when to pass category versus query, including server-side normalization behavior. It does not explicitly state when to prefer this tool over sibling alternatives such as cheapest_fuel_along_route or nearby_places, so exclusions to alternatives remain implicit.

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

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

With no annotations, the description must carry the burden of behavioral transparency. It discloses that the operation is non-destructive in effect by publishing 'a new immutable style version', and it states the returned artifacts ('new version and style URL'). It does not mention permissions or failure modes, but the core side-effect is clearly communicated.

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 deliver the verb, target, scope, example, prerequisite id source, and return value with no filler. The most important information is front-loaded, and every phrase 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 description is functionally complete: it states the operation, target, examples, where layer ids come from, and what is returned; an output schema handles return shape. It could explicitly mention set_palette as the multi-property alternative for full sibling differentiation, but the gap is 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?

The schema already describes all four parameters in detail, including value types and examples. The description adds a concrete example ('road-major', 'line-width', '4') and reminds the agent that expressions are valid, but this largely mirrors the schema's existing documentation. With 100% schema coverage, the description's added semantic value is modest.

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 precise operation: 'Set one MapLibre paint property on one skeleton layer of a hosted style', immediately clarifying scope and context. It also explains the outcome ('publish the result as a new immutable style version') and explicitly contrasts this with related styling tools by using 'one property' and 'one skeleton layer'.

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 clearly establishes when to use this tool: when you need to change a single paint property on a layer, and it tells the agent where to get valid layer ids ('Layer ids come from list_style_layers'). It does not explicitly contrast with set_palette or state when not to use it, but the single-layer/single-property framing is clear 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 provided, the description carries the full burden of behavioral disclosure. It reveals that this operation publishes a new immutable style version, which implies the existing style version is not mutated, and it states the return value. It could additionally mention side effects like publication visibility, 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?

The description is a single dense sentence that front-loads the action, includes a concrete example, covers input sources and colour syntax, and states the return value. There is no fluff 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?

The description covers what the tool does, how to find slot names, allowed colour formats, and the return value. Since an output schema exists, detailed return documentation is unnecessary. A brief note drawing the boundary against set_layer_paint would make it fully complete, but nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by enumerating accepted CSS colour formats (#rgb, #rrggbb, #rrggbbaa, rgb(), hsl()) and providing a concrete example of the colours object. This helps the agent construct valid parameter values.

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 action ('Recolour one or more palette slots'), a specific resource ('hosted style'), and a distinctive outcome ('publish the result as a new immutable style version'). It clearly separates this from siblings like set_layer_paint by focusing on palette slots rather than layer paint properties.

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 operational context: it tells the agent to obtain slot names from list_style_layers and explains how colours should be formatted. It does not explicitly compare against siblings such as set_layer_paint or create_style, so exclusion guidance is implied 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, the description carries full behavioral disclosure. It clearly states the tool only sends structured schema fields, never conversation or code, and that it should be called at most once. This covers the key side effects and privacy boundary a caller needs to know.

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: purpose, invocation constraints, and field summary. Every sentence earns its place, and the most critical 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 description is complete for this tool: it specifies when to call, what conditions must be met, what is sent, what is not sent, and which fields are required or optional. The output schema exists, so not explaining return values is acceptable. Nothing needed 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 every parameter in detail. The description adds a useful summary of required vs. optional fields, but does not materially expand on the schema's own description of each parameter. 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: 'Send MapMap a structured integration retro'. It clearly distinguishes this tool from the geo/mapping siblings by naming the unique feedback purpose.

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?

Description provides explicit when-to-use guidance: 'Call at most once, after your MapMap integration works or you stop trying, and only if the developer has approved sending feedback to MapMap.' This is precise and leaves no ambiguity about invocation conditions.

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 burden and does so richly. It discloses that the tool returns a 202-and-job-id, not a plan; that jobs are queued and processed asynchronously; that unknown fields are refused by name rather than dropped; that polling is free; that units are charged on submission and refunded on failure; and that webhook_url delivers a signed pointer, never the result. These are substantial behavioral traits beyond the schema.

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

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

The description is long, but every sentence conveys a distinct and necessary fact: purpose, parameter mapping, refusal behavior, ceilings, re-plan counting, response semantics, polling cost, billing, and webhook guidance. It is front-loaded with the core purpose and then structured to cover the tool's edge cases. Nothing is redundant or 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 complex asynchronous submission tool with no annotations, the description is remarkably complete. It covers purpose, alternatives, parameter semantics, error behavior, quotas, billing, result retrieval via get_job, and optional webhook usage. The output schema may handle return value structure, but the description provides all contextual and operational knowledge an agent needs 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 significant meaning. It explains the kind values map to specific synchronous input shapes, elaborates on the problem parameter with the exact-shape requirement and refusal behavior, and details webhook_url semantics including HTTPS-only, signed notifications, pointer-not-result, and the agent-should-poll caveat. This goes well beyond the schema descriptions.

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

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

The first sentence states a specific verb and resource: 'Submit a problem too large to solve inside one request to the asynchronous lane, and get a job id back.' It clearly differentiates this tool from synchronous siblings like optimise_routes and replan_routes, and from get_job which polls the result. The purpose is unambiguous and distinct.

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 states when to use the tool: for problems too large for a single synchronous request. It names the matching synchronous tools and says moving a working synchronous call changes nothing but the tool. It also gives a clear exclusion for webhook_url: 'An agent that can poll should not use it.' This is explicit when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description fully carries the behavioral burden and does so thoroughly. It discloses the return shape (verdict, plain-language problem, alternative interpretation), states that no coordinate transformation occurs, and guarantees local computation with no network call or quota. This gives an agent a complete picture of side effects and non-effects.

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?

Every sentence earns its place: purpose, failure modes, input prescription, output summary, and capability boundary. The description is dense but not bloated, and the most decision-relevant 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 2-parameter validation tool with a full output schema present, the description covers what matters: what the tool checks, why it exists, what inputs to provide, what outputs to expect, and what it will not do. An agent has everything needed to select and invoke it correctly without additional context.

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

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

The schema already covers 100% of parameters, so the baseline is 3; the description adds real value beyond that by explaining why parameters are named x/y rather than lon/lat, giving concrete EPSG examples, and advising that 'a few dozen is plenty'. This helps the agent construct sensible inputs without restating schema content.

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 gives a precise verb-check, a specific resource (a dataset's declared CRS against its own coordinates), and a concrete use moment ('before you draw it on a map'). It also names example failure modes (swapped axes, degrees labelled as metres), making the tool's job unmistakable and distinct from the many geo 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 description clearly frames when to use it ('before you draw it on a map') and explicitly excludes a major misuse case ('a sanity check, not a reprojection: it never transforms coordinates'). It does not name an alternative tool for reprojection or other coordinate operations, so it stops just short of explicit alternative routing.

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

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

With no annotations provided, the description carries the full behavioral burden and exceeds it: it explains the non-boolean verdicts, the defamation-avoidance rule, how sequence/claimed_time trigger routing-based contradiction checks, the 20-claim limit, and that `summary` is surfaced as text content. This is exemplary disclosure for a tool with this complexity.

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?

Though long, every sentence earns its place: purpose, mode selection, verdict semantics, a crucial behavioral caveat, itinerary feasibility, request limits, and output-format note. The structure front-loads the primary action and then layers necessary detail without fluff.

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

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

For a tool with three parameters, no annotations, and real behavioral nuance, the description is complete: it covers input-mode tradeoffs, verdict semantics, constraints, edge-case behavior, and response-format quirks. The presence of an output schema means the description does not need to enumerate return fields, and nothing an agent needs to call 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 coverage is 100%, so the baseline is 3. The description adds real semantic value beyond the schema by labeling `claims` as the reliable path, `text` as best-effort heuristic extraction, and explaining why `sequence` and `claimed_time` together enable feasibility checks. It does not merely repeat 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?

The opening sentence states a specific verb and resource: checking whether places and itineraries an AI mentioned are real, findable, and physically possible. The three-verdict model (verified/contradicted/unverified) further sharpens what the tool does and clearly distinguishes it from geocoding or place-search siblings.

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

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

The description explicitly tells agents when to use structured `claims` versus free `text`, and notes that only `claims` supports itinerary feasibility. It does not explicitly name sibling alternatives like `geocode` or `nearby_places` as things to use instead, but the usage context is clear enough for a unique-purpose tool.

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