PlaceRoot

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

Beyond the read-only/idempotent annotations, the description discloses important behavior: optional attributes are omitted when absent, empty results are valid and carry an explanatory note, structured errors are returned for upstream/data/coordinate issues, and no id is returned because ids are not GERS-stable. This is substantial extra 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 each paragraph earns its place: output format, relation to siblings, id stability, coverage caveats, and error behavior. The most important 'nearest first' detail is front-loaded, and the return shape is given concretely.

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 the return shape, ordering, optional-field omission, result cap, coverage limitations, empty-result semantics, error cases, and the no-id policy. Given the tool's complexity and the annotations provided, nothing critical is missing 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?

The input schema has 0% description coverage, so the tool description must explain lat, lon, and limit. While it mentions 'a point' and says results are capped at 5, it never explicitly names or explains the limit parameter, its default, or coordinate constraints. This leaves meaningful ambiguity for a 3-parameter tool.

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

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

The description states a specific verb and resource: returns nearest street addresses to a point, ordered nearest first, with the exact fields returned. It also explicitly distinguishes itself as the address-level counterpart to reverse_geocode, so an agent can tell them apart.

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: use this when you want doorway-level address attributes near a point, and use reverse_geocode when you need a stable reference via the division. It also warns about coverage gaps, making it clear when results should not be expected.

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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses result ordering, the meaningful empty-chain case, and structured error behavior for upstream or dataset schema failures. No contradiction with annotations exists.

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

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

The description is compact and front-loaded: purpose, method, output shape, ordering, empty-result meaning, and errors are each covered in a useful sentence. There is no redundant or filler 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?

Given the output schema exists and annotations cover safety and idempotence, the description still supplies the important contextual details: hierarchy order, empty chain as a valid answer, and failure modes. An agent has enough to call and interpret 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?

With 0% schema coverage, the description's 'point' and 'point-in-polygon' wording clarifies that lat/lon are a geographic coordinate pair. However, it does not specify coordinate system, decimal-degree format, or valid ranges, so parameter meaning is only partially compensated.

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 the tool returns the admin hierarchy for a point from neighborhood up to country, and names the point-in-polygon method against Overture's divisions theme. This is specific enough to distinguish it from reverse_geocode, address_at, and other sibling lookup 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 intended use case is explicit: given a lat/lon point, get the chain of containing administrative divisions. It does not explicitly name alternatives or exclusion cases, but the scope is clear and edge-case semantics are explained.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds valuable behavioral context beyond annotations: it discloses the no-raw-geometry-by-default design rule, the include_geometry=true caveat with token cap and geometry_max_deviation_m reporting, and the structured error behavior when upstream is unavailable or dataset is missing geometry/bbox. That is more than annotations provide. Not a 5 because it doesn't mention pagination or ordering ties, but the disclosed behaviors are meaningful.

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 moderately sized but every sentence earns its place: the return shape, the no-geometry design rule, the include_geometry consequences, and the error case are all covered. It front-loads the core purpose and leads with the most important semantic ('nearest first'). Slightly dense parenthesis nesting costs a little readability.

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 annotations cover safety and idempotence, the output schema is explicitly illustrated in the description, and the tool is a simple point-query with 5 params, the description is complete. It even discloses edge cases (upstream unavailable, missing geometry/bbox) and the design rule behind default behavior. An agent can call this correctly without additional documentation.

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

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

Schema coverage is 0%, so the description carries the full burden. It explains include_geometry in detail and implies radius_m and limit via 'nearest ... nearest first', but doesn't specify units for radius_m (meters are inferable from the name), default/range semantics, or limit semantics beyond a list length. With 5 params at 0% coverage, a 3 is the minimum viable; the description compensates for the most important parameter but leaves lat/lon/radius_m/limit to 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?

States a specific verb+resource ('Nearest building footprints to a point, nearest first') and differentiates from siblings: it's clearly a point-query tool (like infrastructure_at, land_use_at, water_near) targeting building footprints. The scope is unambiguous: buildings near a point, not places, infrastructure, or areas.

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

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

The description explains the design rule ('answers, not data') and the optional include_geometry behavior, giving context for when to use the default versus when to pass the flag. It doesn't explicitly name alternatives or exclusions like infrastructure_at for non-building features, but the phrasing 'building footprints' and the sibling list imply the boundary. Slight gap: no explicit 'use X for other features' guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's job is to add behavioral context — and it does so richly. It discloses structured error modes (ambiguous_area with candidates, not_found, bad_request for oversized areas and partial release pairs, upstream_unavailable), the default release window resolution, degraded_fields schema-drift behavior where 'everything reads as changed', truncation/omitted_count semantics, and the honest-framing 'notes' caveat that a disappearance may be data cleanup rather than a closure. This goes far beyond what annotations 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?

Front-loaded with purpose and usage before parameter detail, and organized into clear paragraphs per parameter group. It is lengthy, but every section carries substantive content. Minor redundancy exists — degraded_fields is mentioned both in the release-window guidance and in the return-format section, and the final error paragraph restates upstream_unavailable behavior already described — but for a 9-parameter tool with 0% schema coverage, this depth is largely earned rather than padded.

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

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

For a tool of this complexity (9 params, release-window semantics, size caps, multiple error modes, nuanced return digest), the description covers every dimension an agent needs: parameter semantics, defaults, edge cases, error contracts, truncation behavior, and interpretive caveats about what appeared/disappeared actually mean. Even though an output schema exists, the description adds semantic nuance (exact counts, by_category denominators, degraded_fields warnings) that structured schemas cannot express. Nothing needed for correct invocation or result 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 description coverage is 0%, so the description carries the full burden for all 9 parameters — and it does so exhaustively. place gets free-text resolution semantics plus ambiguous/not_found error behavior; the four bbox params get their all-or-none constraint and size cap; category gets its both-sides-identically filter semantics and the 'disappeared' interpretation; from_release/to_release get defaults, validation rules, and the partial-passing bad_request; limit gets its default (8), hard cap (25), and the fact that counts/by_category are never reduced by it. No parameter is left to schema inference.

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-driven statement of what the tool does: 'What's opened or closed around here since a past Overture release.' It then explicitly distinguishes itself from every sibling: 'every other tool here answers against a single, current snapshot of the data; this is the only tool that compares two.' An agent can immediately tell this apart from compare_areas (two areas, one snapshot) and find_places (one snapshot, no time dimension).

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

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

Provides concrete example queries ('what's new around here', 'what's closed since spring') and an explicit selection rule: any question with a time dimension belongs here because no other tool compares two releases. It also implicitly gives the when-not-to-use condition (single-snapshot questions should go elsewhere) and later warns against too-large areas, routing the caller to a neighborhood/district or bbox 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?

Annotations already mark this read-only and idempotent; the description adds substantial extra behavior: resolution errors, GERS/name fallback, structured errors, degraded verdict behavior, caveats about boundary vs radius, and a map payload that splats into render_map. No contradiction with 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 very long, but it is organized into coherent paragraphs (core result, priority scoring, map payload) and front-loads the purpose in the first sentence. Every major behavior is concretely specified; the length is mostly earned, though it could be tightened.

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 exhaustive for this tool's complexity: it documents input formats, edge cases, error behavior, scoring formulas, degraded-data behavior, and integration with render_map. Given the rich nested behavior and sparse schema, nothing needed 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 0%, so the description carries the full burden. It fully explains areas (dict, GERS id, or name), the shared radius_m, and every field of priorities, including constraints like up to 6, weights 0.1-5, and valid prefer values. This is exemplary compensation for the bare 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 clearly identifies the verb and resource: compare 2-5 areas side-by-side, with specific dimensions (category mix, density, differences). It is unambiguous and distinct in behavior, but it does not explicitly contrast this tool with sibling tools such as summarize_area or changes_in_area.

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

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

