Mapsource OpenStreetMap & Geospatial APIs

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the catalog itself is public while tile requests require a subscription key, which is an auth/access behavior an agent cannot infer from the annotations or empty schema.

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

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

Two sentences, zero waste, and the enumeration of return contents is front-loaded ahead of the access caveat. Nothing could be cut without losing information.

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

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

With no params and no output schema, the description carries the burden of conveying what comes back, which it does by listing the catalog's fields. It could add a note on catalog stability, scope, or pagination, but for a zero-parameter read tool it is largely 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?

The tool takes zero parameters, so the baseline is 4. Nothing in the schema needs compensating for, and the description correctly offers no parameter discussion.

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 pairs the verb 'List' with a specific resource and enumerates the catalog's contents (raster/vector tile templates, zoom ranges, dataset snapshots, attribution), making the purpose unambiguous. It does not explicitly contrast itself with siblings like geo_style or geo_render, so it stops short of a 5.

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

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

The line 'The catalog is public; tile requests require a subscription key' gives a useful access condition, but it is an auth note rather than when-to-use-this-vs-alternatives guidance. No sibling tool is named and no exclusion condition is stated, so usage is only weakly implied.

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

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

Annotations already cover the read-only/non-destructive profile, so credit goes to the added context: it discloses a subscription-key auth requirement, an accuracy caveat ("not survey-grade"), and semantics for returned fields (clamped vs raw elevation, bathymetry source). These are meaningful behavioral traits not present in the annotations or schema.

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

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

The purpose is front-loaded, followed by output-field semantics and then caveats. It is dense but each sentence carries information; the field-list sentence is slightly terse and would read better as structured output documentation, but nothing is wasted.

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

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

With no output schema, the description appropriately explains the return fields, auth requirement, and accuracy limitation, which is nearly complete for a simple 2-parameter sampler. Only the lack of usage context keeps it from being 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 100%, with both lat and lon fully documented including bounds, so the schema carries this dimension. The description references lat/lon only in passing and adds no format or usage detail beyond the schema. Baseline 3 is appropriate.

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

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

"Sample terrain at lat/lon" gives a specific verb (sample) and resource (terrain) with the required inputs, which is easy to distinguish from sibling tools like route, isochrone, or geo_analyze. However, it never explicitly contrasts itself against any sibling, so an agent must infer the boundary.

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

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

The description states what the tool does but gives no guidance on when to use it versus alternatives, and no exclusions or prerequisites beyond the auth note. The agent gets no routing help.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the 0.5-degree-per-axis bbox cap, that results are OSM geometry and tags, that output is subject to a limit, and that a subscription key or x402 payment is required. It omits rate limits and explicit read-only framing, but auth and constraint disclosure are solid.

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

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

Three sentences, front-loaded with the resource categories and scope, then return content, then prerequisites. The long category enumeration is slightly list-heavy but every sentence carries information.

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

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

With no output schema and no annotations, the description covers return content, scope limits, and auth requirements. It is close to complete for a read-style search tool; missing only finer points like failure behavior and rate limits.

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 43%; south/west/north/east are undocumented (though self-evident), while category, limit, and responseMode are described in the schema. The description adds genuinely useful meaning beyond the schema by stating the real 0.5-degree bbox cap, which is stricter than the schema's ±180/±85 bounds.

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 ('Find') and enumerates the exact resource categories, plus the geographic scope (bounding box). An agent can tell this is a bounded POI/feature search. It does not explicitly differentiate itself from siblings like geo_search or geo_data, though the schema's category note points to overpass_query.

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

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

Implies usage via the category list and the bbox constraint, and states the auth prerequisite, but never says when to choose this over alternatives. The only alternative-routing hint ('use overpass_query for arbitrary OSM tags') lives in the schema, not the description.

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 and destructiveHint=false, and the description is consistent with that (compute/transform, no persistence claims). Beyond the annotations it adds real context: the subscription-key auth requirement, the 12-step pipeline cap, the estimateOnly cost-estimation mode, and the constraint that overlay ops need polygon areas. It does not disclose rate limits or what a successful response contains.

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

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

Dense but front-loaded: the operation enumeration and accepted input forms lead, followed by the pipeline/estimateOnly note and the auth prerequisite. Nearly every clause carries information, though the long operation list partially duplicates the enum in the schema.

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

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

