overpass.ch

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: the call is quota-free ('It does not count as a request') and it exposes when the allowance resets plus the age of the underlying data — both relevant to deciding whether to proceed with a query.

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

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

A single sentence plus a short quota caveat, with the core subject ('the plan of the API key… and its use this month') front-loaded before the enumeration. No filler, and the quota-free note is placed last where it reads as a qualifier rather than burying the payload.

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 carries the burden of describing return content, and it does so by listing the counters an agent will receive. That is close to sufficient for a no-argument status tool; only the shape/grouping of those fields (flat keys vs. nested) is left implicit.

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 no parameter semantics for the description to compensate for; the baseline for 0 params is 4. Nothing in the text misdescribes an input, and additionalProperties=false with an empty object matches the 'this connection' framing.

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

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

The description names a specific resource — the API key's plan and this month's usage — and enumerates the counters it reports (Overpass requests used/left, reset time, running queries, elevation lookups, geocoding). That is far more specific than the title alone. It never explicitly contrasts itself with siblings like overpass_query or geocode, but the meta/status framing makes the distinction obvious.

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 only implied: an agent can infer this is the call to make before or instead of consuming quota, and the closing note that it 'does not count as a request' mildly encourages calling it freely. There is no explicit statement of when to call it versus the sibling query tools, nor any precondition such as checking remaining allowance before a large Overpass query.

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 readOnly, idempotent, non-destructive and closed-world, so the description is free to add what they can't: ground vs. surface modelling (Copernicus includes buildings and trees), 2 m vs. 30 m resolutions, negatives at sea, and an attribution obligation ('credit © swisstopo'). Only the return shape and behaviour for unsupported points are left unstated.

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

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

Front-loaded with the core output (metres above sea level, negative at sea), followed by coverage, then billing. The telegraphic source list is dense but every clause carries information; nothing is 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 two-parameter read-only lookup this covers accuracy expectations, geographic coverage, licensing and cost. With no output schema, the one remaining gap is that it never states the response is a per-point list of heights in input order.

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 lat/lon bounds and max_chars truncation-with-offset behaviour are already documented in the schema. The description adds only that each point is billed as one lookup, a useful cost semantic but a marginal addition.

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

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

The description names a concrete verb-and-resource ('Heights above sea level in metres for a list of points') and backs it with data sources, so the purpose is unmistakable. It stops short of naming the sibling elevation_profile or explaining how the two differ, which is the main thing an agent must decide between.

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 indirect routing guidance by disclosing per-region sources (Switzerland/Liechtenstein vs. elsewhere on land vs. sea) and a cost model ('Each point counts as one lookup; account_status shows the plan maximum per call'), which implies when to batch or split calls. There is no explicit when-to-use/when-not statement and no comparison with elevation_profile or geocode.

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: a 90 m default sampling interval, an override mechanism, a 100-point return cap, and a per-sample quota cost that can hit the plan maximum per call.

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

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

Three sentences, each earning its place: returns first, sampling default second, cost third. No output schema exists, so enumerating the returned fields is necessary rather than redundant.

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

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

With no output schema, the description correctly carries the return-value burden and adds the quota constraint. Remaining gaps are the truncation behavior above 100 points and the precedence rule between the two sampling parameters.

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

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

Schema coverage is 100%, so the baseline is 3, and the description only partially goes beyond it by explaining that `samples` or `interval_m` replace the 90 m default. It does not clarify what happens if both are set simultaneously, nor how `samples` interacts with the 100-point cap.

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 (elevation profile) and scopes it to "a path of two or more points," which implicitly separates it from the sibling `elevation` tool for single points. It also enumerates exactly what is computed: distance, ascent, descent, lowest/highest point, and per-sample distance/height/lat/lon.

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 sampling defaults and the cost model ("each sample counts as one lookup, up to the plan maximum"), which tells the agent how to use it economically. However, there is no explicit when-to-use routing versus the `elevation` sibling, and no stated precedence when both `samples` and `interval_m` are supplied.

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 annotations already cover read-only, idempotent and non-destructive behavior; the description adds context the annotations do not carry, namely that one call counts as one geocoding request (quota cost) and what the result payload contains (name, address, lat/lon, bounding box, osm element, overpass_area_id). It does not describe error or empty-result behavior, so it stays at 4.

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

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

It is front-loaded with the core purpose and stays to a few dense sentences with no filler. The enumeration of returned fields is slightly list-like but each item is functional information, so it earns its place.

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

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

With no output schema, the description usefully enumerates return fields, and it explains how to chain results into overpass_query. For a seven-parameter tool with nested objects and an 86% schema coverage, the schema handles the rest. The only gap is the absence of any note on empty or ambiguous 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 coverage is 86%, so the schema already documents most parameters. The description restates the supported languages (en, de, fr), which duplicates the enum already in the schema, and adds no meaning for near, within, kind, limit or country_codes. Baseline 3 is appropriate when the schema carries the load.

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: 'Finds places, addresses and points of interest by name (geocoding)', and adds that partial text works for autocomplete. The phrase 'by name' implicitly contrasts with reverse_geocode, but no sibling is named explicitly, so the differentiation falls slightly 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?