The context is very clear: use this when comparing 2-5 centers, and it details optional priority-based scoring. It does not explicitly state when not to use it or name alternative tools, so it misses full alternative routing, but the intended scenario is obvious.

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

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

The description adds substantial behavior beyond the annotations: values are resolved once at process start, cached for the process lifetime, and not re-checked upstream. It also explains the three possible provenance sources and its shared implementation with the placeroot resource, giving an agent accurate expectations about freshness and reliability.

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 purpose stated in the first sentence and each following sentence adding meaningful detail: output fields, caching behavior, and alignment with the resource surface. No sentence is filler or redundant with the schema or annotations.

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

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

For a zero-parameter, read-only, idempotent tool with an output schema, the description is complete. It explains what the value reports, how it was resolved, its stability, and its relationship to the data-version MCP resource, leaving no practical gap for an agent deciding whether or how to call it.

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

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

The tool has zero parameters and the schema is empty, so there is nothing for the description to clarify about arguments. The description instead explains what the report contains, which is all that is needed for a parameterless informational tool.

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

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

The description opens with a precise, non-generic statement: 'Which Overture Maps release backs the answers from every other tool.' It then names the exact outputs (release string, date, provenance), making the tool's function unmistakable and clearly distinct from the geographic 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 the tool: whenever an agent needs to know the underlying Overture release behind all other tools. It does not explicitly name alternatives, but no sibling offers this function, and it adds exclusions by noting the tool does not re-check upstream, clarifying it is not a live-source lookup.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description adds substantial behavioral context beyond that: the 10-point cap with 100-pair limit, error handling for unresolved names with indexed errors and ambiguity candidates, check ordering (cap fails first), the 'resolved' field behavior, flat origin-major return order, empty-input handling, and structured bad_request errors. No contradiction with 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 long but every sentence earns its place. The first sentence front-loads the core function, then paragraphs cover scope limits, alternatives, error semantics, resolved-field behavior, output format, and edge cases. There is no fluff or repetition; dense paragraphs are organized by topic.

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

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

Despite the output schema being present, the description also details the return shape and ordering, covers empty input, error behavior, id/name resolution, and budget hints. With sibling differentiation and clear parameter semantics, nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 0%, so the description must carry the full burden. It fully compensates by explaining that origins and destinations are lists of LocationRefs with three acceptable forms (lat/lon dict, GERS id, free-text name), that they can be mixed freely, that each is capped at 10, and how unresolved strings are reported. This goes far beyond the plain array/string 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 precise verb+resource statement: 'Straight-line (great-circle) distance in meters between every origin and destination.' It immediately distinguishes itself from routed-distance or travel-time tools by calling the calculation a plain haversine and explicitly saying what it is NOT, which differentiates it from travel_time_matrix and Google/Mapbox APIs.

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

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

The description gives explicit when-to-use and when-not-to-use guidance, naming alternatives: use isochrone() for 'how far can I get in N minutes' and travel_time_matrix() for routed times/distances. It also characterizes the tradeoff (cheap but not routed), making the selection rationale 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description goes well beyond this: it discloses nearest-cell (non-interpolated) sampling and the accuracy caveat on steep slopes, the exact success return shape, the non-error null+note behavior for no coverage, and the structured error case for out-of-range coordinates or fetch failures. This fully specifies the behavioral contract.

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

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

The description is front-loaded with the core purpose and then builds out the data source, sampling semantics, return contract, error contract, and attribution in clearly separated paragraphs. Every paragraph earns its place; the middle sentence about "the same open-data pattern every other tool here uses" is mildly redundant context and could be trimmed, but the overall structure is efficient for the amount of behavioral detail conveyed.

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 read tool, the description is complete: purpose, data provenance, resolution, accuracy caveats, success return shape, the non-error null path, the error path, and attribution are all covered. The output schema's existence plus the explicit return-shape documentation means an agent knows exactly what to expect before and after invoking the tool. 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 0%, so the description must compensate. It does partially: "at a point" maps the two required numeric params to a coordinate pair, and "out-of-range coordinate" signals that lat/lon have validity bounds. However, it never states the coordinate format or the actual valid ranges (lat -90..90, lon -180..180), leaving the agent to rely on geographic convention.

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: "Ground elevation in meters at a point, from Copernicus GLO-30 (~30 m resolution)." It names the exact data source and measurement, making it easy to distinguish from sibling point-lookup tools like buildings_at, land_use_at, and address_at. The purpose is unambiguous and non-tautological.

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 tool's purpose is specific enough that an agent can infer when to use it (any time elevation at a coordinate is needed), and the coverage/error notes clarify when results will be null or failed. However, it never explicitly names an alternative or states when not to use this tool versus a sibling. The open-data pattern remark references other tools generally but provides no routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower, but the description adds substantial behavioral context. It documents error responses for ambiguous, unresolved, and bad input, the compact row shape, comma-qualified place scoping, and cursor delegation.

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

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

The description is front-loaded with the core purpose and every sentence contributes useful information about behavior, errors, or alternatives. It is fairly long and repeats the 'one hop' idea, but the density is justified by the tool's error-handling and pagination 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 5 parameters, sibling-alias relationship, and cursor behavior, the description is complete: it covers invocation, result shape, error responses, pagination continuation, and the relationship to find_places. The output schema and the referenced find_places docstring cover the remaining 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?

Schema description coverage is only 20%, so the description must compensate, and it does: near is explained as a user-supplied place name with comma-scoping behavior, and radius_m/limit clamping plus cursor continuation are defined. It does not enumerate valid category values, but enough is provided for correct invocation.

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's action and resource: finding places of a category near a named place or city. It also distinguishes itself from the canonical sibling find_places by explicitly calling itself a thin alias with one-hop behavior.

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 directs agents to prefer find_places(where=..., category=...) and explains that find_near is only a thin alias. It also instructs the agent to pass the user's place name as near and not to call geocode(), resolve_place(), or geocode_batch() first, giving concrete when-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?

Even though annotations already mark the tool read-only and idempotent, the description adds substantial behavior: ambiguity errors instead of silent selection, name-fallback tiers with matched_by, cursor identity rules, detail being presentation-only, brand sparsity caveats, and the needs_confirm cold-graph flow. Nothing contradicts the readOnlyHint, idempotentHint, or destructiveHint 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 long, but justified by 20 parameters and three modes, and its labeled mode/filter/pagination/detail structure makes it navigable. It is not perfectly concise—roadmap references such as '#373', 'ROADMAP §4.4', and 'roadmap feature 5' are incidental noise for an agent—so it falls just short of a 5.

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

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

For a tool this complex, the description covers input modes, output shapes, error contracts, per-mode ordering, pagination, projection tiers, degraded columns, and data-caveat behavior. The output schema exists, but the description adds the error responses, cursor semantics, and per-mode behavioral rules 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 only 15%, and the description compensates thoroughly. It explains defaults like radius_m=1000, the where forms (lat/lon dict, GERS id, free text), operating_status relabeling, categories/group_by_category semantics, within/confirm, cursor, and detail tiers. Even limit receives indirect explanation through pagination and grouped-row behavior.

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

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

The opening sentence identifies a specific operation—finding named places—and the two spatial contexts (near a point or inside an area boundary). It also distinguishes itself from siblings by noting that named search is one hop and needs no prior geocode()/resolve_place() call, and later points to search_categories and place_details where relevant.

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 three mutually exclusive modes are clearly specified with their exact parameter combinations and the errors for mixing them. It gives routing guidance: skip geocode/resolve_place for named searches, use search_categories when a category slug matches nothing, and use place_details when full website/phone arrays are needed.

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

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

