MobilityMCP

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

Annotations already declare readOnly/openWorld/non-destructive, and the description piles on behavior the annotations cannot carry: `unknown` means neither accessible nor bike-allowed, `staySeated` must not be inferred when absent, `not_considered` must never be reported as satisfied, `broken_journeys` don't run, and an explicit anti-fabrication rule about lines/times/stops. This is exactly the extra context annotations leave open.

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

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

Front-loaded with the purpose and the mandatory-endpoints rule, which is right, but the body becomes a dense run-on mixing routing rules, output-field semantics, filter enumerations and anti-fabrication advice into bold-separated clauses. For a 49-parameter tool length is justifiable, yet a fair share restates schema-documented parameters (`max_walk_from_origin` values, `verbosity` words) instead of earning new space.

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 49 parameters, no output schema, and the need to explain result fields (`departsExpected`, `firstRide`, `ascentInMeters`, `change`, `reliability`, `bikeCarriageConditions`), the description covers what an agent needs to both call and interpret the tool. It even points to `get_usage_guide` for the parts deliberately left out.

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 cross-parameter rules and intent that the schema does not: both endpoints are mandatory as id+type OR lat/lon, a name in an id field is an argument error, and several filters are gated on user intent (change_reliability, carsharing via access_modes, stay_minutes). It largely mirrors the schema rather than going beyond it, which keeps it out of 5 territory.

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 ("Plant ÖPNV-Verbindungen von A nach B") with geographic scope and real-time vs. timetable coverage, plus the distinctive framing "als Daten, für Ergebnisse, die du weiterverarbeitest". It explicitly distinguishes itself from the sibling `show_connections`, which it names as the human-facing entry point.

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

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

Gives concrete when-to-use routing against siblings (`show_connections` for a human question, `get_usage_guide` before filtering) and conditions for optional features: `change_reliability` only on reliability questions with explicit example phrasings, carsharing only on request, `cycling_profile` only for a bike ride. It also names when-not cases ("nein: 'A nach B um 16:30'") rather than only positive triggers.

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 safety profile (readOnlyHint, destructiveHint=false, openWorldHint), and the description layers on real behavioural context: a mandatory pre-resolved stop id, that a name in `id` is an argument error rather than an empty board, that an empty board is not an answer, and an anti-fabrication rule. It does not describe pagination or response shape, but for a read-only tool this is well above the bar.

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

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

Front-loaded with purpose and the required `id`, and bolds the load-bearing constraints (Pflicht, Optional, Anti-Fab). It is long and re-states some `lines`/`modes` detail the schema already carries, so it is dense rather than perfectly lean, but few sentences are 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 19-parameter, single-required-parameter read tool with no output schema, the description covers the mandatory argument, the sibling routing for the two special modes, the empty-result fallback, and points to get_usage_guide for deeper vocabulary. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema itself is unusually detailed, so the baseline is 3. The description still adds cross-parameter meaning the schema does not: hard vs. soft direction, that `['tram','subway']` must be set together for light-rail networks, and when to suppress a mode filter entirely.

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

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

Opens with a specific verb+resource+scope ("Abfahrten oder Ankünfte für EINE Haltestelle") and immediately frames it as structured data for downstream use rather than a human-readable board. It explicitly separates itself from show_departures, connections, first_last and facilities, so an agent can route without opening any schema.

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

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

Gives explicit trigger phrases and the alternative each selects: "wann fährt von X"/"letzte Stadtbahn" → this tool, A→B → connections, "letzte Bahn heute" → first_last, "hat X einen Aufzug" → facilities. Hard-filter behaviour of modes/lines/direction and the empty-board retry path are also 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 already cover safety (readOnly, non-destructive, openWorld), yet the description adds the crucial semantic that an empty answer is only an all-clear inside coverage regions, lists which regions those are, discloses AND-combination of line+stop, truncation signalling (truncated/total), and anti-fabrication rules. This is behavioral context far beyond the annotation set.

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 well front-loaded: purpose, data-coverage caveat, argument behaviour, format, guide pointer, then anti-fab rules in bold-labeled blocks. It is long, and some of the coverage/guide material is partly delegated, but nearly every sentence carries a distinct operational constraint.

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 six optional parameters, the description does the heavy lifting: it explains result shape at a high level (two lists, `coverage` values, truncation markers) and points to `get_usage_guide` for field-level detail. The reliance on an external guide for the seven coverage values and message fields is a minor gap but an intentional, disclosed one.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning not in the schema: that `line` and `stop` combine with AND, that `area` decides coverage and routes unplaceable reports to `unplaced` rather than suppressing them, and that agents should omit `format`. It mostly reinforces rather than extends the schema, hence 4.

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

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