There is no explicit when-to-use or when-not guidance, and no comparison to reverse_geocode or overpass_query. It does, however, give actionable follow-up guidance: results carry an osm element, and for ways and relations an overpass_area_id usable in overpass_query as area(id:N). That is real workflow guidance, even if selection guidance between siblings is left 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 readOnly, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds real value by disclosing the return shape ("the 5 closest examples with their query and a link") and the quota behavior ("Free: it does not count as a request"). What remains unstated is how "closest" relevance is determined or what happens when no examples match.

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, both front-loaded: the identity of the tool first, then the input/output contract. The example list is compact and each example maps to a distinct query pattern, so no sentence is wasted.

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

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

For a single-parameter, read-only lookup tool with no output schema, the description supplies everything needed: what it searches, what to pass, what comes back, and that it costs nothing against quota. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already describes topic as "what the query should find, in a few English words." The description goes beyond that by giving four concrete example topics and the "in a few words" format expectation, which helps the agent phrase a good input rather than just understand the field.

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?

"Searches the cookbook of overpass.ch: Overpass queries that were tested on the full planet" gives a specific verb (searches) and resource (a curated example-query cookbook), and the contrast with executing queries is implicit in the wording. It does not name the sibling overpass_query explicitly, so the differentiation from that tool is left to inference 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?

The description gives concrete sample topics ("bakeries in a city", "hiking routes", "count buildings", "changes since a date") that show what kinds of inputs this tool is meant for, and notes it is free, nudging the agent to try it before composing a query. It stops short of explicitly saying "use this before calling overpass_query" or stating when-not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive behaviour, and the description adds real operational context on top: per-call request accounting ('Each call counts as one request of the plan, a cut one too'), timeout capping at 120 s, truncation at max_chars with offset continuation, plan gating of the date filter, and attribution/licence terms. That is exactly the extra context annotations cannot 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?

The core statement and return behaviour are front-loaded, and the pattern list is dense but each line encodes a distinct query idiom that is otherwise hard to infer. It is long, and a few patterns ('Lines with coordinates: out geom; (large)') are terser than the rest, but no sentence is filler.

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

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

With no output schema, the description still explains the response shape ('starts with counts and the date of the data, then one JSON object per element and line'), pagination behaviour, and data provenance. For a free-form query tool of this complexity, an agent has everything needed to call it correctly and to react to a truncated answer.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond it by explaining how max_chars and offset interact ('The answer ... up to max_chars characters. When it is cut, call again with offset') and by tying [timeout:N] to a hard 120 s ceiling. add_elevation is left entirely to the schema, which keeps it from a 5.

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

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

States a specific verb and resource ('Runs an Overpass QL query on the full OpenStreetMap planet at overpass.ch') plus what comes back ('nodes, ways and relations with their tags'). This clearly separates it from siblings like geocode, reverse_geocode and elevation, which do lookup-style work rather than arbitrary spatial queries.

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 patterns block gives concrete when-to-use-which-form guidance (box, around radius, area, name, count, tags, geom, regex, id) and notes plan restrictions for the date filter. It never explicitly routes to the sibling overpass_examples for query authoring, which is the one obvious gap.

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, non-destructive, and closed-world behavior, so the description needn't restate safety. It adds genuinely new context: the default value of 'detail' (address), the quota impact ('One call counts as one geocoding request'), and where to look for the result shape. It does not say what happens when no address exists at the point, which is the main remaining gap.

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

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

Front-loaded with the one-line purpose, then the parameter semantics, then the result/cost notes — every sentence carries information an agent would otherwise have to infer. No repetition of the title 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?

With no output schema, the description compensates by pointing to geocode's fields and by covering the enum semantics, default, and request cost. Edge-case behavior (unresolvable points, partial matches, error responses) is the only notable omission for a lookup tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns more by explaining the containment hierarchy behind the 'detail' enum and disclosing its default, neither of which the schema states ('what to return' is all it says). The 'language' parameter is left entirely to the schema, keeping it short of a 5.

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

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

States a specific verb and resource ('Finds the address or place at a point') and names the operation class ('reverse geocoding'), which immediately separates it from the sibling geocode tool that goes the other direction. An agent can select it without opening the schema.

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

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

The description explains the selection logic for the 'detail' parameter in plain terms (nearest address/object, then progressively larger containing units), which tells the agent when to pick each mode. It references geocode only for output-field parity rather than as an explicit alternative, so the when-not-to-use guidance is implied rather than stated.

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