Annotations mark this read-only and idempotent, and the description agrees without contradicting them. It goes far beyond annotations by detailing exact error shapes ('ambiguous_place', 'too_far', 'not_found', 'bad_request'), per-mode distance caps (7.5/23.5/95.5 km), the maybe-needed 'confirm' delay for first-time graph builds, and pass-through parameter behavior with caveats like 'avoid needs mode="drive"'.

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 paragraph earns its place: input format, error handling, caps, pass-through params, and confirm behavior are each given a compact block. It is front-loaded with the one-sentence summary, and the alternative tool is identified in the second 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?

For a routing tool with 8 parameters and 38% schema coverage, the description covers all invocation-critical details: input resolution, errors, mode defaults, graph-build confirmation, and what outputs are returned. The existing output schema and read-only/idempotent annotations cover the remaining structural expectations.

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 only 38%, yet the description thoroughly compensates. It defines the accepted 'from/to' forms (free-text name, {"lat", "lon"} dict, GERS id, mixed), clarifies the default mode ('stored preferences mode, else walk'), and details 'confirm' semantics ('warm or cached graph never needs it'). It even explains the meaning of 'prefer' and 'avoid' via route() semantics.

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

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

The description opens with 'Shortest-path walk, cycle, or drive between two places,' a specific verb/resource combination that exactly matches the tool name and title. It then explicitly contrasts itself with the sibling 'route' tool: 'from_to is route() with LocationRef ends and a walk default; route is the canonical routing tool.' This makes the tool's unique role unmistakable.

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 direct routing guidance: 'prefer route(from=..., to=...) once it takes them,' telling the agent when to use the sibling instead. It also forbids unnecessary upstream calls ('Do not call geocode(), resolve_place(), or geocode_batch() first') and precisely conditions the confirm flag on user consent ('Pass it only after a needs_confirm reply and they said yes').

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description goes far beyond them. It discloses ranking order (exact > prefix > substring), fallback to places, budgeted execution, structured error return instead of raising, empty-result notes, fuzzy retry, postcode handling, exonym matching, lang variants, and home-region bias. This is a thorough disclosure of the tool's hidden behavioral traits.

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

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