Names a specific verb+resource in the first line ("Aktuelle Störungen, Baustellen und Liniensperrungen im ÖPNV") and immediately distinguishes itself from the sibling tools by stating that connections and departures are unaffected. An agent can tell this apart from departures/connections without opening any schema.

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

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

Gives concrete user phrasings that select this tool ("gibt es Störungen", "Ausfälle in X") and a hard filter rule ("Nenne nur Filter, die der Nutzer wirklich nannte"). It does not name a competing sibling tool to route away to, so it is strong context without explicit exclusions.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds valuable context: omitting `tool` returns all tool sections at once, supplying `tool` returns one section, and the full retrieval is costly. 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 dense and front-loaded with purpose, then explains parameter behavior and cost. Every sentence carries useful information, though it is slightly longer than strictly necessary.

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 guide tool with one optional parameter and no output schema, this description is complete: it explains purpose, when to use it, how the parameter behaves, what is returned, and cost implications. Nothing essential is missing.

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

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

Schema coverage is 100% and the parameter is already documented. The description adds decision guidance around when to supply `tool` versus omit it, including the cost trade-off, which goes beyond the schema. It does not enumerate valid tool names, but catalog context provides that.

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 is the detailed guide to all catalog tools, covering purpose, delimitation, arguments, return values, and quotation rules. It clearly positions itself as a meta-tool distinct from the domain-data sibling tools.

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

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

It explicitly says when to read a section (before setting filters or passing an empty result), when to omit the `tool` parameter, and when to set it. It also warns that calling without `tool` is expensive and should only be used for a full-catalog overview.

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/openWorld/non-destructive, and the description goes well beyond them: it discloses the candidates fallback for ambiguous names, the geometryDegraded and patternsTotal/matchedTotal semantics, unknown-place behavior, and a hallucination guardrail. Rich behavioral context for a read tool.

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

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

Front-loaded with purpose and then grouped into required/optional/response/limits/not-for sections. It is dense and long, but nearly every sentence carries distinct information; the bolding and structuring keep it navigable 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?

With no output schema, the description carries the full return-value burden and does so: it explains per-direction courses with headsign, halts, pathOnMap simplification, the candidates alternative, and the max ~50 m simplification with render_payload for full resolution. Nothing essential is missing.

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

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

Schema coverage is already 100%, so the baseline is 3. The description still adds value by foregrounding the 'exactly one of query/id' obligation and the area/limit defaults, though it mostly reinforces rather than extends the schema wording.

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 states a specific resource (the halt sequence of an ÖPNV line and its drawn map path) and pairs it with concrete user questions ('wo fährt die Y entlang'). It also explicitly names the siblings it is not (connections, departures, disruptions), so an agent can route correctly 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?

Gives an explicit when-to-use rule, the 'genau EINE Linie' constraint, the fallback when ambiguous (query by area or by id), and an explicit 'Nicht dafür' list mapping other needs to connections/departures/disruptions. Almost no inference is left.

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 readOnlyHint=true and openWorldHint=true, the description adds real behavioral detail: the result is a single instant (start == end), unresolvable phrases return candidates: [], and the agent must not fabricate dates or do its own date arithmetic. Nothing contradicts 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 fairly long and restates some schema details, but it is well structured: purpose and examples first, then parameters, then response semantics, then anti-fabrication guidance. Every part earns its place, though a bit of trimming would make it tighter.

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 subtle semantics (timezone interpretation, vague phrases, single-instant result), the description is complete: it states the return shape, where the value flows (connections.time / departures.time), the empty-candidates behavior, and the required follow-up action. It also points to get_usage_guide for finer 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 coverage is 100%, so the schema already documents all four parameters. The description adds meaningful operational semantics beyond that: text is marked as Pflicht, tz default is explicitly tied to Europe/Berlin local-time interpretation, and format is labeled as something the agent should leave out. This is more than the baseline needed for full schema coverage.

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

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