For a complex 8-parameter tool with a nested pipeline and no output schema, the description covers inputs, the pipeline cap, and auth but says nothing about what comes back (result handles, geometry payloads, units of numeric results) or failure behavior. The mention of 'result handle such as rh_...' in the schema hints outputs are handles, but the description never closes that loop.

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 88%, so the schema already documents a, b, distance, units, pipeline, returns, and estimateOnly, including which operations take b vs. distance. The description mostly restates this (operation list, input forms, 'polygon overlay operations require areas'), adding only marginal meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb pair ('measure or transform') plus the resource ('geometry') and enumerates all 15 operations, so an agent can tell this is a geometry-computation tool rather than a search or routing tool. It never names a sibling to route away from, so differentiation from geo_search/find_features/route is only implicit.

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

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

Gives conditional guidance for the pipeline path ('Use operation pipeline for up to 12 ordered steps and estimateOnly for cost estimation') and a prerequisite ('Polygon overlay operations require areas', 'Requires a subscription key'). It does not say when to prefer this tool over siblings such as geo_search, find_features, or route for spatial questions, so usage is only partially implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial context beyond that: status reports subsystem availability and replication lag, elevation returns surface and raw model heights, metrics report rates/latencies/dataset ages, and the public-vs-subscription-key auth requirement is disclosed. This is genuinely useful behavioral detail not available in the structured fields.

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

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

Four sentences, front-loaded with the operation list followed by per-operation output detail and the auth constraint. Each sentence carries information, though the output-detail sentence could be trimmed and the structure does not group constraints as cleanly as it could.

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 no output schema, the description does describe what several operations return (subsystem availability, replication lag, surface/raw model heights, request rates, latency percentiles, dataset ages) and covers the auth requirement, which is enough for a dispatcher tool. The notable gap is sibling differentiation against basemap_catalog/elevation/service_status, plus no disclosure of defaulting behavior for zoom/bands/window (left to the schema).

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

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

Schema description coverage is 100%, and every parameter (lat, lon, zoom, bands, window, operation) is already documented with type bounds and per-operation applicability in the schema. The description reinforces operation-level semantics but adds no new parameter detail, so the baseline 3 for high coverage is appropriate.

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

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

The description uses a concrete verb (Read) and enumerates the six resources it covers (service status, basemap catalog, point elevation, contours, usage, metrics), giving a clear picture of the tool's scope. However, it draws no distinction from siblings like basemap_catalog, elevation, and service_status, which appear to overlap heavily with the 'basemaps', 'elevation', and 'status' operations, leaving the agent unable to tell which tool owns that functionality.

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 explicit when-to-use guidance, no statement of when a sibling should be preferred, and no conditions selecting among the six operations beyond the auth note. The auth sentence ('Status and basemaps are public; other operations require a subscription key') is a prerequisite but not 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 establish the safe read-only profile (readOnlyHint=true, destructiveHint=false). The description adds meaningful context beyond that: it discloses the subscription-key auth requirement, describes what results contain (geometry or travel costs plus source metadata), and states that unroutable requests fail with an error requiring revised inputs. This is useful operational disclosure the annotations do not carry.

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

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

Front-loaded with the operation list, then capacity limits, then auth and error behavior in three compact sentences. Every clause carries information and nothing is padded, though the dense run-on listing without formatting slightly reduces scannability.

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-operation tool with no output schema, the description covers operation inventory, per-operation size limits, auth, error handling, and a summary of return content. The main remaining gap is the unresolved overlap with the sibling `route` and `isochrone` tools, which an agent must be told how to disambiguate.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds constraints absent from the schema: the 2-10 route waypoint range, the 3-20 optimize stop range, the 625-pair matrix cap, and the 1,000-point map_match trace limit. It also clarifies that elevation is optional for route, tying the boolean parameter to a concrete 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 description opens with a specific resource and enumerates all six operations (route, matrix, isochrone, map_match, snap, optimize), so an agent knows exactly what capability is behind the name. However, it never differentiates from the sibling tools `route`, `isochrone`, and `elevation`, whose names overlap directly with operations and parameters this tool exposes, leaving genuine ambiguity about which tool to pick.

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?

Per-operation constraints (2-10 waypoints, 625 pairs, 1,000 trace points, 3-20 stops) implicitly guide which operation suits a given workload, and the schema supplies per-operation parameter notes. But there is no explicit when-to-use-this-vs-`route`/`isochrone` guidance and no stated exclusions, so selection against siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: the style-dependent rendering mode (dark/light = raster, any other name = vector) and the subscription-key auth requirement, both of which an agent needs to call it successfully.

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

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

