Journeys, departures, line courses, disruptions in Germany; nearby sharing as currently reported.
Scored across 13 tools
Most tools have distinct purposes, and the location-related tools are well-differentiated. However, connections, show_connections, and show_connections_slim all perform the same route-planning operation, creating real overlap; the descriptions mitigate this but the agent must read carefully to pick the right variant.
Tool names are readable and snake_case is used throughout, but the naming style is mixed: some tools are bare nouns (connections, departures, disruptions), some use verb_noun (resolve_location, search_place, link_datetime), and three use a show_ prefix. There is a logic to the pattern, but it is not consistent across the whole set.
13 tools is a reasonable size for a mobility API covering routing, departures, disruptions, line courses, and geocoding. The three connection variants and data/view pairs add mild redundancy, but each variant serves a documented delivery mode.
The surface covers the main transit-information workflow end to end: place/stop resolution, routing, departures, disruptions, line geometry, reverse geocoding, nearby search, and natural-language time parsing. For a read-only mobility information server, there are no obvious dead ends or missing core operations.
Plant ÖPNV-Verbindungen von A nach B, deutschlandweit, Fernrouten eingeschlossen — als Daten, für Ergebnisse, die du weiterverarbeitest. Steht show_connections in deinem Werkzeug-Satz, ist das der Vordereingang für die Frage eines Menschen. Für „wie komme ich von X nach Y" kommt die Auskunft aus diesen Werkzeugen, nicht aus dem Allgemeinwissen. Pflicht sind BEIDE Endpunkte: origin_id UND destination_id aus einer Ortsauflösung, mit origin_type/destination_type — ODER origin_lat+origin_lon+destination_lat+destination_lon; ein NAME in einem Id-Feld ist ein Argument-Fehler. Optional: time, is_arrival_time; via_id bzw. via_lat+via_lon mit via_type; die hart einschränkenden Filter modes, only_lines/exclude_lines, submodes_allow/submodes_deny, max_transfers, max_walk_minutes/max_walk_meters, walk_speed, accessibility_profile, include_rental_bike, prefer_flat, mobility_profile; verbosity, limit, render_payload. Höhenmeter: nur Fuß-/Rad-Abschnitte tragen ascentInMeters/descentInMeters. Durchbindung: staySeated: true an einem Abschnitt heißt, der Fahrgast bleibt aus dem vorigen sitzen — kein Umstieg, also auch keinen zählen. Fehlt das Feld, ist nichts gesagt; nie selbst herleiten. Rad-Tempo: Bei einer Radfahrt setzt cycling_profile das Tempo des Fahrers und damit die gemeldete Dauer — family bei kleinen Kindern, ebike bei E-Bike/Pedelec; sonst weglassen (= normal). Fahrradmitnahme: Geht es um ein Rad, sprich je Abschnitt bikeCarriageConditions aus (Bedingungen des Verbunds zur Abfahrtszeit); bikesAllowed/bikeCarriageNote sind nur die Grundregel, bikeCarriageCoverage die Wissensgrenze. Genannter Wunsch: Nennt jemand, was ihn stört ("nicht in der Innenstadt parken"), hol die Option, die das löst, als EIGENEN Aufruf (mobility_profile) und empfiehl sie aus ihrem Nutzen — mit dem Nachteil, den die Antwort ihr gibt. Anleitung: get_usage_guide mit tool='connections' — lies sie, bevor du filterst. Anti-Fab: Linien, Zeiten, Halte, Anlagen und Gleise ausschließlich aus dem Output dieses Aufrufs.
| Name | Required | Description | Default |
|---|---|---|---|
| time | No | ISO 8601 timestamp (e.g. `"2026-06-15T08:30:00Z"`). Omit to plan from now. Resolve a spoken time with the time tool rather than computing one. | |
| limit | No | Maximum number of journeys, at least 1. Default 5, values above 15 are served as 15. | |
| modes | No | Transport-mode restriction, not a preference: nothing outside the list is planned. The footpath always stays allowed — the way to, from and between stops goes on foot — while `["foot"]` on its own plans no ride at all. Entries: `"bike"`, `"bike_rental"`, `"foot"`, `"car"`, `"taxi"`, `"scooter"`, `"transit"`, `"bus"`, `"tram"`, `"rail"`, `"subway"`, `"ferry"`; several combine. An entry outside that list is an argument error, not a dropped filter. Omitted or empty = all standard transit modes, the ferry included. Set only when the user insists on a mode; the guide has the vocabulary and the traps. | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** | |
| via_id | No | Intermediate stop the route must pass through („über X"), as an id in the same form as `origin_id`. The route is then planned A → via → B. | |
| via_lat | No | Via latitude, for an intermediate address or POI without an id. Goes with `via_lon`. | |
| via_lon | No | Via longitude. Goes with `via_lat`. | |
| extended | No | `true` keeps the map data in the text: every stop's coordinate, every leg's polyline, and the whole stop sequence with them — for an application that DRAWS the route, at two to three times the answer. A chat client leaves it off. | |
| via_type | No | What `via_id` is. Same values as `origin_type`. | |
| origin_id | No | Origin id. A DHID (`de:NNNNN:NNN`) for a stop, otherwise the resolver's `main` id of the address or POI. Resolve the place first — a name here is an argument error. | |
| verbosity | No | How much of each journey comes back: `"compact"` (default — everything an answer is cited from) or `"full"` (adds the stops in between). A third word is an argument error, not the default. | |
| only_lines | No | Line whitelist. Entries are line tokens as printed on the vehicle (`"6"`, `"U3"`); a journey is kept only if every transit leg uses one of them. | |
| origin_lat | No | Origin latitude, WGS-84 decimal degrees — the fallback when no id is at hand, and the one retry worth making when resolved ids find nothing. | |
| origin_lon | No | Origin longitude. Goes with `origin_lat`. | |
| walk_speed | No | Walking speed of the foot legs in metres/second, between 0.3 and 3 m/s — outside that it is an argument error. Default ≈1.33, slow ≈0.7, brisk ≈2.0. Overrides the walk speed of `accessibility_profile`. | |
| origin_type | No | What `origin_id` is: `"stop"` (default), `"address"` or `"poi"`. A stop id is auto-prefixed `GTFS.de:`; the other two are forwarded verbatim so the backend resolves the real name. | |
| prefer_flat | No | `true` plant die hügel-ärmste statt der sonst gewählten Rad-Route: die Suche gewichtet die Steigung und nimmt dafür Umwege in Kauf, nur auf Rad-Abschnitten. Keine Zusage — ohne flachere Alternative kommt dieselbe Route; die Höhenmeter der Antwort sagen es. Wann setzen: die Anleitung. | |
| cycling_speed | No | Rad-Tempo in Metern/Sekunde, 1 bis 12 — außerhalb ein Argument-Fehler. Überschreibt `cycling_profile`. Richtwerte: Familie ≈2.8, normal ≈5, Pedelec ≈6.5. | |
| exclude_lines | No | Line blacklist, same token form as `only_lines`. A journey is dropped if any transit leg uses one of them. | |
| max_transfers | No | Upper bound on interchanges: `0` = direct, up to `3`. Omit unless the user constrains transfers: the backend then derives the search depth from the trip's air-line distance and escalates it when the first attempt finds nothing, so omitting never loses a connection. | |
| submodes_deny | No | Fine submode blacklist, same vocabulary as `submodes_allow`. A journey is dropped if any transit leg matches one. | |
| destination_id | No | Destination id. Same form as `origin_id`. | |
| render_payload | No | `true` appends the same journeys again as raw JSON, addressed to the user rather than to the model — the map geometry an application draws from. A chat client leaves this off: it is the whole answer twice. | |
| submodes_allow | No | Fine submode whitelist — finer than `modes`, which only separates bus/tram/rail/subway. Entries: `"sbahn"`, `"regionalbahn"`, `"ice"`, `"ic"`, `"ir"`, `"nj"`, `"fernverkehr"`, `"stadtbahn"`, `"ubahn"`, `"bus"`, `"regionalbus"`, `"stadtbus"`. A journey is kept only if every transit leg matches one. | |
| cycling_profile | No | Wer auf dem Rad sitzt, und damit das Tempo der Rad-Abschnitte: `family` (mit kleinen Kindern), `normal` (Default, unverändert) oder `ebike` (Pedelec). Ein anderer Name ist ein Argument-Fehler. | |
| destination_lat | No | Destination latitude. Same use as `origin_lat`. | |
| destination_lon | No | Destination longitude. Goes with `destination_lat`. | |
| is_arrival_time | No | `true` reads `time` as the desired ARRIVAL time instead of the departure time. | |
| max_walk_meters | No | Cap on the summed walking DISTANCE in metres. Works like `max_walk_minutes`, on the metres walked. | |
| destination_type | No | What `destination_id` is. Same values as `origin_type`. | |
| max_walk_minutes | No | Cap on the summed walking TIME in minutes. A post-filter drops journeys above it; if that leaves nothing, the backend searches once more avoiding footpaths before the answer is empty. | |
| mobility_profile | No | How the first and the last mile may be covered, by name: `"transit"` (default — both ends on foot), `"transit_plus_sharing"` (a shared bike), `"door_to_door"` (being driven), `"park_and_ride"` or `"bike_and_ride"` (one's OWN car or bicycle, left where the transit leg starts). Another name is an argument error. It widens those two ends, restricts no ride and promises nothing. When to set which, and how it composes with `modes`, is in the usage guide. | |
| include_rental_bike | No | `true` adds a rental-bike leg (park-and-bike / station rental). Equivalent to naming `"bike"` in `modes` together with a transit mode. | |
| accessibility_profile | No | Mobility profile by name: `"Standard"` (default), `"WheelchairRobust"`, `"WalkerComfort"` or `"IndividualComfort"`. Each bundles its accessibility constraints and walk speed; another name is an argument error. The two wheelchair profiles find no ride at all today — the answer then carries `accessibility_routing` with `status: no_data` beside ordinary connections, which are to be reported as ordinary ones. What each profile constrains is in the usage guide. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false, openWorldHint=true) already cover the safety profile, and the description enriches it heavily: modes is a hard restriction not a preference (["foot"] alone plans no ride), max_walk_minutes is a post-filter with a retry-without-footpaths fallback, omitted max_transfers derives search depth by distance and escalates, wheelchair profiles return no_data status, staySeated must never be inferred, and an explicit anti-fabrication rule. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The text is well-structured — bold section labels, front-loaded purpose, and dense paragraphing make it scannable — but it is far longer than a typical tool description, approaching a mini usage-manual. Several coaching paragraphs (bike carriage reading, "Genannter Wunsch" mobility_profile advice, anti-fabrication) duplicate or pre-empt content the description itself defers to get_usage_guide, so not every sentence earns its token cost.
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 34-parameter tool with no output schema, the description covers the orchestration-critical material: mandatory endpoint pairing, the coordinate fallback as the one worthwhile retry, hard-vs-soft filter semantics, output-interpretation traps (staySeated, ascentInMeters, bikeCarriageConditions, accessibility_routing no_data), and an explicit pointer to get_usage_guide. It is not a 5 because substantial behavior is deferred to that guide and there is no structured overview of responses or error/empty-result behavior beyond scattered hints.
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 per the baseline the description need not repeat parameter detail — and it mostly doesn't add meaning beyond it. It does emphasize cross-parameter rules (both endpoints mandatory, id-vs-coordinate exclusivity, filter grouping as "hart einschränkend"), but these largely restate the schema's own top-level and per-field descriptions. The added interpretation rules (cycling_profile→duration, staySeated counting) are output semantics rather than new parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb, resource, and scope: "Plant ÖPNV-Verbindungen von A nach B, deutschlandweit, Fernrouten eingeschlossen" — planning transit connections nationwide, including long-distance routes. It then explicitly differentiates from the sibling show_connections by framing this tool as the data-oriented variant ("als Daten, für Ergebnisse, die du weiterverarbeitest") versus the "front entrance" for a human question, so an agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when/when-not/tool-selection guidance: "Steht show_connections in deinem Werkzeug-Satz, ist das der Vordereingang für die Frage eines Menschen" names the alternative and the condition for choosing it instead, while the opening frames this tool as the choice when data needs further processing. It also instructs that answers must come from these tools rather than general knowledge and directs the agent to read get_usage_guide before filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Abfahrten oder Ankünfte für EINE Haltestelle — als Daten, für Ergebnisse, die du weiterverarbeitest. Steht show_departures in deinem Werkzeug-Satz, ist das der Vordereingang für die Frage eines Menschen. Für „wann fährt von X", „letzte Stadtbahn von X" kommt die Auskunft aus diesen Werkzeugen, nicht aus dem Allgemeinwissen; für eine A→B-Frage aus connections. Pflicht ist eine konkrete Stop-id aus einer vorhergehenden Ortsauflösung (z.B. 'de:03241:57'); ein Haltestellen-NAME in id ist ein Argument-Fehler, keine leere Tafel. Optional: time und is_arrival_time; modes; direction (Halt-Name, in dessen Richtung gefahren wird) bzw. für eine weiche Angabe target_bearing mit bearing_tolerance; arrival_departure; für „letzte Fahrt des Tages" time_range_seconds zusammen mit last_of_window; und für den Umfang verbosity, limit sowie render_payload. modes und direction schränken hart ein. Eine leere Tafel ist keine Auskunft: blieb sie mit ['tram'] („Straßenbahn") leer, mit ['tram','subway'] nachfassen — sonst ohne den Filter. Anleitung: get_usage_guide mit tool='departures' — die Fenster-Kette für „letzte Fahrt", die Echtzeit-, Ausfall- und Zitier-Felder. Anti-Fab: Linien, Richtungen, Zeiten, Gleise, Verspätung und Ausfall ausschließlich aus dem Output dieses Aufrufs.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Stop id to read the board of, as a DHID (`"de:03241:57"`). Resolve the stop first — a name here is an argument error. | |
| time | No | ISO 8601 timestamp (e.g. `"2026-06-15T08:30:00Z"`). Omit for now. Resolve a spoken time with the time tool rather than computing one. | |
| limit | No | Maximum number of departures, at least 1. Default 5, values above 15 are served as 15. | |
| modes | No | Transport-mode filter; the board then shows nothing else. Entries: `"bus"`, `"tram"`, `"subway"`, `"train"`/`"rail"`, `"ferry"`, `"transit"`; several combine. Another entry — a street mode, a misspelling — is an argument error, not a dropped filter: a board lists scheduled services. Omitted or empty = all modes. A Stadtbahn or light-rail mention needs BOTH labels — `["tram","subway"]`: which of the two such a network carries depends on the dataset rather than on the vehicle. Set the filter only when the user really asks for a vehicle type; the guide has the rest of the vocabulary and the traps. | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** | |
| extended | No | `true` keeps the map data in the text: every stop's coordinate, the whole course of each run, and a polyline where the board carries one — for an application that DRAWS the board. It multiplies the answer. A chat client leaves it off. | |
| direction | No | Name of a stop the user wants to head TOWARD („Richtung Wettbergen") — not a routing destination. The board keeps only departures heading that way, whether the named stop is the terminus or a stop downstream of the queried one. Matching is case-insensitive and area-prefix-tolerant. | |
| verbosity | No | How much of each departure comes back: `"compact"` (default — everything an answer is cited from) or `"full"` (adds the onward stops of the run, and with them the per-stop cancellation marker). A third word is an argument error, not the default. | |
| last_of_window | No | Which end of a `time_range_seconds` window to read: omitted or `false` the FIRST departures, `true` the LAST ones (the end-of-service question). An answer carrying `window_truncated: true` beside its board did NOT reach the window's end — its last entry is then not the last departure. Without a window it has no effect. | |
| render_payload | No | `true` appends the same board again as raw JSON, addressed to the user rather than to the model — for an application that draws a departure board. A chat client leaves this off: it is the whole answer twice. | |
| target_bearing | No | Target bearing in degrees (0=N, 90=E, 180=S, 270=W) for a SOFT direction („Richtung Norden", „Richtung Stadt") instead of a stop name. The board keeps only departures whose course lies within `bearing_tolerance` of it. Mutually exclusive with `direction`. | |
| is_arrival_time | No | `true` reads `time` as an ARRIVAL time — the same as `arrival_departure = "arrivals"`. | |
| arrival_departure | No | `"arrivals"` (when vehicles reach `id`) or `"departures"` (default) — a third value is an argument error. Wins over `is_arrival_time` when both are set. | |
| bearing_tolerance | No | Angular tolerance in degrees for `target_bearing`. Default ±60°. | |
| time_range_seconds | No | Time WINDOW in seconds, starting at `time`. Together with `last_of_window` this answers „letzte Fahrt": pick it so the window ENDS after end of service (from the evening on, `28800` = 8 h rather than 4 h). Omit for a normal next-N lookup. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/open-world/non-destructive, and the description adds non-redundant behavior: an empty board is not a no-information answer, `modes` and `direction` are hard filters, an invalid mode or stop name is an argument error, and all journey facts must be cited only from this tool's output. This is exactly the anti-fabrication and error-semantics context an agent needs beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The text is dense but front-loaded, leading with the one-stop purpose before moving to alternatives and invocation rules. Bold key phrases and the final anti-fabrication rule earn their place; it is longer than a minimal description, but for a 15-parameter tool with several traps, the length is justified. A more scannable list structure would have pushed it to 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, it covers selection, required/optional parameter usage, error cases, empty-board behavior, and delegation to `get_usage_guide` for real-time/cancellation/citation fields. It stops short of self-contained output details (which are referred to the guide), so an agent without access to that guide would be missing some return-field semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already documents all 15 parameters, the description adds value by grouping them by intent: required resolved `id`, time/arrival switches, hard vs soft direction filters, the `time_range_seconds` + `last_of_window` combination for last-trip questions, and payload/verbosity controls for chat vs drawing applications. It also flags the mutual exclusion of `target_bearing` and `direction` and the tram/subway labeling trap.
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 names the operation precisely: departures or arrivals for a single stop, delivered as data for downstream processing. It also distances the tool from route planning by steering A→B questions to `connections`, and distinguishes it from the human-facing `show_departures` sibling, so 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 gives explicit when-to-use rules: single-stop departure questions come from this tool family, A→B questions from `connections`, and `show_departures` is the front end when present. It also mandates a pre-resolved stop `id`, names the `get_usage_guide` route for nuance, and tells the agent how to recover from an empty filtered board.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aktuelle Störungen, Baustellen und Liniensperrungen im ÖPNV. Für „gibt es Störungen", „Ausfälle in X" ist dieses Werkzeug die Auskunft, nicht das Allgemeinwissen. Datenlage — wichtig: Störungsmeldungen liegen derzeit für Niedersachsen, Bremen und Hamburg vor; außerhalb gibt es dafür KEINE Datengrundlage. (Verbindungen und Abfahrten sind davon nicht betroffen — die sind deutschlandweit.) Eine leere Antwort ist deshalb nur dann eine Entwarnung, wenn das Feld coverage sie als solche ausweist; außerhalb der abgedeckten Gebiete heißt sie, dass du es nicht weißt. Keine Pflicht-Args — ohne Filter kommen die aktiven Meldungen, gekappt auf limit. Optional: line (Liniennummer/-token, z.B. '6', 'U3') und stop (Haltestellen-Name) verknüpfen UND; area (Stadt/Gemeinde) bestimmt das coverage und sortiert die unverorteten Meldungen — es unterdrückt sie nicht: die kommen getrennt in unplaced zurück, auch ohne area. Nenne nur Filter, die der Nutzer wirklich nannte. Format: kompakter Einrück-Text (TOON), kein JSON; die Schreibweise steht in der Anleitung. Anleitung: get_usage_guide mit tool='disruptions' — die sechs coverage-Werte, die beiden Listen, die Felder einer Meldung und woran eine gekappte Antwort zu erkennen ist. Anti-Fab: nur zurückgegebene Meldungen nennen; eine Meldung ohne betroffene Linie und ohne betroffenen Halt ist eine allgemeine Störung und wird keiner Linie zugeschrieben, eine Meldung aus unplaced keinem Ort.
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | Area or city name (`"Hannover"`). Matches the municipality the affected stops lie in, and decides the `coverage` the answer reports. It never suppresses a report: the ones it cannot place come back in `unplaced`. | |
| line | No | Line token as printed on the vehicle (`"6"`, `"169"`, `"U3"`). A disruption is kept only if it names that line — under one of its `affected_lines` or one of its `affected_line_refs`. | |
| stop | No | Stop name (`"Kröpcke"`). Case-insensitive substring match against the disruption's `affected_stops`. | |
| limit | No | Maximum number of disruptions, at least 1. Default 5, values above 15 are served as 15. It shortens the answer, it does not choose better entries — an answer that had to leave something out says so (`truncated` + `total`). | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** | |
| include_unplaced | No | `false` leaves the `unplaced` list out of the answer (default `true`). It only shortens the answer — `coverage` still counts what was left out, so it never turns into an all-clear. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false; the description adds substantial context beyond that: the regional data-coverage limitation, the semantics of an empty answer (all-clear only if `coverage` says so, otherwise "du es nicht weißt"), truncation semantics (`limit` caps, `truncated` + `total` signals), and anti-fabrication rules (never attribute an unplaced report to a line/place). This is exactly the context annotations alone cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely structured with bold leads ("Datenlage — wichtig", "Keine Pflicht-Args", "Format", "Anleitung", "Anti-Fab"), and the most safety-critical caveat (data coverage) is front-loaded right after the purpose. Every sentence earns its place; the length is long but justified by the open-world and anti-fabrication stakes for a 6-param, 0-required 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 tool with openWorldHint=true, no output schema, and heavy inference risk, the description is complete: it covers purpose, data limits, filter semantics, output format (TOON, not JSON), a concrete pointer to the six coverage values via `get_usage_guide`, and truncation indicators. The one deferral to the usage guide is a legitimate division of labor rather than a 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% and the schema itself already documents all six parameters richly (e.g., `area` "never suppresses a report`). The description adds meaning beyond the schema by spelling out the AND-combination of `line` and `stop`, the `area`→`coverage` relationship, and the directive to pass only user-named filters — genuinely additive, just leaving the baseline 3 one notch higher.
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+resource: "Aktuelle Störungen, Baustellen und Liniensperrungen im ÖPNV" — a clear, specific queryable scope. It further distinguishes itself from siblings by stating it is the answer source for disruption queries "nicht das Allgemeinwissen" and by explicitly separating disruptions from connections/departures, which are "deutschlandweit" covered.
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 explicitly when to use it ("Für ‚gibt es Störungen"), gives an exclusion boundary (no data basis "außerhalb" Niedersachsen/Bremen/Hamburg), and routes alternatives ("Verbindungen und Abfahrten sind davon nicht betroffen"). It even specifies response interpretation rules conditioned on the `coverage` field, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Die ausführliche Anleitung zu den Werkzeugen dieses Katalogs: wofür ein Werkzeug da ist, wogegen es abzugrenzen ist, was seine Argumente bewirken, was zurückkommt und was daraus zitiert werden darf. Die description eines Werkzeugs ist die Kurzform, dieser Text die vollständige. Optional tool — der Name genau eines Werkzeugs, dessen Abschnitt du lesen willst; weggelassen kommt die ganze Anleitung. Lies den Abschnitt eines Werkzeugs, bevor du dessen Filter setzt oder ein leeres Ergebnis als Antwort weitergibst. Der Abruf ohne tool ist teuer: er bringt die Abschnitte ALLER Werkzeuge dieses Katalogs auf einmal, ein Vielfaches eines einzelnen. Setze tool, sobald feststeht, um welches Werkzeug es geht; ohne Argument nur für den Überblick über den ganzen Katalog.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | No | Der Name genau eines Werkzeugs aus diesem Katalog, dessen Abschnitt zurückkommen soll. Weglassen für die ganze Anleitung. |
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.
Linienverlauf: die Halte-Folge einer ÖPNV-LINIE und ihre gezeichnete Strecke für die Karte — „wo fährt die Y entlang", „welche X-Linien gibt es". Für Linien-Fragen: diese Auskunft, nicht das Allgemeinwissen. Pflicht ist EINES: query — Name/Nummer, wie ein Mensch sie schreibt ('Heide-Shuttle', 'HS 2'); ODER id aus einer früheren Antwort = GENAU EINE Linie. Sonst frag nach. Optional: area — der Ort, in dem die Linie fährt ('Hannover'; Dutzende Linien heißen '100'), limit (Default 8), render_payload, format. Die Antwort: je Fahrtrichtung ein Verlauf mit headsign, den halts als Namen und pathOnMap — der Strecke im Text, auf max. ~50 m vereinfacht; volle Auflösung: render_payload: true. Mehrdeutig: meint die Frage mehr Linien als eine Antwort ganz liest, kommt statt lines die Liste candidates (Nummer, Betreiber, Id) — ungezeichnet; dann den Ort erfragen oder mit id nachfassen. Grenzen: geometryDegraded: true heißt Luftlinien-Kette statt Straßenverlauf, note sagt es. Je Richtung EIN Fahrtmuster; ist patternsTotal größer, fährt sie üblicherweise so. matchedTotal über der Zahl der Linien heißt Ausschnitt. Unbekannter Ort: note sagt es, nichts wurde eingegrenzt. Nicht dafür: A→B (connections), Abfahrten (departures), Störungen (disruptions). Anleitung: get_usage_guide mit tool='line_course'. Anti-Fab: Linien, Halte, Reihenfolge, Strecke nur aus diesem Aufruf; findet sich keine, sag das.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | A line id out of an earlier answer (`"de:VBN-VH:6002:_3"`) — the one way to name exactly one line when a name means several. | |
| area | No | The town or city the line runs in (`"Hannover"`), where the user named one — the other way to make a line number mean ONE line. Beside `query`; no effect beside `id`, which already means one line. | |
| limit | No | Maximum number of lines, at least 1. Default 8, values above 15 are served as 15. Ignored beside `id`, which is one line. | |
| query | No | Line name or number, as written on the vehicle or in the timetable (`"Heide-Shuttle"`, `"HS 2"`, `"U3"`). Matched against the beginning of both, without case and without separators. | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** | |
| render_payload | No | `true` appends the whole answer again, addressed to the user rather than to the model: the halts with their coordinates, and every course's line at the resolution it was drawn at rather than the simplified `pathOnMap` the text carries. For an application that needs the exact line; a client that draws the answer's own `pathOnMap` leaves this off. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/openWorldHint/destructiveHint annotations, the description discloses rich behavior: simplified pathOnMap at ~50m, render_payload for full resolution, geometryDegraded meaning, patternsTotal semantics, matchedTotal indicating an excerpt, note for unknown areas, candidate list on ambiguity, and a strong anti-fabrication directive. This exceeds what annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but highly structured with bold labels (Pflicht, Optional, Die Antwort, Mehrdeutig, Grenzen, Nicht dafür, Anleitung, Anti-Fab) and front-loads the core purpose. Every section earns its place by covering a distinct operational aspect of a complex tool, and the density is justified by the absence of an output schema and the large sibling set.
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 six parameters, no output schema, and numerous sibling tools, the description is exceptionally complete: it covers required inputs, response shape, candidate handling, degraded geometry, limits, what the tool is not for, and anti-hallucination guidance. An agent has all the information needed to invoke it correctly and interpret 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?
Although schema coverage is 100%, the description adds substantial meaning: human-written query matching ('Heide-Shuttle', 'HS 2'), id from a previous answer being exactly one line, area disambiguating lines numbered '100', limit default 8 and capping at 15, and render_payload behavior. These details are not fully evident from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as the line course of an ÖPNV line (stops sequence and drawn route) and distinguishes it from sibling tools by naming alternatives: A→B connections, departures, disruptions. It even gives example questions ('wo fährt die Y entlang', 'welche X-Linien gibt es'), so an agent can recognize when to select it.
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 states that for line questions this tool should be used rather than general knowledge, and it names excluded cases: connections, departures, disruptions. The mandatory query-or-id requirement, fallback instruction to ask when ambiguous, and pointer to get_usage_guide provide clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Löst eine Zeit-Nennung in einen absoluten ISO-8601-Zeitpunkt auf — „morgen früh", „heute Abend um 18 Uhr", „in zwei Stunden", „um 8:30". Auch „jetzt"/„now"/„aktuell" wird aufgelöst: nutze das als kanonische Quelle für die aktuelle Zeit, statt dir selbst ein Datum auszudenken. Das Ergebnis (candidates[].datetime_range.start) geht direkt als connections.time bzw. departures.time weiter. Nennt der Nutzer bereits eine vollständige ISO-8601-Zeit mit Offset, ist kein Aufruf nötig. Pflicht: text — die Nennung, so wie der Nutzer sie schrieb. Optional: lang ('de' Default, 'en', 'fr') und tz (IANA-Name; ohne ihn wird die Lokalzeit als Europe/Berlin gelesen und als korrekter UTC-Instant zurückgegeben). Was zurückkommt: EIN Zeitpunkt, kein Fenster — start und end sind derselbe Instant. Eine nicht auflösbare Phrase liefert candidates: []; dann nachfragen, statt selbst zu rechnen. Anleitung: get_usage_guide mit tool='link_datetime' — insbesondere, auf welche Stunde eine vage Tageszeit fällt und was dann zu tun ist. Anti-Fab: Datum und Uhrzeit sind Fakten wie eine Liniennummer und stammen aus diesem Werkzeug — kein selbst-erfundenes Datum, keine eigene Datums-Arithmetik. Returns candidates[].datetime_range:{start,end}.
| Name | Required | Description | Default |
|---|---|---|---|
| tz | No | Optional IANA timezone the stated local time is interpreted in (default `Europe/Berlin`). DST-aware. Pass e.g. `"Europe/Berlin"`; omit for the default. Determines the UTC instant emitted for a wall-clock mention ("8:30" → `06:30Z` in summer). | |
| lang | No | Optional ISO language code (default `de`). Supported: `de`, `en`, `fr`. | |
| text | Yes | Free-text time mention to resolve via the rustling NLU. E.g. "morgen früh", "heute Abend um 18 Uhr", "in zwei Stunden". | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** |
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.
Findet Haltestellen, POIs und Adressen im Radius um eine KOORDINATE (Schwerpunkt Hannover/Niedersachsen) — „was ist in der Nähe von <lat,lon>", „welche Haltestellen liegen um diesen Punkt". Liegt nur ein Name vor, kommt erst eine Auflösung: search_place für eine Stadt oder Region, sonst die Ortsauflösung. Pflicht: latitude, longitude, radius_m. Optional: limit (Default 10); node_types — EIN String, mehrere Arten mit Komma: 'stop', 'address', 'poi', die Sharing-Angebote 'bike_rental', 'scooter_rental', 'car_sharing', 'taxi_stand', die Abstellanlagen 'park_and_ride', 'bike_and_ride', oder 'any' ('stop,bike_rental'); include_mots (legt die bedienenden Linien über die Haltestellen-Treffer); only_available (nur Sharing-Treffer mit gemeldetem freiem Fahrzeug — UNBEKANNTE Verfügbarkeit gilt nicht als frei). Format: kompakter Einrück-Text (TOON), kein JSON. Anleitung: get_usage_guide mit tool='nearby' — die Werte im Einzelnen, was 'any' nicht abdeckt, und was ein Treffer trägt (category, modality, parking, contactInfo). Anti-Fab: nur die zurückgegebenen Namen, Typen, Distanzen und Verfügbarkeiten nennen; fehlt ein Feld, war es in der Quelle nicht getaggt — Öffnungszeiten und Preise stehen hier NICHT.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results, at least 1. Default 10. | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** | |
| latitude | Yes | Latitude in WGS-84 decimal degrees. | |
| radius_m | Yes | Search radius in metres. | |
| longitude | Yes | Longitude in WGS-84 decimal degrees. | |
| node_types | No | Which kinds of place to answer with: the places the graph holds — `"stop"`, `"address"`, `"poi"` — plus the shared-mobility offers `"bike_rental"`, `"scooter_rental"`, `"car_sharing"` and `"taxi_stand"`, plus the places to leave a vehicle of one's own, `"park_and_ride"` and `"bike_and_ride"`, or `"any"` for all of them. Several combine in ONE comma-separated string — `"stop,bike_rental"`; an array of the same tokens is read as that string. A kind outside the ten is an argument error, not a dropped filter. `"poi"` alone also switches on the non-tourism filter; omit (or `"any"`) for the mixed default, in which each requested kind gets its share of `limit` and the shared-mobility offers share one between them. The two park-and-ride kinds are the exception `"any"` does NOT cover — ask for them by name, and with a `radius_m` of a few kilometres, because such sites are sparse. | |
| include_mots | No | `true` overlays the serving transit lines on stop results. Default `false`, which keeps the answer small. | |
| only_available | No | Set to `true` for „wo kann ich JETZT eines nehmen": of the shared-mobility offers, only those whose live feed reports at least one vehicle ready to be taken are answered with. A station whose availability is unknown is NOT returned then, and neither is a taxi rank, which has no feed to report one. Omit (or `false`) to list every place in range. The other kinds — `"stop"`, `"address"`, `"poi"`, `"park_and_ride"`, `"bike_and_ride"` — are unaffected either way. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and open-world, and the description adds important behavior beyond them: output is TOON text, not JSON; missing fields mean the source did not tag them; opening hours and prices are not present; unknown availability is not treated as free for `only_available`. This gives the agent a realistic model of what the tool can and cannot return.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The text is long but well-structured: bold labels break it into purpose, required/optional parameters, format, further guidance, and anti-fabrication rules. The core purpose is front-loaded, and while some details are dense, each sentence carries practical information. It is comprehensive rather than wasteful.
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 naming the return format (`TOON`), the kinds of fields a hit carries (`category`, `modality`, `parking`, `contactInfo`), and the data limitations. It covers defaults, edge cases, exclusions, and how to get more detail. For a complex eight-parameter tool, 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?
Although the schema already documents every parameter, the description adds valuable semantics: `node_types` is one comma-separated string rather than an array, `'any'` does not cover park-and-ride kinds, `'poi'` alone activates a special filter, and shared-mobility offers split the limit. These operational details go well beyond the schema text and materially affect how the agent should construct calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb and resource: finding stops, POIs, and addresses within a radius around a coordinate, with a clear geographic focus. It also distinguishes itself from name-based search by explicitly routing those cases to `search_place`, so an agent can tell it apart from siblings 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?
It clearly states when to use this tool (a coordinate is present) and that name-only queries should first go through `search_place`. It also points to `get_usage_guide` for finer details and flags the `'any'` exception for park-and-ride kinds. It does not explicitly mention other siblings like `reverse_geocode`, but the coordinate-vs-name distinction is sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Löst Freitext in die Id auf, mit der gefahren wird — die Haltestelle, die Adresse oder den POI hinter „von nach ", „erzähl mir was über ". Wo Routing, Abfahrtstafel oder POI-Steckbrief eine Id brauchen, steht es davor — auch wenn der Nutzer die Stadt dazu nennt („Hauptbahnhof Hannover"). Ein GEBIET (Stadt/Region) verortet search_place. Pflicht: query — nur der Name: 'Kelsterbach Bahnhof', NICHT 'für Kelsterbach Bahnhof'. Wegzulassen sind für, vom, von, nach, bis; ein führendes am/an/in/zur/auf bleibt stehen — so heißen echte Halte („Am Wehrhahn"). Optional: lat/lon (Ranking-Bias), limit, node_types ('stop'/'address'/'poi'/'any', mehrere mit Komma in EINEM String; eine andere Art ist ein Argument-Fehler), city_station (Query = ganze Stadt → deren (Haupt-)Bahnhof). Art-Wort in node_types, nicht in den Namen: „Haltestelle X" → 'stop', „Adresse X" → 'address', „POI X"/„Sehenswürdigkeit X" → 'poi', query je ohne das Wort. A→B: zweimal rufen — Start, Ziel. Jeder Treffer trägt type und location; NUR ein stop hat eine fahrbare DH-Id, nie eine erfinden. Anleitung: get_usage_guide — Abgrenzung, Argumente, Rangfolge. Anti-Fab: nur die Treffer aus dem Output dieses Aufrufs verwenden.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Optional latitude (WGS-84) to bias ranking toward nearby stops. | |
| lon | No | Optional longitude (WGS-84) to bias ranking toward nearby stops. | |
| limit | No | Maximum number of results. Defaults to 5 if omitted. | |
| query | Yes | Free-text query, e.g. "Hauptbahnhof Hannover" or "Linden Markt". Nur der reine Orts-/Haltename — ohne das Wort, das ihn im Satz ankündigt: `"Kelsterbach Bahnhof"`, nicht `"für Kelsterbach Bahnhof"`. Ein führendes `am`/`an`/`in`/`zur`/`auf` bleibt dagegen stehen, weil echte Haltestellen so heißen ("Am Wehrhahn", "In der Au"). | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** | |
| node_types | No | Which kinds of place to resolve to: `"stop"`, `"address"`, `"poi"` or `"any"`. Several combine in ONE comma-separated string — `"stop,poi"`; an array of the same tokens is read as that string. A kind outside the four is an argument error, not a dropped filter — the shared-mobility kinds among them: a rental station and a taxi rank are not in the place index this searches, they are answered by the radius search `nearby`. Forwarded to mobility-middleware as `journey_node_types`. `"poi"` alone additionally drops non-tourism POI names (Kindergarten, Apotheke, Schule, …) — use this for tourism queries. Nennt der Nutzer die Art selbst, gehört sie hierher statt in `query`: "Haltestelle X" → `"stop"`, "Adresse X" → `"address"`, "POI X"/"Sehenswürdigkeit X" → `"poi"` (und `query` dann ohne das Art-Wort). | |
| city_station | No | When `Some(true)` AND the query is a whole CITY, resolve it to the city's (Haupt-)Bahnhof stop and return ONLY that stop (so „von Hannover nach Celle" routes Bahnhof→Bahnhof). Forwarded to mobility-middleware as `cityStation=true`. A no-op for non-city queries. The orchestrator routing-floor sets this deterministically per endpoint; the model never has to. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/destructive annotations, the description discloses normalization rules (omit für/von/nach, keep leading am/an/in), argument-error behavior for invalid node_types, the fact that only a `stop` yields a usable routing ID, and an explicit anti-fabrication rule ('nie eine erfinden'). No statement 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 text is dense but organized with bold semantic chunks (Pflicht, Optional, Art-Wort, A→B, Anti-Fab) and front-loads the core purpose before details. Every sentence carries a distinct rule or pointer, so the length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter resolver with no output schema, the description covers the call intent, all relevant parameter semantics, the two-call A→B pattern, result shape (type and location, stop-only ID), and anti-hallucination guidance. It even routes to `get_usage_guide` for remaining depth.
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%, and the description still adds substantial meaning: `lat`/`lon` are ranking bias, `node_types` combinability and error behavior, `city_station` city→main-station behavior, and the rule to move the user's type word out of `query` into `node_types`. This goes well beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a precise verb and resource: it resolves free text ('Löst Freitext') into an ID for stops, addresses, or POIs, and situates itself in concrete flows (routing, departure board, POI profile). It also differentiates itself from the sibling `search_place` by explicitly assigning areas (Stadt/Region) to that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when to call it ('Wo Routing, Abfahrtstafel oder POI-Steckbrief eine Id brauchen, steht es davor') and gives an explicit alternative: areas go to `search_place`. It also includes actionable call patterns (A→B call twice), prerequisites for `city_station`, and points to `get_usage_guide` for further delimitation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Benennt, was an einer KOORDINATE liegt — der Ort („was liegt bei <lat,lon>"), mit level eine bestimmte Ebene davon, mit level='street' die Straße samt nächster Hausnummer (der Lookup für eine GPS-Startposition). Abgrenzung: den Weg zurück (Name → Koordinate und OSM-Ids) geht search_place, die fahrbare Halte-Id liefert die Ortsauflösung, und nearby listet auf, was UM eine Koordinate liegt, statt den Punkt selbst zu benennen. Pflicht: lat und lon — geschrieben auch latitude/longitude, so wie nearby die Koordinate nimmt; je Aufruf nur eine der beiden Schreibweisen. Optional: radius_m (Suchradius in METERN; ein Ort, IN dem die Koordinate liegt, hat Abstand 0 und ist in jedem noch so engen Radius dabei — ohne radius_m die nächstgelegenen Treffer), limit (Höchstzahl Treffer, Default 10, Maximum 50) und level — 'place' (Default: die ganze Ortshierarchie, feinste Ebene zuerst), 'city' (die Stadt/Gemeinde), 'suburb' (der Stadtteil) oder 'street'. Kennt der Datensatz die gewünschte Ebene hier nicht, antwortet die nächst-gröbere, erkennbar am place_type; ein unbekannter Wert wirkt wie 'place'. Anleitung: get_usage_guide mit tool='reverse_geocode'. Anti-Fab: nur die zurückgegebenen Orts- und Straßen-Namen verwenden, einschließlich der Hausnummer aus dem Datensatz — nie eine erfinden.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude of the coordinate to reverse-geocode. Also accepted spelled `latitude`, the way the vicinity search takes it — one of the two spellings per call. | |
| lon | Yes | Longitude of the coordinate to reverse-geocode. Also accepted spelled `longitude`, the way the vicinity search takes it — one of the two spellings per call. | |
| level | No | Optional resolution level. `"place"` (default) answers with the coordinate's whole admin hierarchy, finest first (suburb → town → county → state → country); `"city"` with the town/municipality it lies in; `"suburb"` with the suburb; `"street"` with the nearest STREET/ADDRESS (street name + nearest house number, e.g. `"Münzstraße 3-4"`) — the level needed to label a real GPS start position. Where the data has no place at the requested level, the next coarser one answers, recognisable by its `place_type`. Any other / omitted value behaves as `"place"`. | |
| limit | No | Optional maximum number of hits, nearest first. Default 10, upper bound 50; a larger value is served as 50 and `0` as the default. Applies to every level and with or without `radius_m`. | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** | |
| radius_m | No | Optional radius in METRES. When set, returns the places inside the circle, sorted nearest-first and capped to `limit`. A place the coordinate LIES INSIDE is at distance 0 and is therefore in every radius, however tight. When omitted, returns the `limit` nearest places. |
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.
Löst den NAMEN einer Stadt, Region oder eines Bezirks in Koordinaten und OSM-Ids auf — der erste Schritt, wenn ein GEBIET verortet werden muss („was kann ich in unternehmen", „wie ist das Wetter in "). Für eine HALTESTELLE ist dieses Werkzeug fast immer falsch: es kennt Gebiete, keine Bahnsteige — auf einen Bahnhofs-Namen antwortet es mit dem Stadtteil, und die Id, die es liefert, ist eine OSM-Id und keine fahrbare Halte-Id. Trägt die Anfrage Bahnhof, Hauptbahnhof, Hbf oder Bf, gehört sie an die Ortsauflösung — „Köln Hauptbahnhof" und „Hannover Bahnhof" also dorthin, nicht hierher: auf das erste antwortet dieses Werkzeug mit einem gleichnamigen Ortsteil (einem in Potsdam), auf das zweite mit der Stadt Hannover. Dasselbe für Adresse und POI — alles, was Start, Ziel oder Abfahrtsort einer Fahrt sein kann; eine Stadt als Fahrt-Endpunkt („von Hannover nach Celle") ebenfalls. Von einer Koordinate zurück zum Namen geht reverse_geocode, die Umgebung einer Koordinate listet nearby. Pflicht: name. Optional: lang — wird für Symmetrie mit den übrigen Geo-Werkzeugen angenommen, derzeit aber nicht ans Backend durchgereicht und ändert das Ergebnis nicht. Anleitung: get_usage_guide mit tool='search_place' — die Abgrenzung im Detail, die typischen Ketten und der Umgang mit einem mehrdeutigen Namen. Anti-Fab: nur die zurückgegebenen Namen und Ids nutzen, keine Bauch-Geographie.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Optional ISO language code (e.g. "de", "en"). Currently advisory: the place names are the German ones the data carries, whatever is asked for. Kept in the signature so a multilingual answer needs no new argument. | |
| name | Yes | Name of the place to search for. Free-text fuzzy match against the place index behind this endpoint (e.g. "Hannover", "Maschsee", "Wangerland"). | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only, open-world, and non-destructive. The description adds substantial behavior beyond that: it returns OSM IDs rather than stop IDs, mis-resolves station names to districts or cities, ignores the lang parameter, and warns against geographic hallucination. 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 long, but well structured with bold markers, concrete examples, and a clear lead sentence. It earns its length by resolving high-stakes sibling ambiguity, though a few examples could be trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description tells the agent what comes back (coordinates and OSM IDs), what failure modes look like, how to route non-matching cases, and where to find deeper guidance via get_usage_guide. Nothing needed 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%, so the baseline is 3. The description restates that name is required and that lang is optional and ignored, but the schema already documents these properties in similar detail. The format parameter is not mentioned in the description, but it is adequately covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact operation in the first sentence: resolving a city, region, or district name into coordinates and OSM IDs, and frames it as the first step for locating an area. It then explicitly excludes stops, addresses, and POIs, so an agent can distinguish it from sibling geolocation tools without inspecting their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance with concrete query examples, and clearly says when not to use it: stop names containing Bahnhof/Hbf/Bf belong to the Ortsauflösung, and addresses/POIs/trip endpoints are also excluded. It names concrete alternatives: reverse_geocode for coordinate-to-name and nearby for listing surroundings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Der Vordereingang für jede Verbindungsfrage eines Menschen, auch wenn er nur nach Zeiten fragt: plant die Fahrt wie connections und liefert sie zusätzlich als Ansicht aus, die ein Wirt mit Ansichten dem Nutzer zeigt — je Verbindung eine Karte mit Zeiten, Dauer, Umstiegen und Echtzeit-Lage. Beantwortest du einem Menschen eine Verbindungsfrage, ruf dies statt connections, das für Ergebnisse ist, die du weiterverarbeitest. Pflicht sind BEIDE Endpunkte, wie dort: origin_id UND destination_id — oder die vier Koordinaten-Felder; render_payload entfällt. Der Antwort-Text ist der von connections; die Rohdaten daneben tragen nur die Felder, die die Ansicht zeichnet, ihr Kartenverlauf davon im _meta. Anleitung: get_usage_guide mit tool='connections'. Anti-Fab: Linien, Zeiten, Halte und Gleise ausschließlich aus dem Output dieses Aufrufs.
| Name | Required | Description | Default |
|---|---|---|---|
| time | No | ISO 8601 timestamp (e.g. `"2026-06-15T08:30:00Z"`). Omit to plan from now. Resolve a spoken time with the time tool rather than computing one. | |
| limit | No | Maximum number of journeys, at least 1. Default 5, values above 15 are served as 15. | |
| modes | No | Transport-mode restriction, not a preference: nothing outside the list is planned. The footpath always stays allowed — the way to, from and between stops goes on foot — while `["foot"]` on its own plans no ride at all. Entries: `"bike"`, `"bike_rental"`, `"foot"`, `"car"`, `"taxi"`, `"scooter"`, `"transit"`, `"bus"`, `"tram"`, `"rail"`, `"subway"`, `"ferry"`; several combine. An entry outside that list is an argument error, not a dropped filter. Omitted or empty = all standard transit modes, the ferry included. Set only when the user insists on a mode; the guide has the vocabulary and the traps. | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** | |
| via_id | No | Intermediate stop the route must pass through („über X"), as an id in the same form as `origin_id`. The route is then planned A → via → B. | |
| via_lat | No | Via latitude, for an intermediate address or POI without an id. Goes with `via_lon`. | |
| via_lon | No | Via longitude. Goes with `via_lat`. | |
| extended | No | `true` keeps the map data in the text: every stop's coordinate, every leg's polyline, and the whole stop sequence with them — for an application that DRAWS the route, at two to three times the answer. A chat client leaves it off. | |
| via_type | No | What `via_id` is. Same values as `origin_type`. | |
| origin_id | No | Origin id. A DHID (`de:NNNNN:NNN`) for a stop, otherwise the resolver's `main` id of the address or POI. Resolve the place first — a name here is an argument error. | |
| verbosity | No | How much of each journey comes back: `"compact"` (default — everything an answer is cited from) or `"full"` (adds the stops in between). A third word is an argument error, not the default. | |
| only_lines | No | Line whitelist. Entries are line tokens as printed on the vehicle (`"6"`, `"U3"`); a journey is kept only if every transit leg uses one of them. | |
| origin_lat | No | Origin latitude, WGS-84 decimal degrees — the fallback when no id is at hand, and the one retry worth making when resolved ids find nothing. | |
| origin_lon | No | Origin longitude. Goes with `origin_lat`. | |
| walk_speed | No | Walking speed of the foot legs in metres/second, between 0.3 and 3 m/s — outside that it is an argument error. Default ≈1.33, slow ≈0.7, brisk ≈2.0. Overrides the walk speed of `accessibility_profile`. | |
| origin_type | No | What `origin_id` is: `"stop"` (default), `"address"` or `"poi"`. A stop id is auto-prefixed `GTFS.de:`; the other two are forwarded verbatim so the backend resolves the real name. | |
| prefer_flat | No | `true` plant die hügel-ärmste statt der sonst gewählten Rad-Route: die Suche gewichtet die Steigung und nimmt dafür Umwege in Kauf, nur auf Rad-Abschnitten. Keine Zusage — ohne flachere Alternative kommt dieselbe Route; die Höhenmeter der Antwort sagen es. Wann setzen: die Anleitung. | |
| cycling_speed | No | Rad-Tempo in Metern/Sekunde, 1 bis 12 — außerhalb ein Argument-Fehler. Überschreibt `cycling_profile`. Richtwerte: Familie ≈2.8, normal ≈5, Pedelec ≈6.5. | |
| exclude_lines | No | Line blacklist, same token form as `only_lines`. A journey is dropped if any transit leg uses one of them. | |
| max_transfers | No | Upper bound on interchanges: `0` = direct, up to `3`. Omit unless the user constrains transfers: the backend then derives the search depth from the trip's air-line distance and escalates it when the first attempt finds nothing, so omitting never loses a connection. | |
| submodes_deny | No | Fine submode blacklist, same vocabulary as `submodes_allow`. A journey is dropped if any transit leg matches one. | |
| destination_id | No | Destination id. Same form as `origin_id`. | |
| submodes_allow | No | Fine submode whitelist — finer than `modes`, which only separates bus/tram/rail/subway. Entries: `"sbahn"`, `"regionalbahn"`, `"ice"`, `"ic"`, `"ir"`, `"nj"`, `"fernverkehr"`, `"stadtbahn"`, `"ubahn"`, `"bus"`, `"regionalbus"`, `"stadtbus"`. A journey is kept only if every transit leg matches one. | |
| cycling_profile | No | Wer auf dem Rad sitzt, und damit das Tempo der Rad-Abschnitte: `family` (mit kleinen Kindern), `normal` (Default, unverändert) oder `ebike` (Pedelec). Ein anderer Name ist ein Argument-Fehler. | |
| destination_lat | No | Destination latitude. Same use as `origin_lat`. | |
| destination_lon | No | Destination longitude. Goes with `destination_lat`. | |
| is_arrival_time | No | `true` reads `time` as the desired ARRIVAL time instead of the departure time. | |
| max_walk_meters | No | Cap on the summed walking DISTANCE in metres. Works like `max_walk_minutes`, on the metres walked. | |
| destination_type | No | What `destination_id` is. Same values as `origin_type`. | |
| max_walk_minutes | No | Cap on the summed walking TIME in minutes. A post-filter drops journeys above it; if that leaves nothing, the backend searches once more avoiding footpaths before the answer is empty. | |
| mobility_profile | No | How the first and the last mile may be covered, by name: `"transit"` (default — both ends on foot), `"transit_plus_sharing"` (a shared bike), `"door_to_door"` (being driven), `"park_and_ride"` or `"bike_and_ride"` (one's OWN car or bicycle, left where the transit leg starts). Another name is an argument error. It widens those two ends, restricts no ride and promises nothing. When to set which, and how it composes with `modes`, is in the usage guide. | |
| include_rental_bike | No | `true` adds a rental-bike leg (park-and-bike / station rental). Equivalent to naming `"bike"` in `modes` together with a transit mode. | |
| accessibility_profile | No | Mobility profile by name: `"Standard"` (default), `"WheelchairRobust"`, `"WalkerComfort"` or `"IndividualComfort"`. Each bundles its accessibility constraints and walk speed; another name is an argument error. The two wheelchair profiles find no ride at all today — the answer then carries `accessibility_routing` with `status: no_data` beside ordinary connections, which are to be reported as ordinary ones. What each profile constrains is in the usage guide. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safe read-only profile (readOnlyHint=true, destructiveHint=false), and the description adds real behavioral detail: the response text matches `connections`, the raw data carries only view-drawing fields, and the map route is placed in `_meta`. It omits any discussion of error or empty-result behavior, but no output schema exists and the core non-obvious behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact despite the tool's 33-parameter surface: four bolded sentences covering purpose, routing, required endpoints, output shape, guide pointer, and anti-hallucination rule. It is front-loaded with the core decision and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no output schema, the description gives enough orientation: it explains what the rendered result contains, what the response text is, which endpoint pair is mandatory, and directs to `get_usage_guide` for parameter-level traps. It could be slightly more explicit about how `show_connections_slim` fits in, but that gap is covered by the usage guide link.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful constraint beyond the schema: both `origin_id` and `destination_id` are required together, or alternatively all four coordinate fields, and `render_payload` is not to be passed. This is especially valuable because the schema lists no required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: it is the front door for every human-facing connection question, plans like `connections`, and adds a rendered view with cards showing times, duration, transfers and real-time position. It also explicitly contrasts itself with `connections` (result for further processing), so it is immediately distinguishable from the closest sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit when-to-use rule: answer a human connection question by calling this instead of `connections`, which is for machine-processing. It also states the mandatory origin/destination endpoints or coordinate fields and points to `get_usage_guide` with `tool='connections'` for full instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dieselbe Verbindungs-Ansicht wie show_connections, nur schlank ausgeliefert: das Kartenwerk lädt die Ansicht als Skript, statt es mitzubringen. Nimm dies nur, wenn ausdrücklich nach der schlanken Auslieferung gefragt wird — sonst show_connections. Sonst unverändert: plant die Fahrt wie connections und liefert sie zusätzlich als Ansicht aus. Pflicht sind BEIDE Endpunkte, wie dort: origin_id UND destination_id — oder die vier Koordinaten-Felder; render_payload entfällt. Der Antwort-Text ist der von connections; die Rohdaten daneben tragen nur die Felder, die die Ansicht zeichnet, ihr Kartenverlauf davon im _meta. Anleitung: get_usage_guide mit tool='connections'. Anti-Fab: Linien, Zeiten, Halte und Gleise ausschließlich aus dem Output dieses Aufrufs.
| Name | Required | Description | Default |
|---|---|---|---|
| time | No | ISO 8601 timestamp (e.g. `"2026-06-15T08:30:00Z"`). Omit to plan from now. Resolve a spoken time with the time tool rather than computing one. | |
| limit | No | Maximum number of journeys, at least 1. Default 5, values above 15 are served as 15. | |
| modes | No | Transport-mode restriction, not a preference: nothing outside the list is planned. The footpath always stays allowed — the way to, from and between stops goes on foot — while `["foot"]` on its own plans no ride at all. Entries: `"bike"`, `"bike_rental"`, `"foot"`, `"car"`, `"taxi"`, `"scooter"`, `"transit"`, `"bus"`, `"tram"`, `"rail"`, `"subway"`, `"ferry"`; several combine. An entry outside that list is an argument error, not a dropped filter. Omitted or empty = all standard transit modes, the ferry included. Set only when the user insists on a mode; the guide has the vocabulary and the traps. | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** | |
| via_id | No | Intermediate stop the route must pass through („über X"), as an id in the same form as `origin_id`. The route is then planned A → via → B. | |
| via_lat | No | Via latitude, for an intermediate address or POI without an id. Goes with `via_lon`. | |
| via_lon | No | Via longitude. Goes with `via_lat`. | |
| extended | No | `true` keeps the map data in the text: every stop's coordinate, every leg's polyline, and the whole stop sequence with them — for an application that DRAWS the route, at two to three times the answer. A chat client leaves it off. | |
| via_type | No | What `via_id` is. Same values as `origin_type`. | |
| origin_id | No | Origin id. A DHID (`de:NNNNN:NNN`) for a stop, otherwise the resolver's `main` id of the address or POI. Resolve the place first — a name here is an argument error. | |
| verbosity | No | How much of each journey comes back: `"compact"` (default — everything an answer is cited from) or `"full"` (adds the stops in between). A third word is an argument error, not the default. | |
| only_lines | No | Line whitelist. Entries are line tokens as printed on the vehicle (`"6"`, `"U3"`); a journey is kept only if every transit leg uses one of them. | |
| origin_lat | No | Origin latitude, WGS-84 decimal degrees — the fallback when no id is at hand, and the one retry worth making when resolved ids find nothing. | |
| origin_lon | No | Origin longitude. Goes with `origin_lat`. | |
| walk_speed | No | Walking speed of the foot legs in metres/second, between 0.3 and 3 m/s — outside that it is an argument error. Default ≈1.33, slow ≈0.7, brisk ≈2.0. Overrides the walk speed of `accessibility_profile`. | |
| origin_type | No | What `origin_id` is: `"stop"` (default), `"address"` or `"poi"`. A stop id is auto-prefixed `GTFS.de:`; the other two are forwarded verbatim so the backend resolves the real name. | |
| prefer_flat | No | `true` plant die hügel-ärmste statt der sonst gewählten Rad-Route: die Suche gewichtet die Steigung und nimmt dafür Umwege in Kauf, nur auf Rad-Abschnitten. Keine Zusage — ohne flachere Alternative kommt dieselbe Route; die Höhenmeter der Antwort sagen es. Wann setzen: die Anleitung. | |
| cycling_speed | No | Rad-Tempo in Metern/Sekunde, 1 bis 12 — außerhalb ein Argument-Fehler. Überschreibt `cycling_profile`. Richtwerte: Familie ≈2.8, normal ≈5, Pedelec ≈6.5. | |
| exclude_lines | No | Line blacklist, same token form as `only_lines`. A journey is dropped if any transit leg uses one of them. | |
| max_transfers | No | Upper bound on interchanges: `0` = direct, up to `3`. Omit unless the user constrains transfers: the backend then derives the search depth from the trip's air-line distance and escalates it when the first attempt finds nothing, so omitting never loses a connection. | |
| submodes_deny | No | Fine submode blacklist, same vocabulary as `submodes_allow`. A journey is dropped if any transit leg matches one. | |
| destination_id | No | Destination id. Same form as `origin_id`. | |
| submodes_allow | No | Fine submode whitelist — finer than `modes`, which only separates bus/tram/rail/subway. Entries: `"sbahn"`, `"regionalbahn"`, `"ice"`, `"ic"`, `"ir"`, `"nj"`, `"fernverkehr"`, `"stadtbahn"`, `"ubahn"`, `"bus"`, `"regionalbus"`, `"stadtbus"`. A journey is kept only if every transit leg matches one. | |
| cycling_profile | No | Wer auf dem Rad sitzt, und damit das Tempo der Rad-Abschnitte: `family` (mit kleinen Kindern), `normal` (Default, unverändert) oder `ebike` (Pedelec). Ein anderer Name ist ein Argument-Fehler. | |
| destination_lat | No | Destination latitude. Same use as `origin_lat`. | |
| destination_lon | No | Destination longitude. Goes with `destination_lat`. | |
| is_arrival_time | No | `true` reads `time` as the desired ARRIVAL time instead of the departure time. | |
| max_walk_meters | No | Cap on the summed walking DISTANCE in metres. Works like `max_walk_minutes`, on the metres walked. | |
| destination_type | No | What `destination_id` is. Same values as `origin_type`. | |
| max_walk_minutes | No | Cap on the summed walking TIME in minutes. A post-filter drops journeys above it; if that leaves nothing, the backend searches once more avoiding footpaths before the answer is empty. | |
| mobility_profile | No | How the first and the last mile may be covered, by name: `"transit"` (default — both ends on foot), `"transit_plus_sharing"` (a shared bike), `"door_to_door"` (being driven), `"park_and_ride"` or `"bike_and_ride"` (one's OWN car or bicycle, left where the transit leg starts). Another name is an argument error. It widens those two ends, restricts no ride and promises nothing. When to set which, and how it composes with `modes`, is in the usage guide. | |
| include_rental_bike | No | `true` adds a rental-bike leg (park-and-bike / station rental). Equivalent to naming `"bike"` in `modes` together with a transit mode. | |
| accessibility_profile | No | Mobility profile by name: `"Standard"` (default), `"WheelchairRobust"`, `"WalkerComfort"` or `"IndividualComfort"`. Each bundles its accessibility constraints and walk speed; another name is an argument error. The two wheelchair profiles find no ride at all today — the answer then carries `accessibility_routing` with `status: no_data` beside ordinary connections, which are to be reported as ordinary ones. What each profile constrains is in the usage guide. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: both endpoints are mandatory, render_payload is omitted, the answer text is the same as connections, the raw data contains only view-drawn fields, and the map trace lives in _meta. It even warns against fabrication by insisting all lines, times, stops, and tracks come solely from this call's output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well structured, with bolded key phrases and a logical flow: what it is, when to use it, what is required, what the output contains, and where to get more guidance. Every sentence earns its place, though the many clauses bundled into single sentences make it slightly harder to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 33-parameter tool with no output schema, the description covers the critical operational needs: when to choose it, which endpoint/coordinate combinations are mandatory, what is dropped, what the response shape is (same text as connections, reduced raw data, _meta trace), and where to find the usage guide. It is highly adequate, though a concrete example or a pointer to the exact output schema of connections would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are already well documented. The description adds real value beyond the schema by specifying the required pairing — origin_id AND destination_id, or the four coordinate fields — and by noting that render_payload is not applicable here. This clarifies an important constraint the schema itself does not express.
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 the specific resource (the connections view) and the verb/action (display it in slim-delivery form), and immediately contrasts it with show_connections: same view, only delivered as a script-loaded map. It also ties the function to connections by stating it plans the trip like connections and additionally outputs it as a view, so an agent can tell it apart from both 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 is explicit: use this tool only when the slim delivery is explicitly requested, otherwise use show_connections. It also points the agent to get_usage_guide with tool='connections' for the relevant instructions, giving clear and actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Der Vordereingang für jede Abfahrtsfrage eines Menschen: liest die Tafel einer Haltestelle wie departures und liefert sie zusätzlich als Ansicht aus, die ein Wirt mit Ansichten dem Nutzer zeigt — je Abfahrt Linie, Ziel, Gleis/Steig, Zeit und Echtzeit-Lage. Beantwortest du einem Menschen eine Abfahrtsfrage, ruf dies statt departures, das für Ergebnisse ist, die du weiterverarbeitest. Pflicht ist die Halte-Id, wie dort: id — eine Id aus resolve_location, kein Haltestellen-Name; render_payload entfällt. Der Antwort-Text ist der von departures; die Rohdaten daneben tragen nur die Felder, die die Ansicht zeichnet. Anleitung: get_usage_guide mit tool='departures'. Anti-Fab: Linien, Ziele, Zeiten und Gleise ausschließlich aus dem Output dieses Aufrufs.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Stop id to read the board of, as a DHID (`"de:03241:57"`). Resolve the stop first — a name here is an argument error. | |
| time | No | ISO 8601 timestamp (e.g. `"2026-06-15T08:30:00Z"`). Omit for now. Resolve a spoken time with the time tool rather than computing one. | |
| limit | No | Maximum number of departures, at least 1. Default 5, values above 15 are served as 15. | |
| modes | No | Transport-mode filter; the board then shows nothing else. Entries: `"bus"`, `"tram"`, `"subway"`, `"train"`/`"rail"`, `"ferry"`, `"transit"`; several combine. Another entry — a street mode, a misspelling — is an argument error, not a dropped filter: a board lists scheduled services. Omitted or empty = all modes. A Stadtbahn or light-rail mention needs BOTH labels — `["tram","subway"]`: which of the two such a network carries depends on the dataset rather than on the vehicle. Set the filter only when the user really asks for a vehicle type; the guide has the rest of the vocabulary and the traps. | |
| format | No | Answer serialisation: `"toon"` (default) or `"json"` — the detail is in `get_usage_guide`. **An agent leaves this out.** | |
| extended | No | `true` keeps the map data in the text: every stop's coordinate, the whole course of each run, and a polyline where the board carries one — for an application that DRAWS the board. It multiplies the answer. A chat client leaves it off. | |
| direction | No | Name of a stop the user wants to head TOWARD („Richtung Wettbergen") — not a routing destination. The board keeps only departures heading that way, whether the named stop is the terminus or a stop downstream of the queried one. Matching is case-insensitive and area-prefix-tolerant. | |
| verbosity | No | How much of each departure comes back: `"compact"` (default — everything an answer is cited from) or `"full"` (adds the onward stops of the run, and with them the per-stop cancellation marker). A third word is an argument error, not the default. | |
| last_of_window | No | Which end of a `time_range_seconds` window to read: omitted or `false` the FIRST departures, `true` the LAST ones (the end-of-service question). An answer carrying `window_truncated: true` beside its board did NOT reach the window's end — its last entry is then not the last departure. Without a window it has no effect. | |
| target_bearing | No | Target bearing in degrees (0=N, 90=E, 180=S, 270=W) for a SOFT direction („Richtung Norden", „Richtung Stadt") instead of a stop name. The board keeps only departures whose course lies within `bearing_tolerance` of it. Mutually exclusive with `direction`. | |
| is_arrival_time | No | `true` reads `time` as an ARRIVAL time — the same as `arrival_departure = "arrivals"`. | |
| arrival_departure | No | `"arrivals"` (when vehicles reach `id`) or `"departures"` (default) — a third value is an argument error. Wins over `is_arrival_time` when both are set. | |
| bearing_tolerance | No | Angular tolerance in degrees for `target_bearing`. Default ±60°. | |
| time_range_seconds | No | Time WINDOW in seconds, starting at `time`. Together with `last_of_window` this answers „letzte Fahrt": pick it so the window ENDS after end of service (from the evening on, `28800` = 8 h rather than 4 h). Omit for a normal next-N lookup. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only and non-destructive, and the description adds meaningful behavioral detail on top: the answer text is identical to `departures`, while the raw data carry only the fields the view draws. It also adds an explicit anti-fabrication instruction to source line, destination, time, and track information exclusively from the call output. No contradiction with the 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 front-loaded with purpose and usage and uses bold labels to separate scope, required input, instructions, and the anti-fabrication rule. It is somewhat dense, and the 'Wirt mit Ansichten' metaphor may be slightly confusing, but for a 14-parameter tool each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 14 parameters and no output schema, the description supplies the essential missing context: when to choose it over `departures`, required id provenance, the return shape (same answer text as `departures`, raw data limited to view-drawn fields), and where to find more details. The schema covers the parameters, while the description covers selection and output behavior, making it sufficiently 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% and the input schema thoroughly documents all 14 parameters, so the baseline is 3. The description reinforces the critical required `id` semantics (`id` from `resolve_location`, not a stop name) and notes that `render_payload` is absent, but it adds little beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens by identifying the tool as the 'front entrance' for human departure questions and states it reads a stop's board like `departures` and renders it as a view, listing line, destination, platform, time, and real-time status. It explicitly distinguishes itself from the sibling `departures`: call this when answering a human, not when processing results. That is a specific verb plus resource with clear sibling differentiation.
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 'Beantwortest du einem Menschen eine Abfahrtsfrage, ruf dies statt departures' and clarifies that `departures` is for results you process further. It also states that the required stop id must come from `resolve_location`, not a stop name, and points to `get_usage_guide` with `tool='departures'`. This gives concrete when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
connectionsdeparturesdisruptionsget_usage_guideline_courselink_datetimenearbyresolve_locationreverse_geocodesearch_placeshow_connectionsshow_connections_slimshow_departuresDB Rail MCP — German + European rail and public transport, keyless.
Plan journeys by train, bus, tram, metro and ferry across 42 European countries.
Sights, events, opening hours, weather and tides; nearby sharing as currently reported.
Live prices, deals & optimal multi-stop shopping routes for German grocery & drug stores.
Add one secure layer between your agents and this server.