The description uses a specific verb+resource construction: "Löst eine Zeit-Nennung in einen absoluten ISO-8601-Zeitpunkt auf" and then gives concrete examples like "morgen früh" and "in zwei Stunden". It also states a clear boundary against a sibling scenario (full ISO-8601 with offset needs no call), so an agent can tell exactly what this tool does.

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

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

It explicitly says when to invoke (any time mention), when not to invoke (user already gave a complete ISO-8601 timestamp with offset), and points to get_usage_guide for the ambiguous-time case. It even instructs the agent to use this tool as the canonical source for "now" instead of inventing a date, which is strong usage 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 cover the safety profile (readOnly/openWorld/destructive=false), but the description goes well beyond: it discloses the TOON text output format, the fact that opening hours and prices are absent, the fields a hit carries, and the special availability semantics (unknown availability is not treated as available). This is rich behavioral context an agent cannot get from the annotations alone.

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, then required/optional, then format, guide pointer and anti-fabrication rules, so the structure is easy to scan. It is long and partly duplicates the schema's own node_types enumeration, but nearly every sentence carries operational value.

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 8 parameters, the description covers what an agent needs: output format, what a result carries, availability caveats, and anti-fabrication rules, while delegating exhaustive detail to `get_usage_guide`. Nothing essential for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds real meaning — required vs optional split, the comma-string form of `node_types`, the fact that `'any'` does NOT cover park_and_ride/charging_station/taxi, and the distinction between unknown and unavailable for `only_available`. It slightly repeats schema text, 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: finds stops, POIs and addresses within a radius of a coordinate, with two concrete example queries. It also distinguishes itself from siblings by routing name-only inputs to `search_place` (city/region) or the place resolution, so an agent can tell it apart without opening another schema.

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

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

Explicit when-to-use phrasing ("was ist in der Nähe von <lat,lon>") plus explicit alternatives (`search_place` for a city/region, otherwise the place resolution). It also directs the agent to `get_usage_guide` for the finer points and names the default serialisation, leaving little 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 only cover the safety profile (readOnly/openWorld/non-destructive). The description adds real behavioral context well beyond them: A→B needs two calls, every hit carries `type` and `location`, only a `stop` has a rideable DH-ID that must never be invented, `modes` reveals what stops there, and `name`/`localName` disambiguate language. It also states that an invalid kind is an argument error rather than a dropped filter.

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

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

Purpose is front-loaded and the rest is chunked under bold labels (Pflicht, Optional, Art-Wort, A→B, Anleitung, Anti-Fab), which makes it scannable. It is nevertheless long and partly duplicates the schema's parameter prose, so it is efficient but not maximally tight.

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 (type, location, modes, localName vs name) plus an anti-fabrication rule. The remaining gap is what to do when nothing resolves — the no-match / empty-result behavior is not stated.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the mandatory `query` hygiene rules and the `node_types`/`city_station` semantics, but these are already documented verbatim in the schema, so it adds little beyond the structured fields apart from emphasis.

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 precise verb+resource: it resolves free text into the ID that travel uses, and immediately names the situations (routing, departure board, POI profile). It explicitly differentiates from the sibling `search_place`, which handles an AREA (city/region) rather than a point. An agent can route between the two without opening either schema.

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

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

States when it is needed ('where routing, departures board or POI profile requires an ID'), names the alternative for areas (`search_place`), and routes shared-mobility kinds (rental station, taxi rank) to `nearby`. It also prescribes the calling pattern for A→B ('call twice') and points to `get_usage_guide` for further distinctions.

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=true and openWorldHint=true, so the description does not need to repeat basic safety. It adds genuinely non-obvious behavior: fallback to a coarser level when the requested level is missing and the result is recognizable via place_type, distance-0 inclusion in any radius, limit clamping, and the anti-hallucination instruction to use only returned names. Nothing in the description contradicts 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 dense but highly structured: purpose, boundary, required args, optional args, fallback behavior, instruction source, and anti-hallucination rule each get a clearly labeled section. Although it is longer than many descriptions, every sentence carries operational value; there is no filler or tautology.

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

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