Four tight sentences, front-loaded with the core purpose before capabilities, rendering behavior, and the auth requirement. No filler; each sentence carries a distinct fact.

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 no output schema and 12 parameters at 50% coverage, the description covers purpose, capabilities, render modes, and auth well. Minor gaps remain on default dimensions and how overlays interact with the center/bbox inputs, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 50%, and much of what the description says about parameters (GeoJSON, result handles, up to 50 markers, style modes) is already present in the schema. It adds little syntax or format detail for the undocumented parameters (width, height, lat/lon, zoom), so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Render a static PNG map') plus the two input modes (center/zoom or bounding box), so the agent knows exactly what it produces. It is clearly distinct from siblings like geo_analyze or route, but it never names or contrasts an alternative explicitly, keeping it short of a 5.

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

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

Usage is implied rather than stated: the description explains the raster-vs-vector rendering rule and the subscription-key prerequisite, which helps an agent know when the tool behaves differently. However, there is no explicit when-to-use vs when-to-pick-another-sibling guidance, so it lands at minimum-viable.

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 readOnlyHint=true and destructiveHint=false annotations, the description adds useful behavioral detail: lookup has a 'soft map-focus bias, strict house numbers, source IDs and ambiguity reporting', discover can rank 'by travel time', and a subscription key is required. These are non-obvious traits an agent would not infer from the annotations alone. It does not cover pagination or rate limits, but with the annotation safety profile already stated, this is sufficient.

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

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

The description is compact, front-loaded with the primary purpose, and each sentence earns its place. It groups lookup vs discover first, then enumerates the remaining operations and ends with the auth requirement. There is no fluff or repetition of schema 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?

Given the tool's complexity (21 parameters, 10 operations), the description covers the main operational split and the non-obvious auth requirement. The schema provides detailed parameter descriptions for the rest. It does not mention return format, but there is no output schema and the read-only nature is captured; the description is complete enough for an agent to select and correctly invoke the tool for common cases.

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

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

The input schema already covers 81% of parameters with descriptions, so the baseline is 3. The description enriches operation-level semantics (e.g., what lookup and discover use) and mentions behaviors like 'soft map-focus bias', but it does not add direct parameter-level meaning beyond the schema. The schema itself carries most of the parameter burden.

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 verb and resource ('Search places and retrieve geographic entities') and then sharply distinguishes the two main modes, lookup and discover, with concrete examples. It also lists the remaining operations, making the tool's overall scope obvious to an agent choosing between geo_search and its geo-* siblings.

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

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

The description explicitly says 'Use lookup for local address...' and 'Use discover for POIs...', giving clear context for the two primary operations. It also names all other operations and warns about the subscription key requirement. It does not provide when-not guidance or alternatives for the remaining operations, so it stops just short of full routing guidance.

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

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