The core purpose is front-loaded in one clear sentence, and the subsequent paragraphs are organized by scenario. However, the description is very long, with embedded issue numbers (#105, #215, #223, #214, #410, #406) and repeated caveats that add clutter. It is structured and relevant, 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?

The description covers the return schema, error behavior, empty-result notes, fuzzy matching, postcode edge cases, exonym behavior, language preferences, and home-region bias. It tells the agent exactly what to expect in every described scenario and when a 'note' will appear. No critical usage aspect is missing.

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

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

The schema only describes 'lang'; 'query' and 'limit' are bare. The description compensates by explaining 'lang' in detail (language-tagged variants, never transliterated) and characterizing 'query' as a free-text place name. It provides minimal direct explanation of 'limit' beyond the budgeted context, but the intended meaning is still inferable.

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 line 'Free-text place name -> ranked candidate locations, from Overture divisions and places' states a clear verb, resource, and input scope. It also explicitly disclaims Nominatim and third-party APIs, distinguishing the tool from external geocoders. The description's scope clearly separates it from siblings like reverse_geocode (coordinates→place) and geocode_address (structured addresses).

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 defines what kind of input qualifies ('free-text place name') and what entity types it covers (localities, neighborhoods, regions, countries). It does not explicitly name sibling alternatives or state when to avoid this tool, such as using geocode_address for structured addresses. The usage context is clear, but explicit exclusions are missing.

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?

Even though annotations already declare readOnly, idempotent, and non-destructive behavior, the description adds substantial operation traits: city-first resolution, boundary bounding, empty-plus-note semantics, no interpolation of missing numbers, country-boundary safeguards, and alpha coverage limits. It also discloses exact match-mode behavior, which is valuable beyond the annotation hints.

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 dense and well-structured, with the core transformation front-loaded at the top. Each paragraph adds a distinct behavior — parsing, resolution, matching, edge cases, coverage — so every sentence earns its place; no repetitions 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 tool with optional parameters, multiple input modes, subtle matching semantics, and edge cases, the description is exceptionally complete. It covers query grammar, structured input, city-boundary behavior, empty results, truncation, deduplication, matching fallbacks, and geographic coverage, leaving virtually no ambiguity about invocation or expected behavior.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it delivers. It explains how to format the query string, including comma separation and house-number placement, and describes when to use the structured number/street/city alternatives. It also clarifies limit behavior through truncation semantics, making the parameters meaningful beyond their names and defaults.

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 crisp transformation statement — "Street address -> coordinates" — and immediately gives a concrete example. It distinguishes itself from address_at and geocode by naming them and specifying the granularity difference, so an agent can tell exactly what this tool resolves and at what precision.

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 positions this as the forward counterpart to address_at and finer than geocode, telling the agent when geocode would be the wrong choice. It also gives a clear alternative invocation — "Pass number/street/city instead if you already have the parts" — so the agent knows when to use the structured parameters rather than the single query string.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: per-query error envelopes, batch cap at 20, structured errors instead of raising, and non-failing of the rest of the batch. However, it states 'keeps only the top candidate' while the input schema includes limit_per_query with a default of 3, and that parameter's behavior is never explained, creating an incomplete and potentially misleading behavioral model.

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 organized and mostly information-dense: purpose, motivation, output format, then failure behavior. The implementation-specific notes like '#329' and 'cold S3 scans' add useful rationale, though 'Budgeted like every other tool' is vague and earns little weight. Overall it stays front-loaded and readable.

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

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

The description is quite complete for a read-only batch operation: it covers input cap, output shape, per-query error isolation, and remote failure behavior. The major gap is the undocumented limit_per_query parameter, which affects actual behavior and is central to calling 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 0%, so the description must carry the full semantic burden for parameters. It does explain that queries are free-text and capped at 20, but it never mentions limit_per_query, its default, or the effect it has on the returned candidates. With a parameter silently left unexplained, agents cannot correctly tune or even predict the tool's output.

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: 'Geocode up to 20 free-text queries in one call, one best match each.' It explicitly contrasts with geocode() by framing itself as the batched replacement, so an agent can tell it apart from both geocode and the other sibling tools 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 motivates when to use this tool: when you have N free-text names to geocode, it cuts N round-trips to one and avoids repeated cold S3 scans. It does not explicitly say 'use geocode for a single query' or list exclusion cases, but the batching rationale makes the intended usage 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?

Annotations already mark read-only/idempotent/non-destructive, and the description builds on this with concrete error responses, coordinate range checks, structural-only validation of geometries, accuracy caveats, and the DuckDB execution note. This is more behavioral detail than most tool descriptions provide.

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

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

Long but tightly organized: one-line op signatures with outputs, grouped notes for shared behavior, and a final validation/accuracy section. Every sentence supplies operational information with no filler.

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

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

For a 9-parameter dispatcher with 16 operations, the description covers selection, input shaping, output shapes, error behavior, caps, and precision caveats. Nothing needed to call it correctly is missing, even without opening the schema.

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

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

Schema coverage is only 11% and the geometric params are untyped anyOf blocks, so the description carries the full burden. It defines point shape, GeoJSON geometry, per-op signatures, caps (100 points), and edge-case empty results, fully compensating.

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

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

Opens with 'Geometry math and predicates — one tool, many ops,' immediately stating the verb, domain, and dispatch nature. The full enumerated operation list makes it impossible to mistake for any sibling.

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

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

The op list plus 'pass only the params it needs' gives clear selection guidance for choosing an operation. It also says geometry outputs are already simplified to simplify_geometry's token targets, so no chained simplification call is needed. It does not explicitly contrast with distance-matrix or routing siblings, but the scope 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?

Annotations already declare the operation safe and idempotent, and the description adds substantial behavioral detail beyond that: the hint bounds the search rather than ordering it, out-of-box ids return not_found, transportation ids are not resolvable yet, and the exact error shapes for malformed ids and upstream failures. It also states 'never geometry', clarifying a common expectation.

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

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

The description is dense but every sentence earns its place: core purpose first, then hint semantics, then error behavior. The structure is logical and front-loaded, with no filler or repetition of annotation metadata.

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

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

Despite having an output schema, the description still enumerates the returned entity fields, the theme-specific summary fields, and the related object. It also covers the non-trivial edge cases of unresolvable ids, malformed ids, out-of-range hints, and upstream failures. An agent has everything needed to call this tool correctly and interpret its results.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it succeeds. It explains that id is an opaque 32-character lowercase hex token, defines near_lat/near_lon as optional hints derived from the source row, and describes the consequences of including or omitting them. This goes far beyond the bare 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 exactly what the tool does: given any GERS id, return the entity it names across themes. It explicitly positions itself as 'the reverse of every other tool' and names the entity fields, making it easy to distinguish from sibling lookups and search 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 explains when to use this tool: whenever another tool returns a GERS id and you need the underlying entity. It also gives explicit guidance on the near_lat/near_lon hint, including when to pass it, when not to, and its effect on performance and results.

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

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

Annotations already mark the tool as readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond that: per-section independent failure with notes, structured bad_request vs upstream_unavailable errors, no geometry ever returned, no confirm gate, self-capping of the graph extraction radius, and degradation of the reach section to a note. This far exceeds the baseline.

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 well-organized with a one-line summary, clear return-section bullets, and a short list of edge cases. It front-loads the core purpose and keeps related facts grouped. It loses one point because a few details are slightly redundant, such as repeating the mode default that already appears in the schema and restating bad_request behavior in two places.

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

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

Given the tool's complexity, the description is remarkably complete: it covers input cardinality, accepted formats, bounds, error modes, per-section degradation, and even the deliberate absence of geometry. An agent has everything needed to invoke this tool correctly and to interpret unexpected per-section outcomes, especially with an output schema also present.

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 only 20%, but the description compensates thoroughly. It explains the mutually exclusive lat/lon vs where inputs and the bad_request result when both or neither are supplied, enumerates valid where forms (dict, GERS id, free-text name), explains the resolved key, constrains minutes to (0, 60], and clarifies mode default behavior. This is exactly the semantic guidance the sparse schema lacks.

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-plus-resource: 'Ground a location' with 'One-hop location grounding: where, surroundings, reach, notable.' It clearly distinguishes itself from sibling chainable tools by promising a single call that replaces a reverse lookup, area summary, reachable-area scan, and nearby-places search. The purpose is unmistakable.

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

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

It explicitly identifies when to use the tool: 'Answers "orient me at this point" in a single call instead of chaining' the four underlying operations. This gives an agent a concrete decision rule and names the alternatives it replaces, without requiring it to infer from sibling names alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is about added context. The description adds substantial behavioral detail: radius clamping, distance measured to closest point rather than centroid, empty results as a valid answer, truncation/note behavior, GERS id semantics, no raw geometry, and structured error cases.

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

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

The description is long but organized into purposeful paragraphs: summary, data caveat, filtering guidance, output shape, radius behavior, and error handling. It is front-loaded with the primary purpose and uses examples compactly. Some phrasing could be trimmed, but nothing is merely 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?

The description is complete for a tool of this complexity: it explains what the tool returns, the truncated/total_in_range/note mechanics, how distance_m is computed, radius clamping, valid empty results, and error responses. The output schema and annotations cover the structured contract, while the description fills the practical gaps an agent would need.

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

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

With 0% schema description coverage, the description carries the semantic burden. It thoroughly explains subtype and infra_class as case-insensitive substring matches against Overture columns, and meaningfully describes radius_m effective behavior. It does not explicitly explain lat/lon units or the limit parameter semantics beyond the default, though these are more self-evident.

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 clear, specific function: return infrastructure near a point, nearest first, with named categories (bridges, towers, piers, street furniture). It differentiates itself from siblings by specifying this is Overture type=infrastructure — built things that are neither buildings nor POIs, which separates it from tools like buildings_at.

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 strong guidance on when to use it and how to frame queries, including the crucial warning that unfiltered results are dominated by street furniture and the recommendation to filter by subtype/infra_class for landmark questions. It does not explicitly name alternative tools for when this tool should not be used, so it stops short of a full 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?

Goes far beyond the readOnly/idempotent annotations: discloses the Dijkstra-on-Overture graph algorithm, per-mode road-class exclusions, one-way handling, default speed models, the exact-stats vs approximate-polygon distinction with token-budget decimation, and radius caps that return errors instead of truncating. Error semantics for unsupported modes and bad requests are fully specified and consistent with the 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 long (~400 words) but nearly every sentence carries functional content, and the flow from purpose to origin to algorithm to output to errors is logical. Minor bloat: the parenthetical road-class enumeration rambles somewhat and 'but not both (and not neither)' is a clunky double negative.

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 origin specification rules, all mode behaviors, the time budget, optional radius/speed overrides, cap violations, and every error path, while the existing output schema handles return-value details. An agent has everything needed to invoke the tool correctly in one place.

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

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

With schema description coverage at only 14%, the description carries the full burden and succeeds: it explains the lat/lon–where mutual exclusion and 'resolved' side-effect, minutes > 0, per-mode radius_m caps (5/15/60 km) with structured errors, and speed_m_s overrides with mode defaults. Every one of the 7 parameters gains meaning that the schema does not provide.

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 precise definition — 'the area reachable from a point within minutes, by mode' — and grounds it with a concrete return shape ('polygon' + 'stats'). Though no sibling is named, the area-reachability scope is unmistakable next to distance/matrix/route siblings like within_distance and travel_time_matrix.

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 primary usage is implied by the definition ('reachable from a point within minutes') rather than stated as explicit when-to-use/when-not-to-use guidance, and no alternatives are named. It does give clear operational context for choosing origin form (lat/lon vs where, not both/neither), but tool-selection criteria against siblings 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?

Beyond the annotations, the description richly documents null semantics, patchy OSM coverage, overlapping-polygon resolution, the 'note' flag, and structured error cases for upstream failures and bad coordinates. This is exactly the behavioral context an agent needs that annotations cannot provide.

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

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

Although long, every sentence earns its place: purpose, output shape, null meaning, overlap behavior, and error semantics are all covered without redundancy. The most important scoping information appears early.

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

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

Given the tool's moderate complexity, the description covers the response shape, valid null cases, overlap selection logic, and failure modes. An agent has enough information to invoke it correctly and interpret results, especially with the output schema also present.

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 only exposes lat/lon as numbers with zero description coverage. The tool description adds minimal parameter-specific meaning beyond mentioning out-of-range coordinates as an error case; the parameter names are self-evident, but coordinate system and range details are not explicitly documented.

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 question-answer framing ('What kind of land is this') and explicitly identifies the resource as land use and land cover classification at a point. It also distinguishes itself from place-search and area-summary tools, making its purpose unmistakable.

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 states the tool is for querying land itself, not discrete POIs, and names the broad tool categories it is distinct from. However, it does not explicitly contrast with point-query siblings like infrastructure_at or buildings_at, so an agent could use more direct exclusion criteria.

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

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

The description goes far beyond the annotations, disclosing the seed-center method, routed-time computation, the 16-pair fan-out cap, cold-graph confirmation behavior, truncated leg handling, candidate dropping when routing fails, silent zero-match categories, and the optional map payload. These operational details are consistent with the readOnly/idempotent/non-destructive 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 long but every paragraph earns its place: purpose and fairness first, then method, parameter details, return format, map payload, and error behavior. The structure is scannable, front-loaded with the core concept, and 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?

For a complex tool with four parameters, a nuanced fairness algorithm, multiple input types, and several edge cases, the description is complete. It covers input validation, ranking details, return shape, error structures, caps, truncated results, and the map payload, leaving no critical gap for an agent deciding whether and how to call it.

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

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

Schema description coverage is 0%, so the description must carry the full load for parameters, and it does. It explains origins types and mixing rules, mode defaults and per-origin modes, limit default and maximum, category slug behavior, and confirm semantics with the cold-graph build wait. This is far more than the raw 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 states a specific purpose: compute fair meeting venues ranked by equalized travel time, not geometric distance. It also explains the fairness objective in detail, clearly distinguishing this tool from sibling geospatial tools that answer different questions such as distance matrices or area suggestions.

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 identifies the use case: several people need to meet somewhere fairly, and explicitly contrasts the max-travel-time objective with the 'minimize the average' approach. It does not name alternative sibling tools, but it gives thorough contextual guidance, including when to pass confirm=true and when to omit it, which is strong practical usage direction.

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

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

The description goes well beyond the read-only and idempotent annotations by disclosing that it does not call external APIs, returns structured errors for multiple failure cases, and degrades gracefully to straight-line times when street graphs are missing. This gives the agent a clear picture of side-effect-free behavior and fallbacks without needing to probe the tool.

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

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

The description is longer than a typical one-liner, but every sentence adds meaningful detail about behavior, defaults, or failure modes. It is front-loaded with the core purpose and then efficiently covers edge cases. The density 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?

The description covers invocation parameters, defaults, error conditions, degradation behavior, and the nature of the returned verdict. An output schema is present, so the exact return shape does not need to be enumerated here. For a tool with this many optional behaviors, the description is complete and self-sufficient.

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 only 17%, so the description carries the burden of explaining parameters. It explains the mode override mapping from context, default walk with 15 minutes, the meaning of radius_m/minutes as overrides, and how empty context behaves. The only remaining parameters are lat/lon, which are self-evident.

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's function: accepting a point plus life context and returning a ranked verdict with strengths, weak points, and a verification item. It distinguishes itself from siblings by explicitly saying it is 'not a data dump' and by focusing on life-decision output. The action and resource are specific enough for an agent to recognize its 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 implies when to use the tool through phrases like 'life-decision neighborhood verdict' and explains what happens with empty context, but it never explicitly names alternative tools or states when not to use it. The guidance on mode and radius overrides is useful for invocation but does not fully replace explicit sibling 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?

Annotations declare read-only, idempotent, and non-destructive behavior, and the description adds substantial behavioral context beyond that: exact Held-Karp optimization, structured errors, estimated straight-line legs on disconnected graphs, and the confirmation/one-time-build behavior. There is no contradiction with the 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 long but each paragraph covers a distinct, necessary concern: optimization semantics, `keep_order`, start/roundtrip behavior, estimation, confirmation, and errors. The key distinction from `route` is front-loaded, and the length 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?

Despite the sparse schema, the description is complete: it covers input constraints, parameter interactions, return structure, error categories, ambiguous stops, disconnected road data, and the confirmation flow. An agent has everything needed to invoke and interpret 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 only 17%, so the description carries the full burden for parameters. It explains each stop format (`{lat, lon, name}`, GERS id, free-text name, mixed), mode defaults, `roundtrip`, `keep_order`, `start_index`, and `confirm` in enough detail to use the tool 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 precise statement of what the tool does: 'Best order to visit several stops: multi-stop route ordering (a small TSP).' It also differentiates from the sibling `route` tool by explicitly saying a single pair's numbers should use `route` instead.

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: use `keep_order=true` when the order came from the user, omit it to get the cheapest order, and call `route` for a single pair. It also clearly states the `confirm` gate: pass it only after a `needs_confirm` reply and user agreement.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: truncation carries _omitted_count, errors have structured shapes, missing upstream data is surfaced, and lang variants are never invented or transliterated. This is rich, honest 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 front-loaded with a compact summary and each paragraph earns its place. The '#410' reference is minor noise, and the amount of detail is justified given the tool's optional-parameter complexity and resolution modes.

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

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

With an output schema present, return values don't need elaboration, and the description covers the remaining operational context: both resolution branches, required parameter pairing, truncation semantics, error responses, performance implications, and language handling. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is only 13%, so the description carries the full burden, and it succeeds. It explains id, name, lat/lon pairing, radius_m scope, near_lat/near_lon purpose and perf impact, and lang behavior far beyond the schema's bare 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 'One place, in full' and enumerates the exact payload fields, making the resource and scope unmistakable. It also specifies two distinct resolution modes, which separates it from other place-related sibling tools without needing to open their schemas.

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

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

It gives explicit usage rules: pass id, or pass name together with lat/lon, 'not both'; near_lat/near_lon are for id lookups and ignored for name lookups. It does not explicitly compare against sibling tools like resolve_place, but the resolution instructions are concrete and actionable enough to prevent incorrect calls.

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 annotations already declaring read-only, idempotent, and non-destructive hints, the description adds substantial behavioral context: results are ordered by along_m rather than detour cost, the detour_m metric is an approximation rather than a re-routed detour, results are evenly sampled when truncated, and a composed itinerary carries verify_before_going. This is far beyond the annotation baseline and meaningfully informs invocation and result interpretation.

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, covering purpose, filtering, output fields, ordering, truncation, route metadata, and error behavior. It is front-loaded with the core concept, then branches into increasingly specific details, making it dense yet 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 the tool's complexity, parameter count, and the availability of an output schema, the description covers all the non-obvious aspects an agent needs: result row structure, ordering semantics, sampling behavior, route metadata, composed-itinerary verification, mode resolution, and error cases. Nothing material is left to inference.

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

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

Schema description coverage is only 11%, but the description thoroughly compensates by explaining max_detour_m's default, cap, and error behavior; category and name semantics matching find_places; mode's default-to-stored-preferences behavior; and limit's effect on sampling/truncation. Even the coordinate parameters are implicitly clear from the 'from A to B' framing and the route 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 uses a specific verb phrase 'corridor search along the route' and explicitly answers an example query, making the tool's function immediately clear. It also distinguishes itself from sibling tools by describing itself as 'the route tool plus find_places in one call,' so an agent can tell it apart from both without opening schemas.

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

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

The description gives clear context for when to use the tool: when the need is 'places on the way from A to B,' and it names the constituent siblings (route and find_places) without being either one alone. It also provides practical guidance on when to pass filters ('worth passing on a long route') and how mode selection behaves, giving an agent actionable selection criteria.

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

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

Annotations already include idempotentHint=true and destructiveHint=true, but the description adds essential behavioral detail: clear=true deletes the file and cannot be combined with other fields, 'Nothing is sent off this machine,' and 'The same document is the placeroot://preferences resource.' It also explains that pace and household do not yet affect answers, and exactly how lang selection works with name-lookup tools. This goes beyond 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 compact and front-loaded: it opens with 'Travel defaults,' immediately states the core use case with an example, then covers edge behaviors (explicit args win, pace/household inert, lang semantics, clear, privacy). Each sentence earns its place and the structure flows from the most common use to edge cases.

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

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

With an output schema present, parameter count of 6, and only 33% schema coverage, the description still covers the essential call patterns: read, merge, clear, and how stored values affect other tools. It explains the persistence resource identity and privacy, which is rare and valuable context. There is no missing information an agent needs to correctly call this 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?

The input schema covers individual parameters with descriptions for lang and mode, and an enum for mode. The description itself explains the merge semantics: 'Pass mode, pace, household tags, a free-text note, or lang to merge those fields.' It also gives a concrete example of lang usage ('Munich' for 'München'). Since schema description coverage is only 33%, the description significantly compensates by explaining how parameters behave as a group, though it does not individually document note, pace, and household beyond listing them.

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 that this tool reads and merges persistent preferences, including travel mode, pace, household, note, and language. It distinguishes itself from routing and name-lookup tools by explaining how stored preferences interact with those tools. The phrase 'Travel defaults' and the explicit 'Call with no arguments to read. Pass mode, pace, household tags, a free-text note, or lang to merge those fields.' provide a specific verb and 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?

The description explicitly explains when to use this tool: to set travel defaults, household info, and stored language preferences. It distinguishes from routing tools by noting 'Routing tools use the stored mode when you omit theirs; an explicit argument always wins.' It also clarifies that pace and household are stored for later features and do not change answers yet, preventing misuse. The clear=true behavior and its exclusivity are 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?

Annotations provide no read-only, idempotence, or destructiveness hints, so the description carries the full burden — and it delivers. It discloses file writing to PLACEROOT_ARTIFACT_DIR, fallback summary composition, skipped-feature behavior rather than hard failure, inline response behavior, color validation/drop rules, and zero network requests. These are substantial behavioral details beyond the structured 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 long but every sentence carries necessary operational detail: artifact location, styling rules, edge cases, response fields, and optional parameters. It is front-loaded with the core purpose and then layers detail appropriately. No repetitive or filler content is present.

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, zero schema coverage, absent annotation hints, and an output schema, the description covers everything an agent needs: input structures, transformation rules, output fields, environment behavior, failure handling, and size caps. It is complete for safe and 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?

With 0% schema description coverage, the description must compensate for all parameters, and it does. The `result` structure, `summary` purpose, `inline` behavior, and the full `legend` mapping format with examples are all explained. Only `title` is not explicitly covered, but its meaning is self-evident from the parameter name and default. The description adds significant semantic value beyond the bare input 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: 'Render any result as a shareable one-pager: map, verdict, and stop list.' It then details the exact artifact produced (a self-contained HTML file with interactive SVG map), distinguishing this tool from the data-retrieval and geometry siblings. The purpose is unambiguous and complete.

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 clear context for when to use the tool: any time a shareable map/verdict one-pager is needed, including reachability payloads, shape roles, and point classes. It does not explicitly name alternatives or exclusions, but the 'any result' phrasing and detailed payload examples provide enough usage guidance. Missing explicit when-not-to-use information keeps it from 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?

Annotations already signal read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context beyond that: it merges geocode and find_places, ranks by match tier, returns empty results instead of errors for unresolvable queries, returns structured errors on remote failures, and explains lang behavior per row kind.

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 uses concrete examples and clear sections. Some references, such as internal issue numbers (#215, #373, #410) and 'Budgeted like every other tool', add marginal value for an agent and could be trimmed without losing essential guidance.

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

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

Despite low schema coverage and a complex 6-parameter surface, the description covers input strategy, ranking semantics, return shape, error behavior, language handling, and even the impact of PLACEROOT_HOME. An agent has enough information to call the tool correctly and interpret its output.

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 only 17%, so the description carries the burden for most parameters. It richly explains query via examples, city, near_lat/near_lon, and lang. However, limit is never described beyond its schema default, and query's exact format is only implied rather than stated formally.

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 line 'Free-text place reference -> ranked, typed GERS ids' states a specific transformation with a clear resource. It further distinguishes itself by naming geocode() and find_places as the merged sources, so an agent can tell it apart from 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 explicitly instructs callers to 'Split the location out of the query, and pass city' and explains when to prefer near_lat/near_lon instead. It also names the failure/retry path with need: 'location' and retry_with, leaving little ambiguity about when and how to invoke 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?

Annotations already mark readOnlyHint and idempotentHint true, but the description adds substantial behavioral context: the 25-item cap, order preservation, per-id error envelopes for unresolved ids, empty-list behavior, budgeted execution, and structured errors instead of exceptions on remote scan failure or missing dataset columns. This goes well beyond the annotations and fully discloses side-effect-free but potentially failure-prone behavior.

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

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

The description is front-loaded with the core purpose and then adds a dense but focused set of behavioral details. Every sentence contributes: batch collapse rationale, comparison to place_details, output shape, ordering, per-id error handling, cap behavior, empty-list behavior, budgeting, and error fallback. 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?

Given the output schema exists and annotations cover read-only/idempotent safety, the description fills every remaining gap an agent needs: max batch size, result ordering, exact compact row fields, error shapes for not-found and batch-level failures, empty-list behavior, and budget expectations. There is no missing context that would prevent 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 schema provides only 'gers_ids' as an array of strings with zero description, so the description must carry the semantic weight. It does: it explains what the ids are (GERS ids), the maximum count, how each is resolved, the output shape, ordering, and error behavior. This is far more than the schema alone offers.

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: 'Resolve up to 25 GERS ids to compact place rows in one call.' It clearly distinguishes itself from place_details by emphasizing compact rows versus the full payload, and from the singular resolve_place by the batch dimension. The purpose is immediately clear even to an agent unfamiliar with the tool.

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

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

Explicitly explains when to use this tool: to replace N place_details round-trips, and explicitly says 'Use place_details for full detail on a single id.' This gives an agent a clear decision rule and a named alternative. The behavior for empty lists and oversized batches further clarifies expected usage 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?

The description goes well beyond the readOnlyHint annotation by explaining the degraded divisions-only path, the source identifier 'divisions_only', the reason addresses may be missing, and the structured error return instead of an exception. This is rich, honest 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?

Two tightly packed sentences convey the core operation, the degraded mode, the cause, and the error behavior. No filler or redundancy; the most important output semantics are front-loaded.

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

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

The tool is simple in inputs, has an output schema to cover result shape, and annotations to cover safety. The description adds exactly the missing context: the expected degraded path and error handling. Nothing critical is left unexplained.

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

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

With 0% schema description coverage, the description was responsible for explaining lat/lon semantics, but it only refers to a 'Point' generically. It does not state coordinate format, bounds, or how the point maps to the parameters, leaving the agent with only the property names 'lat' and 'lon'.

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

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

The description clearly states a specific operation: converting a geographic point into the nearest address and its containing division chain. It distinguishes this from forward geocoding and batch reverse geocoding through the 'Point -> ...' framing and the tool name/title.

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 implied: it handles a single point and returns address plus divisions. However, it never explicitly says when to prefer this over reverse_geocode_batch, geocode, or address_at, and it names no alternatives or exclusion 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?

Annotations already indicate readOnly, idempotent, non-destructive behavior, and the description adds substantial behavioral detail beyond that: the 20-point limit, whole-batch rejection on overflow, per-point ordering, degrade behavior, and per-slot error envelopes for malformed points. This is exactly the kind of context an agent needs.

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

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

The description is front-loaded with the core purpose and then moves through behavior in a logical order: limit, success shape, and error handling. Every sentence adds necessary operational detail without redundancy 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 batch tool with one parameter, no schema descriptions, and a rich behavioral surface, the description covers the critical execution semantics: limits, ordering, degraded mode, and partial failure behavior. It is complete enough for an agent to invoke the tool correctly without needing additional documentation.

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 0%, so the description carries the full burden. It explains that `points` is a list of points with lat/lon, imposes a batch size limit, defines what counts as malformed, and describes how each point is processed and returned. This compensates fully for the schema's lack of detail.

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: 'Reverse-geocode many points in one call.' It clearly distinguishes this batch tool from the single-point reverse_geocode sibling by emphasizing the batching behavior and round-trip reduction.

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 frames the tool for 'many points' and says its purpose is to cut N round-trips down to one, giving a clear when-to-use signal. It also references reverse_geocode as the per-point behavior source, which implicitly identifies the alternative for single-point use.

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

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

Annotations already mark the tool read-only and idempotent, and the description layers on substantial real behavior: endpoints snap to the nearest graph node, drive duration has no live traffic, distance caps trigger route_too_long, and graph failures return no_route/no_graph_nearby rather than raising. It also discloses fallback behavior for prefer='flat' and the deliberate absence of toll/ferry options. No contradiction with 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 long, but it is front-loaded with a one-sentence definition and organized by parameter and edge case. A few explanatory asides, such as the extended rationale for the straight-line cap and the repeated confirm warning, could be trimmed without losing meaning.

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 all 12 parameters, every documented error state, output fields, mode-specific caps, optional flags, and failure fallbacks. An output schema is marked as present, so the agent is not left without return-structure information; the description is complete for a complex 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 description coverage is only 25%, so the description carries nearly the entire burden. It fully compensates: it explains the two mutually exclusive endpoint formats, the accepted from/to value types, the avoid vocabulary, the prefer='flat' semantics and accessibility caveat, and the include_path/include_elevation tradeoffs.

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 an exact verb and resource: 'shortest-path distance and duration between two points, by mode.' It also distinguishes the tool from its sibling by noting 'from_to is this same routing with a walk default,' so an agent can tell which route-like tool is which.

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-not guidance: 'Do not call geocode(), resolve_place(), or geocode_batch() first: names and ids resolve in parallel inside this call.' It also explains exactly when confirm is needed, when include_path should be used, and when avoid is a no-op, which gives the agent clear decision criteria.

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?

Beyond the readOnly/idempotent annotations, the description discloses the ranking priority (exact slug match > slug prefix > slug substring > path segment), synonym-lexicon fallback, output shape (`{"results": [{"slug", "path", "confidence"}, ...]}`), confidence ordering, empty-query behavior, and limit clamping to 0-50. There is no contradiction with the 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?

Every sentence contributes a distinct operational fact: purpose, data-source snapshot, ranking order, fallback, output format, empty-query behavior, and limit semantics. The description is detailed but tightly organized and front-loaded with the main purpose before diving into specifics.

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

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

The description covers input semantics, output format, edge cases (empty/whitespace query, out-of-range limit), and behavioral guarantees (confidence descending, budgeted like other tools). Even with an output schema present, the description adds the semantic context needed for correct invocation, and 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?

The input schema provides no property descriptions (0% coverage), so the description carries the full burden. It explains that `query` is free text mapped to category slugs with a defined ranking and fallback, and that `limit` is clamped to 0-50 with out-of-range values not treated as errors. The schema only supplies type and default, so the description adds essential meaning.

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 'Free text -> valid Overture category slugs, for the `category` param the place-search and area-summary tools take,' which states a specific conversion purpose and names the consumer tools. It further distinguishes itself by declaring 'Lookup only — no geo filtering, no upstream dataset dependency,' separating it from sibling geo/search tools.

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

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

It explicitly indicates when to use the tool: to produce the `category` parameter for place-search and area-summary tools. It also gives exclusion cues ('no geo filtering, no upstream dataset dependency') and describes fallback behavior, so an agent can decide between this and sibling tools without additional 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: binary search on tolerance, point geometries passing through unchanged, and a structured error response for invalid geometry. This goes well beyond the 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 front-loaded with the main purpose, then efficiently covers algorithm, input types, output shape, and error behavior. Every sentence earns its place; there is no filler or repetition.

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

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

Given the output schema exists and annotations cover safety, the description is complete enough. It specifies valid input geometry types, pass-through behavior, the meaning of max_tokens, and error handling. Nothing critical is missing 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 coverage is 0%, so the description must carry parameter semantics. It explains max_tokens as the token budget and describes the binary-search behavior. It also clarifies which GeoJSON types are accepted. It could add more detail about geojson structure, but it compensates for the sparse schema well.

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: simplify a GeoJSON geometry to fit a token budget. It also states exactly which geometry types are handled and which pass through, clearly distinguishing this from sibling tools like geometry_op and render_map.

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

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

The description gives clear context for when to use this tool: when a caller-supplied GeoJSON geometry needs to be simplified to fit a token budget. It does not explicitly name alternatives or say when not to use it, but the scope is specific enough that an agent can infer its niche.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. The description goes well beyond this by disclosing the street-graph build cost, the confirm flow, per-anchor graph checks before building, intersection behavior for multiple anchors, how unroutable legs return 'note' instead of failing, and the honesty field for unmeasurable requirements. It also clearly states it never returns partial shortlists on errors.

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

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

The description is long but exceptionally well organized into purpose, parameter semantics, method, return structure, edge cases, and error behavior. Each sentence adds necessary operational detail for a complex tool, with the core one-line purpose front-loaded so an agent can quickly route the call.

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 0% schema description coverage and complex interaction between anchors, requirements, graph building, and scoring, the description covers everything an agent needs: defaults, output fields, ranking order, capping, empty-result behavior, per-leg routing failures, confirmation timing, and propagated errors. The presence of an output schema does not reduce the need for this behavior-level context, and the description provides it fully.

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

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

Schema coverage is 0%, so the description carries the full burden for parameter meaning, and it succeeds. It specifies anchors as 1-3 objects with lat/lon plus optional mode and minutes, defaults for mode and minutes, requirements as 1-8 free-text strings, limit as 1-10 defaulting to 5, and confirm semantics. It even covers validation error conditions for each parameter.

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 'Where within reach: neighborhoods ranked by travel budget + amenities', naming a specific verb, resource, and output. It also explicitly contrasts itself: 'The inverse of every other area tool — instead of "describe this place", "find me a place"', which clearly distinguishes it from 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 tells the agent when to use this tool versus general area tools and frames it as the opposite of describing an existing place. It also gives concrete call-level guidance, such as 'Omit confirm unless you just asked and they said yes', and explains when an empty result is still valid, so the agent can avoid false error handling.

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?

Adds substantial behavior beyond the annotations: invalid calls return a structured {'error': 'bad_request'} naming the problematic choice, a 'resolved' object appears conditionally, and upstream failures return errors instead of raising exceptions. These are non-obvious runtime behaviors that an agent cannot infer from readOnlyHint or idempotentHint.

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 tightly structured into purpose, input contract, and error behavior. Every sentence earns its place, and line breaks make the key constraints easy to scan.

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

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

Given the output schema exists, the description covers the essential call contract, input constraints, and error behavior. The only clear gap is the undocumented radius_m parameter, which prevents full completeness for an agent needing to set a custom radius.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully explains lat/lon versus where formats, the exclusivity constraint, and the 'resolved' object behavior. However, radius_m is never described, leaving its units and meaning ambiguous, so the compensation is incomplete.

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: 'Summarize what's in an area: total places and top categories.' This clearly defines the tool's output and differentiates it from sibling tools like summarize_buildings, compare_areas, and land_use_at.

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 no guidance on when to choose this tool over its many siblings, such as whether to prefer summarize_area over summarize_buildings or compare_areas. The description only explains the lat/lon vs. where calling constraint, which is parameter-level guidance rather than tool-selection 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?

The description goes beyond the read-only/idempotent annotations by explaining data sparsity behavior: it reports height_known_pct/num_floors_known_pct as coverage rather than assuming complete data, and includes mean values only when any are known. It also discloses error behavior (structured {"error": ...}) for upstream unavailability or missing geometry/bbox.

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 opens with a one-sentence summary of purpose and metrics, then adds necessary detail about data provenance, coverage semantics, and error handling. Every sentence contributes new information and is clearly structured without 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?

For a read-only summary tool with an output schema, the description covers data provenance, output metrics, sparse-data handling, and error responses. It does not explain input parameters or contrast with sibling tools, leaving some context incomplete, but the essential operational details are present.

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 has zero descriptions for lat, lon, and radius_m, and the description does not compensate by defining these parameters or their units. It only says 'in an area', which implies a spatial scope but does not specify the role of each parameter or the meaning of radius_m.

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 ('Summarize'), a specific resource ('building footprints in an area'), and the exact metrics returned (count, footprint area, height/floor coverage, mix). It clearly distinguishes this from sibling tools like `buildings_at` (likely raw building access) and `summarize_area` (broader area summaries) by narrowing to building footprints.

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 through the word 'Summarize' and building-specific focus, but it does not explicitly state when to choose this tool over siblings like `buildings_at` or `summarize_area`. No exclusions or alternatives are mentioned, so usage guidance is only implied, not 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?

Annotations already mark this as read-only and idempotent, and the description adds substantial behavioral context: cached graph reuse, fallback to per-pair route() calls, unroutable pairs returning nulls, truncation caveats, no_graph_nearby failure, and error shapes. This far exceeds what annotations alone provide.

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

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

The description is long but dense and well-organized, with the core purpose and key constraint front-loaded. Each paragraph covers a distinct topic — input format, resolution behavior, graph caching, output/error shape — with no filler or redundant restatement of schema fields.

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 limits, edge cases, output structure, performance characteristics, and failure modes, including unusual cases like all-unroutable matrices and truncated street graphs. Nothing needed for correct selection or invocation appears to be 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 only 33%, but the description compensates fully: it explains LocationRefs forms (dict, GERS id, or free-text name), the 5-per-list cap, the mode enum with omitted-mode default, and how unresolved id/name entries behave. This adds meaning far beyond the sparse input 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 'Routed travel time + distance between every origin and destination, by mode', giving a specific verb, resource, and scope. It then distinguishes itself from distance_matrix's plain haversine and aligns with route()'s cost model, making sibling differentiation 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 contrasts with distance_matrix ('Unlike distance_matrix's plain haversine, this is a real shortest-path search') and clarifies the mode behavior ('one mode per call; omit mode to use the stored preferences mode, else walk'). It does not fully spell out when to choose route() or distance_matrix instead, but the context strongly implies the boundaries.

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

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

The description goes far beyond the annotations by detailing exact verdict thresholds (x1.15, x1.5), the semantics of 'unverifiable' vs 'false', how absence is treated, routing failure caveats, size-cap truncation effects, and structured error cases. This gives an agent a precise model of tool behavior that annotations alone could not provide.

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

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

Although long, the description is densely informative and well-structured with bullets, bolded claim kinds, and clearly separated error/output sections. Every sentence adds a necessary behavioral or semantic constraint; there is no filler or repetition of schema/annotation data.

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 three required parameters, no schema-level parameter descriptions, and many edge cases. The description covers input shape, claim constraints, matching semantics, verdict rules, output format, and all error classes. Given the complexity and the minimal schema, nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 0% and the claims parameter is just a generic object array, so the description carries the full burden—and it delivers. It thoroughly documents the three claim kinds, all allowed fields, defaults, caps, matching rules, and required field combinations, adding enormous meaning beyond the bare 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: 'Grade spatial listing claims ... against real routing and places data.' It clearly distinguishes this tool from sibling analysis tools by specifying its exact job—verifying structured spatial claims—and even states that free-text parsing belongs to a separate prompt/process, not this tool.

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

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

The description explicitly says the tool consumes already-decomposed structured checks, not free text, and points to the verify_listing_claims prompt for the decomposition step. It also gives practical usage constraints such as max 8 claims and max 5 travel_time claims due to routing cost. It stops short of naming an alternative sibling tool, but the usage 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?

Even though annotations declare readOnly, idempotent, and non-destructive, the description goes well beyond them: it discloses the cache side effect, the slow first-call behavior, expected wait time, radius cap, and the confirm flow. No contradiction with annotations exists because the cache write is internal and idempotent.

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 and front-loaded: purpose first, then scope, then operational constraints. There is slight redundancy in the confirm instructions ('Omit confirm unless...' repeats the prior condition), but every other 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 description is comprehensive about cache behavior, routing limitations, and confirmation protocol. However, it omits the location parameter contract (city vs lat/lon, requiredness, precedence), which is a meaningful gap for a 5-parameter tool with no schema descriptions. The output schema mitigates the need to document return values.

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

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

With 0% schema description coverage, the description explains radius_m (default 8000, cap 25 km) and confirm (only after user agrees) well. However, it never explains lat/lon/city semantics, whether one is required, or how they interact, leaving key location inputs to inference from their names.

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

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

Description opens with 'Pre-cache a city' and precisely states what is copied into cache (places and transportation tiles) and what is not (routing graph, buildings). This makes the tool's purpose unambiguous and clearly distinguishes it from query tools like find_places or 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?

Provides concrete usage context: call it before place searches so later queries read locally, and note that it will not speed up routing or building queries. It also says an already-cached city never needs another call. It does not explicitly name sibling tools as alternatives, but the guidance 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?

Annotations already mark this as read-only and idempotent, but the description adds substantial behavior beyond them: distance is to the closest point rather than centroid, no raw geometry is returned, ocean tiles cause phantom land overlap, radius is clamped, and error response shapes are detailed. It also explains the dense-water scenario and in_range_count purpose. No annotation contradiction exists.

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

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

The description is front-loaded with the core purpose and each subsequent paragraph adds important caveats (distance semantics, ocean artifacts, empty-result validity, error behavior). It is dense and somewhat monolithic, and could be improved with bullet points or section breaks, but no sentence is pure 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 filtering/query tool, the description is nearly exhaustive: it covers output shape, distance semantics, water classes, ocean edge cases, truncation, clamping, error handling, and data-coverage caveats. The presence of an output schema reduces the need to enumerate return fields, and the description still adds the semantic details needed to interpret them 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?

With 0% schema description coverage, the description compensates well for most parameters: radius_m (clamping, effective radius), subtype (case-insensitive substring, examples, ocean restriction), water_class (maps to class), and coordinates (bad_request error). It does not explicitly explain the 'limit' parameter as the maximum result count, only implying it through 'truncated': true and the results array.

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, 'Water near a point, nearest first,' names a specific resource (water bodies) and behavior (distance-ordered), and the phrase 'waterfront check, distance to river/canal/lake' scopes it. It is clearly distinguishable from sibling tools by focusing exclusively on water features and explicitly disclaiming raw geometry.

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 use context: waterfront checks, distance queries to specific water subtypes, and how to filter with subtype/water_class. It also states a when-not ('subtype="ocean" cannot return distance rows') and notes that empty results are a valid answer. However, it never names alternative sibling tools, so an agent must infer which other tool to choose when water info is not the goal.

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

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

The description explicitly documents the error contract: bad_request for ambiguous center choices and for invalid max_distance_m, plus upstream/dataset failure errors. The detailed note about not silently returning a confident-looking 'false' for a zero or missing distance is especially valuable, and the conditional 'resolved' behavior is disclosed.

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

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

The description is organized into clear blocks: center choice, distance validation, and return value/errors. Every sentence adds operational value; the zero-distance parenthetical is slightly long but earns its place by preventing a subtle misuse.

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 six-parameter tool with no schema-level descriptions, this covers input alternatives, validation, return shape, and error outcomes exceptionally well. The output schema supplies remaining return details, but a bit more clarity on category/name matching semantics would make it fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does well by explaining max_distance_m requirements, the three `where` forms, the exclusivity of lat/lon vs `where`, and the conditional `resolved` field. Minor gaps remain: it does not fully define how category/name matching behaves or explicitly require lat and lon as a pair.

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 question defines a precise boolean check: whether the nearest place matching category/name is within max_distance_m of a center. It distinguishes this from sibling list/detail tools by its predicate and matching criteria, though it never explicitly names a sibling.

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

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

The description clearly frames the tool as a proximity test and fully specifies acceptable center inputs, so an agent can infer when it applies. It does not mention alternative tools or provide explicit when-not-to-use guidance, which keeps it from a 5.

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