For a 6-parameter tool with no output schema, the description covers all parameters, defaults, edge cases, sibling-tool routing, and output interpretation (place_type fallback indicator). It also gives an anti-fabrication rule for returned names, which is critical practical guidance. The reference to get_usage_guide fills any remaining serialization detail without bloating the main description.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it by adding the one-spelling-per-call rule, explaining the nearest-hit behavior when radius_m is omitted, and clarifying that unknown level values behave like 'place'. It largely restates schema semantics for radius_m and limit, but it provides extra operational context that helps an agent invoke 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?

States a specific action and resource: names what lies at a coordinate, optionally at a chosen level, including street-level reverse geocoding. The first sentence alone tells an agent not just what the tool returns but that it is the lookup for a GPS start position. It also distinguishes itself from nearby and search_place, making sibling confusion unlikely.

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 gives when-to-use guidance: reverse geocoding a coordinate, street labeling for GPS positions, and the distinction from search_place (name → coordinate), nearby (what lies around), and another resolution tool. It also states required parameters, the mandatory spelling consistency rule, and points to get_usage_guide for further detail.

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 cover the safety profile (readOnly, openWorld, non-destructive), and the description goes well beyond them: it discloses that a station name yields a same-named district (one in Potsdam) and that the returned id is an OSM id, not a drivable stop id. It also explains the score matching semantics (1 = exact, >=0.5 whole word) and adds an anti-fabrication instruction about only using returned names and ids.

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

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

Front-loaded with the core purpose, then the critical exclusion, then parameters, then the usage guide and anti-fabrication note, with bold markers making sections scannable. It is dense rather than padded, but the single block is long and some parenthetical examples could be trimmed without loss.

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 lookup with no output schema, it covers purpose, alternatives, required/optional params, matching behavior and what the returned id actually is. It stops short of describing the full response shape (e.g. whether coordinates and ids come as a list of candidates), so an agent still infers some of the return structure.

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 a 3 is the baseline. The description adds real signal on top: it restates name as mandatory and clarifies that lang has no current effect (the schema only says "advisory"), which is a genuine refinement. The format parameter is left to the schema and the reference to a `score` field is a bit ambiguous, keeping it from a full 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 precise verb and resource: it resolves the NAME of a city, region or district into coordinates and OSM-Ids, and frames this as the first step for locating an area. It actively distinguishes itself from siblings by naming reverse_geocode and nearby for their respective jobs, so an agent can route without opening any schema.

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

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

Gives explicit when-to-use (locating a region/city for questions like weather or activities) and explicit when-NOT-to-use (any request containing Bahnhof/Hbf/Bf or any stop/address/POI that could be a journey endpoint, which belongs to resolve_location). Concrete examples ("Köln Hauptbahnhof", "Hannover Bahnhof") show what goes wrong otherwise, and it points to get_usage_guide for deeper chaining.

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/openWorldHint and non-destructive, so the safety profile is covered; the description adds genuinely non-obvious behaviour: both endpoints are mandatory (even though the schema lists zero required fields), `render_payload` is dropped, the answer text mirrors `connections`, and the raw payload carries only view-drawn fields in local time with the map course in `_meta`. It does not describe failure/empty responses, though the schema notes that unknown ids answer empty rather than erroring.

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

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

Front-loaded correctly: identity and the call-instead-of-`connections` rule come first, then constraints, then output shape, then anti-fabrication. It is dense and mixes German prose with English parameter jargon, and the repeated 'wie dort' back-references pad it slightly, but almost every clause carries decision-relevant content for a 48-parameter tool.

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

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

For a 48-parameter tool with no output schema, the description covers the essentials an agent needs to call it correctly: the endpoint requirement, opt-in flags, the shape of the returned view versus raw data, and where to get parameter detail (usage guide, `tool='connections'`). The view payload's structure itself is only summarised, not specified, which is the remaining gap.

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

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

Schema coverage is 100% across 48 parameters, so baseline would be 3; the description earns above that by flagging the endpoint requirement the schema does not enforce, excluding `render_payload`, and pinning the two opt-in switches to their guarding parameters (`change_reliability`/`max_miss_risk`, `car:sharing` with `stay_minutes`). The remaining ~40 parameters are left entirely to the schema and the usage guide.

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 two sentences state a specific verb and resource (plan a journey like `connections`, deliver it as a renderable view with one card per connection) and explicitly name the sibling this replaces. An agent can distinguish `show_connections` from `connections` and `show_connections_slim` without opening either schema.

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

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