Beyond the annotations, the description discloses the auth scope ('Authenticated operations affect the current key's profiles'), that preview does not persist, that delete removes a profile, and the accepted input format versus raw MapLibre JSON. Note the tension with destructiveHint=false, which sits awkwardly next to a delete operation, though the description itself is explicit rather than misleading.

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

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

Purpose is front-loaded in the first sentence, followed by operations, an input constraint, and an auth caveat — a logical order with no filler. It loses a point because the operation list largely restates the schema's enum descriptions verbatim, which is redundant for an agent that can read the schema.

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

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

For an 11-parameter, multi-mode tool with nested patch objects and no output schema, the description covers the operational model, the auth scoping, and the payload format expectation. It stops short of describing return payloads for the read-style operations (explain, schema, list, diff), which an agent would have to infer.

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

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

Schema description coverage is 100% across 11 parameters, so the schema already carries per-parameter meaning and the operation-to-parameter mapping. The description reinforces the input-format expectation for the patch/manifest payload but adds no new syntax or per-parameter semantics, so baseline 3 applies.

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

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

The opening sentence gives a specific verb and resource ('Configure semantic basemap styles'), and the operation enumeration (explain, schema, intent, preview, save, list, revisions, diff, delete) makes the tool's scope unmistakable against catalogue/render siblings. However, it never names or contrasts a sibling tool, so differentiation is implied by scope rather than stated.

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?

Each operation is annotated with its purpose (e.g., 'preview: compile without saving', 'intent: generate a style proposal'), which tells the agent which mode fits a given goal. It also gives a concrete input constraint ('Submit semantic manifests or preset patches, not raw MapLibre JSON'), but provides no explicit when-not-to-use guidance or routing to alternatives like basemap_catalog.

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 read-only, non-destructive profile, and the description adds genuinely useful behavioral context beyond them: an auth requirement (subscription key) and the return format (GeoJSON). It omits rate limits or precision caveats, so it falls short of 5.

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

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

Three short sentences, front-loaded with the core purpose and progressing to output format and prerequisite. 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?

With no output schema, the description helpfully discloses the GeoJSON return type, covers the auth precondition, and the fully-described parameters leave little else needed. Minor gaps such as error behavior or band-ordering semantics keep it from 5.

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

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

Schema coverage is 100%, so lat, lon, costing, and contours are already fully documented in the schema. The description only restates the coordinate input and the four-band limit, adding no syntax or default details beyond the structured fields.

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

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

States a specific verb-and-resource ('Calculate reachable-area polygons from a coordinate') plus the scope limit ('up to four travel-time bands'), which lets an agent distinguish it from the sibling route tool that returns paths rather than polygons.

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

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

Gives clear use contexts ('catchment, coverage, and accessibility analysis') and a prerequisite ('Requires a subscription key'), but names no alternative tool or when-not-to-use condition.

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

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

With no annotations, the description carries the full burden and does disclose key traits: the query must be bounded, historical attic queries are rejected, auth is required (subscription key or x402 payment), and the dataset timestamp lives behind service_status. It omits rate limits, error semantics, and cost/credit implications of large queries.

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

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

Front-loads the capability, then tacks on the exclusions, auth requirement, and cross-reference in three tight sentences with no filler. It is appropriately sized for a two-parameter tool, though slightly clipped at the end.

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

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

For a tool with no output schema and no annotations, it covers the essential call-time facts (bounded input, auth, unsupported query class, where to get dataset recency). It leaves the shape/size of the returned results only partially implied by the responseMode enum in the schema.

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

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

Schema description coverage is 100%, so the schema already documents 'query' (bounded QL with explicit timeout and output limit) and 'responseMode' (compact/handle/raw). The description adds no syntax, format, or default details beyond that, so it meets the baseline but adds no marginal 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?

States a specific verb (Execute) and resource (bounded Overpass QL over OSM nodes/ways/relations/tags/geometry/areas), which makes the tool's nature clear. It doesn't explicitly contrast itself with nearby siblings like find_features or geo_search, so the agent must infer when raw QL is preferable.

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 constraints: historical attic queries are unsupported, and a subscription key or authorized x402 payment is required. It also routes the agent to service_status for the dataset timestamp, but never states when to prefer this tool over find_features/geo_search for the same task.

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 this as a safe read (readOnlyHint=true, destructiveHint=false), and the description adds meaningful context beyond that: the subscription-key auth requirement, the returned payload fields (GeoJSON, distance, duration, maneuvers), and the side effect of elevation=true producing gain/loss. Rate limits and error behavior are not covered.

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

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

Four short sentences, front-loaded with the core action and waypoint bounds, then options and the auth caveat. Efficient, though the enumerated costing list partially duplicates the schema enum.

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 no output schema, the description carries the return-value burden and does so (GeoJSON, distance, duration, maneuvers, elevation profile). The auth requirement is disclosed. Only minor gaps remain, such as behavior on invalid/duplicate waypoints.

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

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

Schema description coverage is 100%, so the schema already documents costing, elevation, and the ordered 2–10 waypoint array. The description largely restates these (mode list, elevation gain/loss, waypoint count) without adding syntax or format details, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Calculate a turn-by-turn route between 2–10 waypoints'), so an agent knows exactly what it produces. It does not name or distinguish itself from siblings like isochrone or geo_navigate, which also deal with routing/reachability, leaving some ambiguity in a crowded namespace.

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 when-to-use / when-not-to-use guidance and no alternatives are named. The agent is told what modes are supported and that a subscription key is required, but it must infer the conditions under which this tool beats isochrone or geo_navigate.

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

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

With no annotations, the description carries the burden but does disclose that the tool is 'Public', implying no authentication is required, and 'Read' implies a non-mutating operation. It does not state side effects, rate limits, or failure behavior, though for a zero-parameter status probe the risk surface is small.

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

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

Three short sentences, front-loaded with the core capability and followed by access level and the sibling alternative. No filler or redundancy.

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

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

There is no output schema, so the description usefully enumerates the return fields (readiness, dataset timestamp, billing state, payment mode), which is the key omitted structured data. A zero-parameter read tool with this field list is adequately covered, though response shape beyond the field names remains unspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The listed fields add context about scope but no parameter meaning is needed.

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

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

States a specific verb (Read) and enumerates the exact resources returned: Overpass engine readiness, dataset timestamp, billing state, and x402 payment mode. This is precise enough to distinguish it from the broad geo_data sibling, which it explicitly names.

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

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

Names the alternative directly ('Use geo_data with operation status for the full subsystem report'), giving a clear selection condition: this tool for a quick status read, geo_data for the fuller report. No explicit when-not or prerequisite guidance, but the routing to the sibling is unambiguous.

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