Explicit routing rule: 'Beantwortest du einem Menschen eine Verbindungsfrage, ruf dies statt `connections`' with the exclusion stated for `connections` (results you further process). It also states when optional behaviour should be switched on ('nur auf Wunsch' for change_reliability, max_miss_risk, car sharing) and points to `get_usage_guide` with `tool='connections'`.

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 safety profile (readOnlyHint, openWorldHint, destructiveHint false), yet the description still adds real behavioral content: render_payload is absent, the raw payload carries only the fields the view draws (in local time) and the map course lives in `_meta`, and the answer text is identical to `connections`. The anti-fabrication rule (lines, times, stops, tracks only from this call's output) is a genuinely useful constraint that no annotation or schema field conveys.

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 discriminator and the 'only when asked' rule are front-loaded in bold, and the rest is organized by concern (payload shape, opt-in features, response, guide, anti-fabrication). It is dense but not padded. Minor cost: a couple of long compound sentences (the raw-data/_meta sentence in particular) that a reader has to parse twice.

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 48-parameter tool with no output schema, it covers the two things that matter most: what the input must contain regardless of `required: []`, and what the answer looks like (departs/arrives, firstRide after a walk, view-only raw fields in local time, map course in `_meta`). It delegates the remaining vocabulary to get_usage_guide with tool='connections', which is a legitimate strategy at this schema size, though it means an agent that skips the guide knows less about the other 40 params than it ideally should.

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% across 48 params, so the baseline would be 3 — but the description adds a crucial fact the schema does not: while `required` is empty, both endpoints are in practice obligatory (origin_id AND destination_id, or the four coordinate fields). It also states which schema knobs belong to conditional behaviour (change_reliability / max_miss_risk, car:sharing plus stay_minutes), which steers parameter choice rather than merely restating field docs.

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 by naming the exact resource and its defining variant ('dieselbe Verbindungs-Ansicht wie show_connections, nur schlank ausgeliefert') and explains the mechanical difference: the map widget loads the view as a script rather than shipping it inline. It then names the sibling it must not be confused with, so an agent can route between show_connections_slim and show_connections without opening either schema.

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

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

Explicit gating condition: 'Nimm dies nur, wenn ausdrücklich nach der schlanken Auslieferung gefragt wird — sonst show_connections.' That is a rare, unambiguous when/when-not plus the named alternative. It also repeats the opt-in conditions for the risky optional features (change_reliability only on request, carsharing only via car:sharing in access_modes/egress_modes), which prevents an agent from over-enabling parameters.

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/openWorld/non-destructive, so the bar is lower, and the description still adds real behavior: the response text equals `departures`, the raw payload carries only view-drawn fields, the id must come from `resolve_location`, and an explicit anti-fabrication constraint. It stops short of describing pagination or view rendering mechanics, but the added context is 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?

Purpose and the sibling-routing decision are front-loaded before the id requirement and the guide pointer, so an agent gets the critical selection signal first. The heavy bold markup and long compound sentences add some density, but nothing is truly 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?

For a 16-parameter tool with no output schema, the description states what the answer contains (the `departures` text plus a view-shaped raw payload), the mandatory id source, and where to find further guidance. The safety profile is carried by annotations, so the remaining gap is only detail on the optional filters, which the schema covers.

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

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

Schema coverage is 100% so baseline is 3, but the description adds genuinely new semantics: `render_payload` is dropped here, `id` must be a resolver-issued id rather than a stop name, and the output field set differs from `departures`. It does not re-explain the many optional filters, which the schema already handles 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?

Opens with a bold, specific framing ('Der Vordereingang für jede Abfahrtsfrage eines Menschen'), states it reads a stop's board like `departures` and returns it additionally as a view, and names the sibling it replaces. An agent can distinguish it from `departures` without opening either schema.

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

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

Explicit routing rule: 'Beantwortest du einem Menschen eine Abfahrtsfrage, ruf dies statt `departures`, das für Ergebnisse ist, die du weiterverarbeitest' — when to use it, which alternative to avoid, and why. Also points to `get_usage_guide` for the deeper vocabulary.

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