Germany's open mobility data: Autobahn traffic, DB trains, local transit, fuel, EV charging, parking and DWD warnings.
Scored across 22 tools
Descriptions aggressively delineate boundaries with explicit 'Do NOT use for X — call Y' cross-references, e.g. check_autobahn_traffic vs check_road_status vs find_roadworks_ahead and find_cheapest_fuel vs find_fuel_station. Even superficially overlapping lookups (find_place, find_address, find_poi, describe_location) are sharply separated by input type and direction. An agent has very little room to misselect.
Every tool follows a clean snake_case verb_noun pattern (check_*, find_*, get_*, describe_*, watch_*, stop_watch). The verb prefix reliably signals the operation class, and there are no camelCase or stylistic deviations.
22 tools is on the heavy side and pushes toward the 'borderline heavy' band, but the domain (German multi-modal mobility: traffic, fuel, charging, parking, transit, weather, places, watches) is genuinely broad and nearly every tool maps to a distinct user need. Slight consolidation of the many find_* lookup tools could tighten it.
Coverage is impressive across traffic, roadworks, routing status, fuel/charging/hydrogen, parking, sharing, departures, facilities, disruption, weather, geocoding, POIs, and a full watch lifecycle (watch_situation/stop_watch). The notable gap is A-to-B journey planning, which is explicitly declined rather than supported, leaving a real but acknowledged hole.
Jams, slow traffic, closures and roadworks in force this minute on up to 5 motorways, with delay/speed. Use when asked about a named motorway now: Stau, a delay, how it looks, or a LIST of closures now; name every motorway (Munich→Berlin: A9). Do NOT use for yes/no: is a road open/closed/passable — check_road_status, even now — nor a closure with no time word or a later one (tonight, weekend); Baustellen dated or geplant — find_roadworks_ahead; Stau in a town, no motorway — check_road_status; fuel (find_cheapest_fuel), trains (get_train_departures). ~5 min old. Show the attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| kinds | No | Which event kinds to return: warning = live traffic (jams, slow traffic, hazards), closure = full closures, roadworks = construction sites. Set it when the SUBJECT of the question is one of those categories by name: "Baustellen auf der A8?" is ["roadworks"], "welche Sperrungen sind in diesem Moment gemeldet?" is ["closure"]. Omit it when the question is how the road IS — Stau, frei, a delay, "wie sieht es aus", "everything"; the German "Stau?" is the idiom for the whole picture, and a filter nobody asked for hides the closure on the same stretch. Whether a closure question is this tool's at all is decided by two things, and the noun (Sperrung, Vollsperrung, closure) is neither. FIRST THE CLOCK: only a question about this minute (jetzt, gerade, in diesem Moment, right now, at this very minute) can be this tool's — with no time word at all, or for a later window (tonight, heute Abend, am Wochenende, the coming days), it is check_road_status. SECOND, WHAT IS ASKED, which the clock cannot see: what is REPORTED or in force on a named motorway is this tool ("which closures are in force on the A100 at this very minute?"), while whether the road is OPEN or passable is check_road_status AT ANY CLOCK — "ist die A8 offen", "ist die A3 in diesem Moment gesperrt?", "komme ich da durch?" — and so is a closure asked around a town instead of on a motorway number. Baustellen with a date or the word geplant are find_roadworks_ahead. Default: all three. | |
| limit | No | Maximum events to return across all roads (1–50, default 10). Jams come first, then closures, other reports, then roadworks; within each the roads take turns in the order you listed them, so every road gets its share of the page. Only what is in force now is listed — closures announced for later are counted apart in the headline. | |
| roads | Yes | Autobahn numbers, e.g. ["A9"] or ["A8", "A99", "A9"] (1–5 per call). Name every motorway on the route so the whole drive is briefed in one call — "A9", "A 9" and "a9" are the same road. Results are grouped per road, in the order you list them. | |
| cursor | No | Pagination cursor from a previous result's _meta.nextCursor. Omit for the first page. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that the data is about 5 minutes old (a freshness/staleness caveat) and requires showing an attribution line, which are behavioral obligations beyond the annotations. It does not describe pagination behavior or error cases, but the freshness and attribution details are meaningful additions.
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-loads the core purpose, but it is very long with nested clauses and multiple exclusion paths crammed into one paragraph. Every sentence does carry routing information, but the structure could be tighter. It earns its space but is not concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and a rich input schema with full coverage, the description is complete. It covers what the tool returns, its freshness, the attribution requirement, and acts as a router to all relevant sibling tools. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the schema documents each parameter. The description goes further by explaining semantic intent: 'roads' should list every motorway on a route for one call, 'kinds' should be omitted when the question is about how the road IS, and 'language' must be set on every call to avoid a wrong-language answer. These clarify usage in ways the schema's own descriptions reinforce but the tool-level text makes actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (reports jams, slow traffic, closures, roadworks), a resource (up to 5 motorways), a temporal scope (in force this minute), and the data returned (delay/speed). It explicitly distinguishes itself from siblings like check_road_status and find_roadworks_ahead, so an agent can differentiate 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 criteria (named motorway, now, Stau, list of closures) and when-not-to-use with named alternatives for each excluded case: yes/no open/closed goes to check_road_status, dated/geplant roadworks to find_roadworks_ahead, town Stau to check_road_status, fuel to find_cheapest_fuel, trains to get_train_departures. This is about as complete as usage guidance gets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whether a motorway, B or Land road (NI, SN, TH, BW: pass the Land/town as place) is open, closed, restricted, now or coming days; by place, jams, city/Land messages, Hamburg traffic cameras. Use when asked if a road is open/passable — "ist die A8 in diesem Moment gesperrt", "komme ich durch", at any clock, closures tonight/weekend — or city Stau: "Stau in Köln?". Do NOT use for jams/delays on a named motorway or multi-motorway route — check_autobahn_traffic; roadworks in a date window — find_roadworks_ahead; city street: not held, say so. ≤ 14 days, ≤ 11 entries. Show attribution.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in WGS 84, e.g. 48.137. Use with lon when the caller already holds coordinates; otherwise use place. | |
| lon | No | Longitude in WGS 84, e.g. 11.576. Use with lat; otherwise use place. | |
| road | No | One German motorway or federal road, e.g. "A8" or "B27", or a Landes- or Staatsstraße in Niedersachsen, Sachsen or Thüringen, e.g. "L1025" or "S296". "A8", "A 8" and "a8" are the same road. Use this whenever the person named a road — it is the only input that reaches the planned-works data, which is filed by road and section and carries no coordinates. When the person also says WHERE — a town or a Bundesland ("die B2 bei Potsdam", "L1025 in Niedersachsen") — pass that as place too: only sources for that Land answer, and a Land no source covers is named. L and S numbers repeat in every Land, so give the Land with them. Otherwise give exactly one of road, place, or lat+lon. | |
| limit | No | Maximum entries to return (1–11, default 10). By road, closures come first, then restrictions in force, then planned works; by place, nearest first. | |
| place | No | Where to look, as free text: a city ("München", "Munich"), a district or Kreis ("Kreis Fulda"), a Bundesland, a station or stop ("Hamburg Hbf"), a motorway junction ("AK Neufahrn"), or a street address with a house number ("Bahnhofstraße 12, 36037 Fulda"). A motorway number alone ("A7") resolves to the road, which has no single point — name a town or junction on it instead. Use this instead of coordinates whenever the person named a place. An address needs its town or postcode — a street and a number alone exist in many towns. Give either place OR lat+lon, never both. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| horizon_days | No | How many days ahead to look, counting from now (0 = right now only, max 14, default 3). Set it only to what the person actually asked for: 0 when they said right now / gerade / jetzt / in diesem Moment, 1 for tonight or heute Abend, 3 for "this weekend", 7 for "next week", and for a named weekday ("am Freitag", "on Friday") the number of days from today to that day. A bare "is the A8 open?" asks for no window — omit the argument and take the default rather than reading it as 0. Live closures are always included whatever this is, and so, by place, are the jams reported right now ("Stau in Köln?" needs no horizon). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context the annotations don't: the ≤14-day and ≤11-entry caps, ordering semantics (closures first, then restrictions, then planned works; nearest-first by place), the requirement to show attribution, and the frank statement that city street data is not held.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and routing are front-loaded well, but the block is dense — long parenthetical lists, mixed German/English examples, and multiple constraints packed into single sentences. It is information-rich but not cleanly segmented, so scanability suffers.
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, zero-required, no-output-schema tool with full schema descriptions and safety annotations, the description covers routing, scope limits, ordering, language handling, and data gaps. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter reasoning the schema states only piecemeal: pass Land/town with L/S numbers because they repeat, road is the only path to planned-works data, and one of road/place/lat+lon. It reinforces but does not merely repeat 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 a specific verb and resource — road open/closed/restricted status across motorways, B/L/S roads, by place, jams, cameras — and explicitly distinguishes itself from check_autobahn_traffic, find_roadworks_ahead, and city-street coverage. An agent can route correctly without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use triggers with quoted German examples ('ist die A8 in diesem Moment gesperrt', 'Stau in Köln?') and explicit when-not-to-use routing to three named siblings with the condition that selects each. This is a model negative-and-positive routing block.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report whether the lifts and escalators of a German railway station — or of a Köln Stadtbahn stop — are working now: each one, where it is, its state (in service / out of service / unknown) and the operator's explanation. Use when asked about step-free access or a broken lift: "Funktioniert der Aufzug am Kölner Hauptbahnhof?", "is the lift at Hamburg Hbf working?", "Rolltreppe am Neumarkt kaputt?", wheelchair, pram, heavy luggage. Do NOT use for train times, platforms or delays — call get_train_departures. At most 50 facilities, out-of-service ones first. Results carry their attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many facilities to list (1–50, default 20). Out-of-service equipment is listed first and the counts in the summary always cover ALL of them, so a shorter list never hides a broken lift. | |
| eva_no | No | The station's EVA number (6–8 digits, e.g. 8000207 for Köln Hbf), when a previous result — a departure board, for instance — already gave you one. It skips the name lookup and is exact. | |
| station | No | The railway station — or Köln Stadtbahn stop — as the person says it: "Köln Hbf", "Hamburg Hbf", "Munich Central", "Neumarkt Köln". Pass their words — English names and "central station" are understood. If the name fits several stations the result lists them and asks which; do not guess one yourself. Give either station OR eva_no, never both. | |
| facility | No | Which equipment to report: "elevator" for lifts only, "escalator" for escalators only, "any" for both (default). Pass a value only when the person named the equipment itself ("Aufzug", "Rolltreppe", "lift", "escalator"): a question about a wheelchair, a pram, heavy luggage or step-free access keeps the default — an escalator carries a suitcase too, and a filter there hides half of what the traveller needs. Filtering does not change how a broken one is reported, only which ones are listed. | any |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered and the bar is lower. The description still adds real behavioral context beyond them: a 50-facility cap, out-of-service equipment listed first, the guarantee that summary counts cover all facilities so a short list never hides a broken lift, and an attribution line on results. Ambiguous station names producing a disambiguation list ('the result lists them and asks which; do not guess') is a genuinely useful behavior disclosure, though nothing is said about failure modes when a station has no facility data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then usage triggers, then the exclusion. It is long, but each sentence does work — the bilingual examples exist to route non-English queries and the exclusion prevents misrouting to departures. The clause about attribution lines is slightly marginal, keeping it off a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so: it lists the per-facility fields (location, state, operator explanation), the ordering rule, the cap, and the attribution line. Combined with annotations covering the safety profile and a 100%-covered schema, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the parameter descriptions are unusually thorough, so the baseline is 3. The description only echoes the limit semantics ('At most 50 facilities, out-of-service ones first') already spelled out in the limit field; it adds no new meaning for eva_no, station, facility or language beyond what the schema already documents.
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 ('Report whether the lifts and escalators ... are working now') and enumerates exactly what is returned: each facility, its location, its state (in service / out of service / unknown) and the operator's explanation. It also distinguishes itself from the nearest sibling by name ('Do NOT use for train times, platforms or delays — call get_train_departures'), so an agent can separate it from get_departures without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use triggers are given with multilingual user phrasings ('Funktioniert der Aufzug am Kölner Hauptbahnhof?', 'Rolltreppe am Neumarkt kaputt?') plus the intent vocabulary that should route here: wheelchair, pram, heavy luggage, step-free access. An explicit exclusion and named alternative (get_train_departures) covers the main confusion case, 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.
How punctual public transport is now in one German region: the share of trips ever over 5 min late, trips with a cancelled stop, the trend, and the service alerts in force there (diversions, closed stops). Use when asked whether buses and trains run normally, or a strike, storm or works disrupt them. Do NOT use for a station's departures or a line from a named DEPARTURE station ("RE1 ab Köln Hbf verspätet?"; a destination, "nach …"/"zum …", is not one) — get_train_departures. No per-line figures. Window ≤ 120 min. CC BY-SA (DELFI) or CC BY 4.0 (VBB, Berlin/Brandenburg): show attribution.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in WGS 84, e.g. 48.137. Use with lon when the caller already holds coordinates; otherwise use region. | |
| lon | No | Longitude in WGS 84, e.g. 11.576. Use with lat; otherwise use region. | |
| region | No | The German region to report on, as free text: a Bundesland ("Bayern", "Bavaria", "Nordrhein-Westfalen"), a city ("Hamburg", "Köln"), a Kreis ("Landkreis Fulda") or one of the conurbations Ruhrgebiet, Rhein-Ruhr and Rhein-Main. A town inside a Kreis is reported as that Kreis and the answer says so, because the data is filed at Kreis level. Not a stop, not a street, not an address. Give either region OR lat+lon, never both. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| window_min | No | How many minutes back to look, 5–120 (default 60). The trend compares this window with the equally long one before it, so 60 means "the last hour against the hour before". Use a short window for "right now" and a long one for "has it been bad all morning". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, but the description adds traits they cannot carry: no per-line granularity, a hard 120-minute window cap, region-level data filing (a town is reported as its Kreis and the answer says so), and mandatory licence attribution (CC BY-SA DELFI / CC BY 4.0 VBB). These are real operational constraints an agent must respect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and tightly packed, with the when/when-not routing and the licence clause each doing work. The parenthetical German query examples add length but also real disambiguation value, so only minor trimming is possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return burden and does so — it names the four reported metrics and the alert types (diversions, closed stops). Zero required parameters plus documented lat/lon-vs-region exclusivity and the language default warning cover everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the description largely restates the window limit ("Window ≤ 120 min") already documented in the schema. Its genuinely additive notes — no per-line figures and the lat/lon vs region exclusivity — are already covered by the parameter descriptions, so it does not meaningfully extend parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (punctuality of public transport in one German region) and enumerates exactly what is reported: share of trips >5 min late, cancelled stops, trend, and service alerts in force. It explicitly separates itself from get_train_departures and rules out per-line figures, so an agent can distinguish it from siblings without opening the schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit positive trigger ("Use when asked whether buses and trains run normally, or a strike, storm or works disrupt them") and an explicit negative one ("Do NOT use for a station's departures or a line from a named DEPARTURE station... get_train_departures"). The German example even disambiguates a destination phrase ("nach …") from a departure station, which is unusually precise routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the official DWD weather warnings in force for a place — storm, snow, ice, heavy rain, thunderstorm, heat — with Warnstufe 1–4, area, validity and the official text unaltered. At a town or coordinate it adds the DWD road-surface forecast (Straßenwetter-Prognose: dry to black ice, road temperature) for the nearest road-weather stations. Use when asked about weather on a trip, safe driving, storm or snow warnings, or icy roads (Glätte, Glatteis). Do NOT use for a general forecast (not offered) or jams (check_autobahn_traffic). Show the attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in WGS 84, e.g. 48.137. Use with lon when the caller already holds coordinates; otherwise use place. | |
| lon | No | Longitude in WGS 84, e.g. 11.576. Use with lat; otherwise use place. | |
| place | No | Where to look, as free text: a city ("München", "Munich"), a district or Kreis ("Kreis Fulda"), a Bundesland, a station or stop ("Hamburg Hbf"), a motorway junction ("AK Neufahrn"), or a street address with a house number ("Bahnhofstraße 12, 36037 Fulda"). A motorway number alone ("A7") resolves to the road, which has no single point — name a town or junction on it instead. Use this instead of coordinates whenever the person named a place. An address needs its town or postcode — a street and a number alone exist in many towns. Give either place OR lat+lon, never both. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| min_level | No | Lowest official DWD level to report, 0–4 (default 0, i.e. everything). The DWD's own names: 1 = Wetterwarnung, 2 = Markante Wetterwarnung, 3 = Unwetterwarnung, 4 = Warnung vor extremem Unwetter; 0 = Vorabinformation Unwetter, an advance notice that is not yet a Warnstufe. Raise it ONLY when the question names a level or a Warnstufe in so many words ("ab Stufe 3", "level 3 or higher", "nur Stufe 4"). Unwetter, Unwetterwarnung, severe and storm are the ordinary way to ask about bad weather, not a filter: leave it at 0 there — a level the caller filtered away is a warning the person is never told about. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safe read-only/idempotent/open-world profile, so the description focuses on what the annotations can't say: the data is official DWD text returned unaltered, the road forecast applies to the nearest road-weather stations, and the caller must display an attribution line. Rich added context, though it stops short of noting any rate limits or failure modes.
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?
Heavily front-loaded: purpose, then hazard/level detail, then the road-forecast extension, then when-not, then the attribution directive. No filler sentences; each clause carries distinct information despite the density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return contract and does so: Warnstufe 1–4, area, validity, official unaltered text, and the road-weather forecast fields. For a read-only lookup with 100% schema coverage and full annotations, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema itself documents each parameter well, so the baseline is 3. The description earns above baseline by explaining a behavioral consequence of the place-vs-coordinate choice (the road-surface forecast is added at a town or coordinate), which the schema does not state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource (official DWD weather warnings in force for a place) and enumerates the hazard types and Warnstufe 1–4, plus the extra road-surface forecast at town/coordinate. It also names the sibling it is NOT (check_autobahn_traffic for jams), so an agent can separate it from adjacent tools without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit positive triggers (trip weather, safe driving, storm/snow warnings, icy roads/Glätte) and explicit exclusions (general forecast not offered; jams go to check_autobahn_traffic). It even adds a caller obligation, 'Show the attribution line', leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turns a coordinate into words: the nearest address, settlement and motorway junction with their distances, and the Gemeinde, Kreis and Land the point lies in. Use when you already HAVE a lat/lon and need to say where that is. Do NOT use to look up a place or address BY NAME — that is find_place, find_poi or find_address; this only goes coordinate to words. Those three come from the municipality the point lies in (by its official key), not from the nearest Kreis point; near the national border the answer says so. OpenStreetMap ODbL 1.0 for the address; show the attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude of the point to describe (WGS84). | |
| lon | Yes | Longitude of the point to describe (WGS84). | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive) but the description adds real behavioral context the agent couldn't infer: boundary behaviour near national borders is disclosed, and the licensing/attribution requirement (OSM ODbL 1.0, must show attribution line) is a genuine obligation. It also flags that Gemeinde/Kreis/Land come from the municipality's official key rather than nearest Kreis point, a subtle accuracy caveat.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads purpose, then usage routing, then behavioral caveats in a compact block. Slightly dense with the licensing sentence appended, but every sentence earns its place and none is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, no-output-schema tool, it covers purpose, alternatives, output contents, boundary caveat, and attribution obligation. Nothing an agent needs to call and correctly present results 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% with an enum on language, so baseline would be 3; the description adds meaning beyond the schema by warning that omitting language defaults to German and yields a wrong answer for English questions, and clarifying that place names/road numbers are never translated. This is actionable semantic guidance beyond the raw enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('turns a coordinate into words') and enumerates the exact outputs (nearest address, settlement, motorway junction with distances, Gemeinde/Kreis/Land). It explicitly differentiates from siblings find_place, find_poi, find_address by stating 'this only goes coordinate to words'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('when you already HAVE a lat/lon and need to say where that is') and when-not ('Do NOT use to look up a place or address BY NAME'), naming the three alternative lookup tools. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Looks up a street address: its coordinate, and the named OpenStreetMap objects at it (company, shop, office) or that none are. Use when the person gives a STREET AND NUMBER — "Bahnhofstraße 12, Fulda" — for the point, or for who or what is there. The coordinate passes to any other tool as lat/lon. Do NOT use for a town/district/station name alone (find_place) or a company/shop/landmark by name (find_poi) — needs a street and a number. At most 5 points; a door mapped twice is folded, points far apart say how far; several towns are a question. OpenStreetMap ODbL 1.0; show the attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many results to return (1–5, default 3) — more than one means the same address carries more than one OpenStreetMap object. | |
| query | Yes | A street address, as a person writes one: street and house number, plus a town or postcode — "Bahnhofstraße 12, 36037 Fulda" or "Bahnhofstraße 12, Fulda". Both orders work. A street and number with neither a town nor a postcode cannot be placed (the same street name exists in about two thousand German towns) and is refused. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only/idempotent/non-destructive profile, but the description adds substantial behavioral detail beyond them: a 5-point cap, duplicate-door folding, distance disclosure when points are far apart, ambiguity handling ('several towns are a question'), and the ODbL attribution obligation. That is exactly the kind of result-shaping and licensing context annotations 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?
Front-loaded with purpose and trigger, and every sentence carries information (limits, dedup, attribution). It is quite dense with em-dash clauses and parentheticals, which slightly taxes readability, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description explains what is returned (a coordinate reusable as lat/lon, plus the named OSM objects or an explicit none), and annotations cover the safety profile. Nothing an agent needs to call or interpret it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents query, limit, and language in detail, including the language default trap. The description reinforces the street+number requirement for query but adds no format or syntax detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('looks up a street address') and enumerates what it returns: the coordinate plus named OSM objects at that point. It explicitly distinguishes itself from find_place and find_poi by naming them, so an agent can route correctly without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit positive trigger (a STREET AND NUMBER, with a worked example) and explicit exclusions: not for a town/district/station name alone (find_place) or a company/shop/landmark by name (find_poi). It also states the input precondition (needs both street and number), 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.
Returns EV charging sites near a place or coordinate with operator, connector types, maximum power, price per kWh where published, and how many points are free right now where the operator publishes live status. Use when an EV driver asks where to charge ("Wo kann ich laden?", "CCS 150 kW near Leipzig", "ist gerade eine Säule frei?"). Do NOT use for petrol or diesel — call find_cheapest_fuel; for E-Kennzeichen or Ladekarte rules — call get_driving_rules. Radius ≤ 25 km, ≤ 10 sites; availability is missing for most operators and is then unknown, never free. Show the attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in WGS 84, e.g. 48.137. Use with lon when the caller already holds coordinates; otherwise use place. | |
| lon | No | Longitude in WGS 84, e.g. 11.576. Use with lat; otherwise use place. | |
| limit | No | How many lines to return, nearest first (1–10, default 5). Records of one place within 50 m that read alike are folded into one line that says how many units it holds; structuredContent.sites lists every record of the lines shown, so it can be longer than limit. | |
| place | No | Where to look, as free text: a city ("München", "Munich"), a district or Kreis ("Kreis Fulda"), a Bundesland, a station or stop ("Hamburg Hbf"), a motorway junction ("AK Neufahrn"), or a street address with a house number ("Bahnhofstraße 12, 36037 Fulda"). A motorway number alone ("A7") resolves to the road, which has no single point — name a town or junction on it instead. Use this instead of coordinates whenever the person named a place. An address needs its town or postcode — a street and a number alone exist in many towns. Give either place OR lat+lon, never both. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| connector | No | Plug the car needs: "ccs2" (CCS Combo 2 — the DC fast-charging standard on almost every European EV), "type2" (Typ 2 / Mennekes, the AC socket) or "chademo" (older Japanese DC, e.g. Nissan Leaf). Omit unless the person named their plug or their car model — filtering on a guess hides chargers they could have used. | |
| radius_km | No | Search radius around the place in kilometres (1–25, default 10). A charging stop is worth a detour, so this is wider than the fuel radius — but 25 km is the cap, and a larger circle is a dataset request rather than a driver's question. | |
| min_power_kw | No | Only charging points of at least this many kW (1–1000). Use when the person names a number or asks for fast charging: 50 = DC fast (a bare "fast"/"schnell"/"Schnelllader"), 150 = HPC ("HPC", "ultra", "ultraschnell"), 300 = the fastest posts in Germany. Omit for "where can I charge" — 11 kW overnight is a valid answer to that question. | |
| only_available | No | When true, return only sites with at least one point reported FREE right now. Default false. Use it when the person asks what is free at this moment. Note that only some operators publish live status: the result always says how many nearby sites were dropped because their status is unknown, so the filter never silently hides a charger that may well be free. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description goes further with non-obvious behavior: availability data is missing for most operators and must be reported as unknown, never as free, plus the mandatory attribution line. That overlap with the only_available parameter description is why it lands at 4 rather than 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose, then examples, then routing, then limits and the attribution requirement — a logical order with almost no filler. It is dense and slightly long, and the radius/limit sentence duplicates schema bounds, keeping it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 optional parameters and no output schema, the description still sketches the returned fields, documents the free-vs-unknown availability caveat, sets the geographic caps, and imposes the attribution-line obligation. An agent has everything needed to call it correctly and to present the result honestly.
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 each parameter carries unusually rich guidance (place formats, enum meanings, power thresholds, radius rationale), so the schema does the heavy lifting and the baseline is 3. The description's contribution — "Radius ≤ 25 km, ≤ 10 sites" and the "CCS 150 kW" example — largely restates bounds already in 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?
A specific verb+resource ("Returns EV charging sites") plus the exact payload the agent will get back (operator, connector types, max power, price per kWh, live free-point counts). It explicitly states what it is not — petrol/diesel — and names the sibling (find_cheapest_fuel) that owns that case, so routing is unambiguous without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete user phrasings that trigger the tool ("Wo kann ich laden?", "CCS 150 kW near Leipzig"), then explicit exclusions with named alternatives: petrol → find_cheapest_fuel, E-Kennzeichen/Ladekarte rules → get_driving_rules. Constraints (radius ≤ 25 km, ≤ 10 sites) are stated up front so the agent knows when a request falls outside the tool's scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the cheapest stations for one fuel grade near a place or coordinate: price per litre, brand, address, distance, open state. Use when the user asks where to fill up or what fuel costs. Do NOT use for charging an electric car (call find_charging_station), price history, or traffic (call check_autobahn_traffic). Radius ≤ 25 km, at most 10 stations. For a brand, a name, open now or at a named time, or nearest-first, call find_fuel_station. Each line names the age of its price and opening-hours claim. Prices are consumer information only; the attribution line and MTS-K note must be shown.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in WGS 84, e.g. 48.137. Use with lon when the caller already holds coordinates; otherwise use place. | |
| lon | No | Longitude in WGS 84, e.g. 11.576. Use with lat; otherwise use place. | |
| fuel | No | Fuel grade: "e5" (Super E5), "e10" (Super E10, the standard German petrol) or "diesel". Default "e10". Pass the grade the person named — a diesel driver is not helped by a petrol price. | e10 |
| limit | No | How many stations to return, cheapest first (1–10, default 5). The provider's terms cap it at 10. | |
| place | No | Where to look, as free text: a city ("München", "Munich"), a district or Kreis ("Kreis Fulda"), a Bundesland, a station or stop ("Hamburg Hbf"), a motorway junction ("AK Neufahrn"), or a street address with a house number ("Bahnhofstraße 12, 36037 Fulda"). A motorway number alone ("A7") resolves to the road, which has no single point — name a town or junction on it instead. Use this instead of coordinates whenever the person named a place. An address needs its town or postcode — a street and a number alone exist in many towns. Give either place OR lat+lon, never both. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| radius_km | No | Search radius around the place in kilometres (1–25, default 5). The provider's terms cap it at 25 km — a larger circle is a dataset request, not a consumer question. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/openWorld/non-destructive, and the description adds context beyond them: each returned line discloses the age of its price and opening-hours claim, the provider's terms cap radius and result count, and the attribution line and MTS-K note are mandatory outputs. Nothing here contradicts the safety 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?
Front-loaded with the core return description, then when-to-use, when-not, parameter routing, and output/legal constraints in that order. Despite covering a 7-parameter tool with no output schema, every clause carries distinct information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the returned fields, the price-age and hours-age disclosures, and the required attribution/MTS-K output. Combined with the schema's 100% parameter coverage and the safety annotations, an agent has everything needed to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema text already explains lat/lon vs place, the fuel enum intent, language defaulting, and the radius/limit caps. The description mostly restates the radius and limit bounds rather than adding new parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource with a clear scope: cheapest stations for one fuel grade near a place/coordinate, plus exactly what each result carries (price per litre, brand, address, distance, open state). It explicitly distinguishes itself from find_fuel_station (brand, name, open-now, nearest-first) and from find_charging_station and check_autobahn_traffic, so an agent can route correctly 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?
Gives explicit when-to-use ("where to fill up or what fuel costs"), explicit when-not (electric charging, price history, traffic) with the alternative tool named for each, and a routing rule to find_fuel_station for brand/name/open-now/named-time/nearest-first. Constraint envelopes (radius <= 25 km, at most 10 stations) are stated up front.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds filling stations around a place or coordinate under any combination of filters — grade, brand, name, open now, open at a time you name, open 24 h — sorted by distance, price or name. Use when the question is WHICH station: the closest diesel to a stop, an ARAL open tonight, what one forecourt sells. Do NOT use for the plain "where is fuel cheapest" question (call find_cheapest_fuel) or for charging an electric car (call find_charging_station). Every result carries the attribution and the MTS-K note, and says how old each price and opening-hours claim is.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in WGS 84, e.g. 48.137. Use with lon when the caller already holds coordinates; otherwise use place. | |
| lon | No | Longitude in WGS 84, e.g. 11.576. Use with lat; otherwise use place. | |
| fuel | No | Only stations with a current price for this grade: "e5" (Super E5), "e10" (Super E10) or "diesel". Omit to get every station near the place whatever it sells — the answer then lists all the grades it holds a price for. Required when sort is "price", because a price ordering needs a grade. | |
| name | No | Part of the station's own name or brand, case-insensitive: "Autohof", "Raststätte Fulda". Use it when the person named a specific forecourt rather than a chain. Combine with place to keep the search local. | |
| sort | No | Order of the answer: "distance" (nearest first, the default — use it for "closest diesel to Hamburg Hbf"), "price" (cheapest first, needs fuel), or "name" (alphabetical, for a person scanning a list of a brand's forecourts). | distance |
| brand | No | Only stations of this brand, matched case-insensitively anywhere in the brand field: "ARAL", "Shell", "TotalEnergies", "JET". Use it when the person named a chain ("die ARAL an der B1"). Free stations often carry no brand at all and are then not matched by any brand. | |
| limit | No | How many stations to return (1–10, default 5). | |
| place | No | Where to look, as free text: a city ("München", "Munich"), a district or Kreis ("Kreis Fulda"), a Bundesland, a station or stop ("Hamburg Hbf"), a motorway junction ("AK Neufahrn"), or a street address with a house number ("Bahnhofstraße 12, 36037 Fulda"). A motorway number alone ("A7") resolves to the road, which has no single point — name a town or junction on it instead. Use this instead of coordinates whenever the person named a place. An address needs its town or postcode — a street and a number alone exist in many towns. Give either place OR lat+lon, never both. | |
| open_at | No | Only stations open at that time in Germany (Europe/Berlin): "23:30" means the next time the clock shows 23:30, and "2026-09-30 06:15" a specific local date and time. Use it for "is it still open tonight". Do not pass it together with open_now — they ask the same question about two different clocks. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| open_now | No | When true, only stations the published opening hours say are open at this moment. Default false. A station whose hours we have never read is NOT returned by this filter and is counted in the answer instead — the result never guesses that an unknown station is open. | |
| radius_km | No | Search radius around the place in kilometres (1–25, default 5). 25 km is the provider's own ceiling — a larger circle is a dataset request, not a consumer question. | |
| whole_day | No | When true, only stations the provider flags as open around the clock (24/7). Default false. Use it when asked whether a station never closes ("durchgehend geöffnet", "around the clock") and for a night drive; it is a stricter filter than open_now, which is satisfied by a station that closes at 22:00. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses data provenance and freshness behavior: every result carries attribution and the MTS-K note plus the age of each price and opening-hours claim. It also clarifies that unknown hours are never treated as open, which is a real behavioral trait not present in 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?
Three sentences, capability first, exclusions second, output caveat last — well front-loaded with no filler. It is dense (long em-dash clause) but each clause carries routing or behavioral information, so nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 13 optional parameters and no output schema, the description still tells the agent what determines the answer (filters + sort) and what comes back (attribution, MTS-K note, staleness). Combined with the fully documented schema, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema descriptions already carry the cross-parameter rules (fuel required for sort=price, place OR lat+lon, open_at vs open_now). The description only summarizes the filter set without adding syntax or format meaning beyond it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb+resource ("Finds filling stations") and immediately narrows scope: around a place or coordinate, with the exact filter axes (grade, brand, name, open now, open at a time, 24 h) and sort orders. It explicitly names the siblings it is not (find_cheapest_fuel, find_charging_station), so an agent can route 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?
Gives a positive selection rule ("Use when the question is WHICH station") with three concrete examples, plus two explicit exclusions routing to find_cheapest_fuel and find_charging_station. When-to-use, when-not, and the alternatives are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns hydrogen (H2) filling stations near a place or coordinate, nearest first, with operator, address, pumps (700 bar car, 350 bar truck/bus), opening hours where published and the age of the record. Use when someone asks where to refuel a fuel-cell car, lorry or bus ("Wasserstofftankstelle", "H2 tanken", "hydrogen station near me"). Do NOT use for petrol, diesel or LPG (call find_fuel_station) or EV charging (call find_charging_station). Radius ≤ 150 km, ≤ 10 stations; no live availability or price is published. Shows the attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in WGS 84, e.g. 48.137. Use with lon when the caller already holds coordinates; otherwise use place. | |
| lon | No | Longitude in WGS 84, e.g. 11.576. Use with lat; otherwise use place. | |
| limit | No | How many stations to list, nearest first (1–10, default 5). | |
| place | No | Where to look, as free text: a city ("München", "Munich"), a district or Kreis ("Kreis Fulda"), a Bundesland, a station or stop ("Hamburg Hbf"), a motorway junction ("AK Neufahrn"), or a street address with a house number ("Bahnhofstraße 12, 36037 Fulda"). A motorway number alone ("A7") resolves to the road, which has no single point — name a town or junction on it instead. Use this instead of coordinates whenever the person named a place. An address needs its town or postcode — a street and a number alone exist in many towns. Give either place OR lat+lon, never both. | |
| vehicle | No | Which pump the vehicle needs: "car" (Pkw — 700 bar, e.g. Toyota Mirai, Hyundai Nexo; a few sites also offer 350 bar for cars) or "truck" (Lkw or bus — 350 bar). Omit unless the person said what they drive. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| radius_km | No | Search radius around place or lat+lon in kilometres (1–150, default 50). Hydrogen stations are few, so the default is wide; when none is inside, the answer still names the nearest one beyond. Example: 50 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-redundant behavior: hard caps (radius ≤ 150 km, ≤ 10 stations), the absence of live availability or pricing, that the nearest station is named even when out of radius, and that an attribution line is shown. It does not discuss error behavior or what happens on an unresolvable place, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with what is returned, then the trigger, then the exclusions and caps. Every clause carries information; it is dense but not padded, though the multilingual example list and operator-field enumeration make it a little long for the core signal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must describe the return payload — and it does, naming operator, address, pump pressures (700 bar car / 350 bar truck-bus), opening hours, record age and the attribution line. Combined with the caps and the no-live-data caveat, an agent has everything needed to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already spells out coordinate-vs-place exclusivity, enum meanings, ranges and defaults thoroughly, so the baseline is 3. The description reiterates the radius and count caps but adds no syntax or format meaning beyond what the schema supplies.
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?
Specific verb+resource ('Returns hydrogen (H2) filling stations near a place or coordinate'), with scope stated as nearest-first and the returned fields enumerated. It explicitly names the siblings it is not (find_fuel_station for petrol/diesel/LPG, find_charging_station for EV), so an agent can distinguish it without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use trigger ('where to refuel a fuel-cell car, lorry or bus') with multilingual query phrasings, plus explicit when-not-to-use clauses routing to two named alternatives. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Overview of what is around a place or coordinate: nearby fuel stations, EV charging, parking, the nearest railway station and motorway junction, each with its distance. Use when someone asks "what is around me" or "what is near " — a broad look, not one category in depth. Do NOT use for a fuel grade's price (find_cheapest_fuel), charger/connector status (find_charging_station), parking kind/occupancy (find_parking), a NAME lookup (find_place/find_poi/find_address), or a coordinate's address (describe_location). Radius ≤ 15 km, up to 3 per category. Shows each source's attribution.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in WGS 84, e.g. 48.137. Use with lon when the caller already holds coordinates; otherwise use place. | |
| lon | No | Longitude in WGS 84, e.g. 11.576. Use with lat; otherwise use place. | |
| place | No | Where to look, as free text: a city ("München", "Munich"), a district or Kreis ("Kreis Fulda"), a Bundesland, a station or stop ("Hamburg Hbf"), a motorway junction ("AK Neufahrn"), or a street address with a house number ("Bahnhofstraße 12, 36037 Fulda"). A motorway number alone ("A7") resolves to the road, which has no single point — name a town or junction on it instead. Use this instead of coordinates whenever the person named a place. An address needs its town or postcode — a street and a number alone exist in many towns. Give either place OR lat+lon, never both. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| radius_km | No | Search radius around place or lat+lon in kilometres (1–15, default 5). This tool answers "what is around me", not "search a wide area" — for that, use the specific tool with its own wider radius. | |
| categories | No | Which categories to include: "fuel", "charging", "parking", "station" (railway station), "junction" (motorway junction). Omit for all five. Pass a subset only when the person named one — otherwise the full picture is the point of this tool. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive), so the description's added value is its operational limits: radius capped at 15 km, up to 3 results per category, and per-source attribution being surfaced. It doesn't discuss failure modes or behavior when a place doesn't resolve, but the disclosed caps go 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?
Front-loaded with purpose, then use, then do-not-use routing, then constraints — a logical order with no filler. It is dense and long, but given six parameters and twelve sibling tools, nearly every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and zero required parameters, the description covers what an agent needs: what comes back (per-category items with distances and attribution), the radius cap, and the latitude/longitude-vs-place choice. 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 description coverage is 100% and the schema text is very rich (WGS 84 ranges, place free-text formats, language default warning), so the schema carries the burden. The description adds one genuinely new detail — the up-to-3-per-category return cap — and restates the radius bound, hence the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource scope (fuel, charging, parking, railway station, motorway junction) and its distinguishing trait — a broad radius-based overview with distances per category. It explicitly contrasts itself with one-category-in-depth tools like find_cheapest_fuel and find_parking, so an agent can separate it from all siblings without opening a 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 gives a direct trigger ("what is around me", "what is near <place>") and then an explicit do-not-use list mapping each excluded intent to the right sibling (find_cheapest_fuel, find_charging_station, find_parking, find_place/find_poi/find_address, describe_location). Nothing about routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parking near a place, a coordinate or along one motorway: motorway lorry parks, car parks and P+R sites, with total spaces and, where published, free spaces now and the reading's age. Use when asked where to park or leave the car for the train ("Parkhaus in Köln", "Rastplatz A3", "P+R"). Do NOT use for fuel (find_cheapest_fuel) or EV charging (find_charging_station). Radius ≤ 25 km, ≤ 10 sites per list; ODbL and CC BY-SA sources are separate lists (up to three). No "free now" means no published count, not full. No prices: for "was kostet" say so, no call. Show each source's attribution.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in WGS 84, e.g. 48.137. Use with lon when the caller already holds coordinates; otherwise use place. | |
| lon | No | Longitude in WGS 84, e.g. 11.576. Use with lat; otherwise use place. | |
| kind | No | Which kind of parking: "car_park" = public car park (Parkhaus/Parkplatz), "park_and_ride" = P+R beside a station, "truck" = lorry parking, "any" = all of them. Default "any". Rest areas are NOT a kind we can filter: no source we hold classifies them, so for "Rastanlage"/"Raststätte"/"rest area" leave kind out ("truck" when lorry spaces were asked for); "rest_area" is still accepted and answered as "any", with a sentence saying why. Pass a kind only when the person named one — a lorry driver asking for a break wants "truck", someone leaving the car for the train wants "park_and_ride". A camper, a caravan or a coach is none of these: leave the argument out rather than filtering a tourist into lorry bays. | any |
| road | No | A single motorway number to list parking along, e.g. "A3" ("A 3" and "a3" are the same road). Use this when the person named a road and no town — "Rastplatz auf der A7". Give road OR place OR lat+lon, never two of them: a road is a 900 km line and a place is a point, so the two answer different questions. When the question names BOTH — "Parkhaus in Köln an der A3" — use the place: a person parks at a point, and the radius already covers the motorway beside it. A road list is in name order and cannot follow a direction of travel: for "A4 Richtung Görlitz" ask with place for the destination or the next town on the way instead, which answers nearest first. | |
| limit | No | How many facilities to return, nearest first (1–10, default 5). | |
| place | No | Where to look, as free text: a city ("München", "Munich"), a district or Kreis ("Kreis Fulda"), a Bundesland, a station or stop ("Hamburg Hbf"), a motorway junction ("AK Neufahrn"), or a street address with a house number ("Bahnhofstraße 12, 36037 Fulda"). A motorway number alone ("A7") resolves to the road, which has no single point — name a town or junction on it instead. Use this instead of coordinates whenever the person named a place. An address needs its town or postcode — a street and a number alone exist in many towns. Give either place OR lat+lon, never both. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| radius_km | No | Search radius around place or lat+lon in kilometres (1–25, default 10). Ignored when you pass road, which covers the whole motorway. Start small in a city and widen if the answer is empty. | |
| only_with_free_spaces | No | Set true only when the person asks whether spaces are free right now. It keeps just the facilities whose operator publishes live occupancy AND currently reports a space, and the result says how many were dropped for publishing nothing — most German parking publishes no occupancy at all, so true usually narrows the answer to very little. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial non-obvious behavior: radius cap of 25 km, max 10 sites per list, up to three separate source lists (ODbL vs CC BY-SA), attribution display requirement, and the critical warning that an absent 'free now' means no published count rather than a full lot.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose before constraints, and every sentence carries information (limits, exclusions, pricing gap, attribution). It is dense and slightly long, with a few parenthetical examples that could be trimmed, but nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must carry return-shape and edge-case burden, and it does: it describes what fields come back (spaces, free spaces, reading age), how many results, the multi-source split, the no-price gap, and the empty-list widening cue. Nothing an agent needs to answer 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, but the description adds interpretation the schema does not: "No 'free now' means no published count, not full", the ≤25 km / ≤10-per-list limits, and the note that sources split into separate lists. It does not add much on lat/lon/place/road beyond the schema, but the occupancy-semantics clarification is genuinely value-adding.
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 a specific verb-and-resource combination (parking near a place/coordinate/motorway) and enumerates exactly what is returned: lorry parks, car parks, P+R sites, total spaces and published free spaces with reading age. It is instantly separable from find_cheapest_fuel and find_charging_station, which are named directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use triggers are given ('where to park or leave the car for the train') with three concrete example queries, plus explicit when-NOT-to-use routing to two named siblings for fuel and EV charging. It also states the no-price case is a no-call case, which prevents a wrong invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Looks up a place name and returns every place that matches, each with its kind, official key (AGS/RS), population, English name and coordinate. Use when the person asks where somewhere is, when you need a coordinate for another tool, and above all to RECOVER after a tool reported a name as ambiguous — this is where you find out which Neustadt is which. Pass near to rank and separate same-named places by distance. Do NOT use to find a company, shop or landmark: call find_poi. At most 10 results, radius <= 200 km. Every result carries an attribution line that must be shown to the user.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude to measure from, instead of `near`. | |
| lon | No | Longitude to measure from, instead of `near`. | |
| kind | No | Narrow to one kind: "city", "district" (Kreis), "admin" (Land or Regierungsbezirk), "station", "stop", "motorway" or "junction". Omit unless the person was specific. | |
| near | No | A second place to measure from, used to tell same-named candidates apart: "Neustadt" near "Hamburg" is one of twenty Neustadts. Every result then carries its distance from this point. | |
| limit | No | How many candidates to return, best match first (1–10, default 5). | |
| query | Yes | The place name to look up, as the person said it — "Neustadt", "Munich", "Kreis Fulda", "Köln Hbf". English names and spellings without umlauts both work. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| radius_km | No | When near/lat+lon is given, keep only candidates within this many kilometres (1–200). Omit to rank by distance without dropping any. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: a cap of 10 results, a 200 km radius ceiling, and a mandatory attribution line that must be shown to the user. It omits anything about ranking/ordering details beyond 'best match first', which is minor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then usage triggers, then constraint, with the key routing rule stated early. Slightly long and mildly redundant (the 'which Neustadt is which' example echoes the schema), but every sentence carries actionable content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by listing the returned fields and the attribution requirement. Combined with annotations and 100% schema coverage across 8 params, an agent has everything needed to call this correctly and route to it appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the rich per-parameter docs (near, radius_km, language, kind) already carry the parameter semantics. The description adds only a light pointer ("Pass `near` to rank and separate same-named places"), which the schema itself states more fully. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (looks up) and resource (a place name), enumerates the returned fields (kind, AGS/RS key, population, English name, coordinate), and explicitly distinguishes itself from the sibling find_poi. An agent can identify it and separate it from find_address, find_poi and describe_location without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives three concrete when-to-use triggers (where somewhere is, need a coordinate for another tool, recovering from an ambiguity error) and an explicit exclusion ("Do NOT use to find a company, shop or landmark: call find_poi"). The alternative tool is named, so routing is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds a business or landmark by name or kind — company, shop, clinic, hotel, hostel — with address, category and coordinate. Use when the person names a THING rather than a town: "the adesso office in Dortmund", "the nearest Aldi", "a hotel in Weimar". The coordinate passes to any other tool as lat/lon. Do NOT use for a town, district or station (every tool's place resolves those), nor for fuel, charging or parking (own tools). Give "in" (a town) when you can: far faster than nationwide. 25 per page, 50 via cursor; radius <= 50 km. OpenStreetMap under ODbL 1.0; show the attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| in | No | A town to search in — "Dortmund", "Fulda". Strongly preferred: it is both far faster and far less ambiguous than a nationwide search. Use this OR near/lat+lon, not both. | |
| lat | No | Latitude of the point to search around, when the caller already holds a coordinate. | |
| lon | No | Longitude of the point to search around. | |
| name | Yes | The name of the thing to find — a company, shop, clinic, hotel, office or landmark. Part of the name is enough: "adesso" finds "adesso SE". A chain name works too, because brands are matched as well as names. A kind word alone, German or English ("Apotheke", "pharmacy", "trade fair"), lists that kind nearest first. When the person names a company AND a type ("the Bosch office"), put the company here and the type in category. Never for fuel, charging or parking, even near a named company or landmark ("a charger by the Allianz Arena"): those have their own tools, asked with the place. | |
| near | No | A place to search around, when the question is "the nearest X" rather than "X in Y". Use with radius_km. | |
| limit | No | How many to return per page, best match first (1–25, default 10). The answer says when more matched; fetch them with cursor, up to 50 in all. | |
| cursor | No | Pagination cursor from a previous result's _meta.nextCursor. Omit for the first page. | |
| category | No | Narrow to one OpenStreetMap family: "office" (companies, agencies), "shop", "amenity" (fuel, pharmacy, school, restaurant, town hall), "healthcare" (hospitals, clinics, doctors, pharmacies), "tourism" (hotels, attractions), "leisure", "industrial" (factories, plants), "historic" (castles, monuments, city gates), "natural" (mountain peaks) or "building". Set it whenever the person names the type ("Bosch office" → office, "Hotel Adler" → tourism); omit it when they name no type. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| radius_km | No | Search radius in kilometres around near/lat+lon (1–50, default 10). Ignored when "in" is used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and not open-world. The description adds operational constraints: pagination limits (25 per page, 50 via cursor), radius limit (≤50 km), coordinate pass-through, and attribution requirement (ODbL 1.0). These are valuable behavioral details beyond the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and usage rules. Every sentence is dense with actionable information—examples, exclusions, pagination, attribution—and none is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with no output schema, the description covers selection criteria, key parameter usage, pagination, radius limit, and legal attribution. It provides everything an agent needs to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minor guidance (e.g., 'Give in when you can') but largely repeats constraints like page size and radius that are also in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (find) and resource (business or landmark) with examples, and explicitly distinguishes from siblings by naming what it is NOT for (towns, fuel, charging, parking). An agent can select it without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (person names a THING) and when-not-to-use (town, district, station, fuel/charging/parking), and recommends using 'in' for speed. Names alternatives implicitly via sibling tools, 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.
Returns roadworks PLANNED on one motorway, one Bundes-/Landesstraße in NI, SN, TH or BW, or Hamburg city streets by place, in a date window: section, restriction, dates. Use when a date or window is named, it says geplant, or how long a site lasts ("Baustellen auf der A7 in den Sommerferien?"). ONE road/place per call. Do NOT use when more than one motorway is named, for the situation this minute, or for Baustellen with neither date nor geplant — all three are check_autobahn_traffic; whether a road is open — check_road_status. ≤ 92 days, max 20 sites. Show attribution.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last day of the window, inclusive, as YYYY-MM-DD. Omit for 7 days after `from`, which is the right window for "am I going to hit roadworks on this drive". The window may span at most 92 days. For "how long will this last" / "wie lange dauert die Baustelle noch", leave both dates out: the default 7 days already returns the site's planned end date. Only widen — 28 days is the sensible step — when the person asked about a period that long. | |
| from | No | First day of the window, as YYYY-MM-DD in German local time. Omit for today. Resolve relative wording ("next Friday", "in den Sommerferien", "nächsten Monat") into real dates yourself, counted from today's date; this argument never takes words, and it never takes a fixed example date — the window a person means moves with the calendar. | |
| road | No | The road to look at, one per call: an Autobahn, e.g. "A7" or "A100", or a Bundesstraße, Landesstraße or Staatsstraße in Niedersachsen, Sachsen or Thüringen, e.g. "B6", "L1025", "S296" — "A7", "A 7" and "a7" are the same road. B and L roads in other Länder and Kreisstraßen are not covered. Ask again for a second road. Give road OR place. | |
| limit | No | Maximum sites to return (1–20, default 10), ordered by planned start. Every returned site is in the structured result; the readable text prints the first 10 and says how many more of them are in the structured half. The answer always names how many sites the window holds in total, so a small limit never hides the size of the problem. | |
| place | No | A place in Hamburg — a district, street or address, e.g. "Hamburg-Altona", "Wilhelmsburg", "Köhlbrandbrücke" — for the city's own roadworks (Bauweiser) within 3 km of it. Outside Hamburg, city roadworks are not held and the answer says so. Give road OR place. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe read-only, idempotent, non-open-world profile, so the bar is lower. The description still adds real behavioral context beyond them: the 92-day window cap, the 20-site ceiling, the one-road-per-call restriction, the coverage boundaries (B/L roads outside the listed Länder and Kreisstraßen are not held; city roadworks only exist for Hamburg, within 3 km), and the standing attribution requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded and dense: purpose first, then triggers, then exclusions, then constraints. It is long and parenthetical-heavy (German sample queries, mixed English/German phrasing), but nearly every clause is actionable routing or constraint information rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description supplies the return shape (section, restriction, dates), the text-vs-structured split (the readable text prints the first 10 and reports the total count), the coverage limits, and the size bounds. An agent has everything needed to decide and call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the parameter docs are unusually rich (date resolution rules, the 92-day cap, the road/place mutual exclusion, the language default warning), so the schema carries the load. The description's contribution is mostly restating the caps ("≤ 92 days, max 20 sites", "ONE road/place per call"), which earns the baseline 3 rather than more.
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 a specific verb ("Returns"), the exact resource (PLANNED roadworks), the coverage universe (one motorway, one B/L/S road in NI/SN/TH/BW, or Hamburg streets by place) and the return fields (section, restriction, dates). An agent can distinguish it from find_poi or check_autobahn_traffic without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states positive triggers ("Use when a date or window is named, it says geplant, or how long a site lasts") and negative ones (Do NOT use when more than one motorway is named, for the situation this minute, or for Baustellen with neither date nor geplant) and routes each exclusion to a named sibling: check_autobahn_traffic and check_road_status. This is textbook when/when-not/alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns rentable shared bikes near a place or coordinate: bike-sharing stations with bikes and free docks now, and free-floating bikes around, with distance and data age (nextbike incl. KVB Rad, MyRadl, VAG_Rad; Donkey Republic). Use when someone asks for a rental or shared bike ("Leihrad", "Fahrradverleih", "nächstes nextbike", "bike share near me"). Do NOT use for parking (find_parking) or a general look around a place (find_nearby). Radius ≤ 5 km, ≤ 20 stations; e-scooters are not covered. Shows each source's attribution.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in WGS 84, e.g. 48.137. Use with lon when the caller already holds coordinates; otherwise use place. | |
| lon | No | Longitude in WGS 84, e.g. 11.576. Use with lat; otherwise use place. | |
| limit | No | How many stations to list, nearest first (1–20, default 8). Free-floating bikes are summarised, not listed one by one. | |
| place | No | Where to look, as free text: a city ("München", "Munich"), a district or Kreis ("Kreis Fulda"), a Bundesland, a station or stop ("Hamburg Hbf"), a motorway junction ("AK Neufahrn"), or a street address with a house number ("Bahnhofstraße 12, 36037 Fulda"). A motorway number alone ("A7") resolves to the road, which has no single point — name a town or junction on it instead. Use this instead of coordinates whenever the person named a place. An address needs its town or postcode — a street and a number alone exist in many towns. Give either place OR lat+lon, never both. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| radius_km | No | Search radius around place or lat+lon in kilometres (0.1–5, default 1). Example: 1 | |
| only_available | No | true (default): list only stations with at least one bike to rent right now. false: also list empty stations, e.g. to find a free dock to return a bike. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuine scope context instead — data age is returned, free-floating bikes are summarised rather than listed, e-scooters are out of scope, and per-source attribution is shown. It does not state refresh cadence or failure behavior, so it falls short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then usage triggers, then exclusions and limits — a sensible priority order with no filler. It is on the long side (multiple parenthetical examples and a trigger-phrase list), which slightly exceeds what an agent strictly needs, but each clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully sketches the return shape — stations with distance and data age, summarised free-floating bikes, per-source attribution. Combined with explicit coverage limits and exclusions, an agent has enough to call correctly, though it omits what happens when no bikes are found in range.
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 parameter docs are unusually strong (place vs lat/lon exclusivity, language defaulting caveat, only_available semantics). The description adds essentially nothing per-parameter beyond restating the radius and station caps already in the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Returns rentable shared bikes near a place or coordinate') and immediately scopes it: bike-sharing stations with bikes/free docks plus free-floating bikes. Names the covered providers (nextbike incl. KVB Rad, MyRadl, VAG_Rad; Donkey Republic), so an agent can distinguish it from every sibling 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?
Explicit when-to-use with trigger phrases ('Leihrad', 'Fahrradverleih', 'nächstes nextbike', 'bike share near me') and explicit when-not-to-use, naming the alternatives (find_parking, find_nearby). It also states hard limits (radius ≤ 5 km, ≤ 20 stations) and an exclusion (e-scooters not covered), 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.
Scheduled departures from any German stop — bus, tram, U-Bahn, S-Bahn, train, ferry. Use when asked when a bus, tram, U-/Stadtbahn or ferry goes ("welche Bahnen" at a Hbf too), or for another DAY or a time over 2 h away: "Wann fährt der nächste Bus ab Fulda Bahnhof?" Do NOT use for a railway station's trains now or later today — get_train_departures. Plan times, with a live delay or cancellation per row where held; regional punctuality check_transit_disruption. No A-to-B journeys: say so, no call. Holds ≥ 48 h ahead, ≤ 3 days; further out, say so. 15 per call. Show the attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| stop | No | The stop, as the person says it: "Fulda, Bahnhof", "München, Marienplatz", "Köln, Hbf", "Hamburg, Rathausmarkt" (town first). Include the town when the person did — half the names in Germany exist in twenty towns, and a bare "Bahnhof" or "Hauptbahnhof" comes back as a list of candidates to choose from, so call it and let the result ask. Pass their words; do not guess an id. Give either stop OR the stop id, never both. | |
| when | No | Start of the window as an ISO-8601 instant with an offset ("2026-10-02T07:30:00+02:00"). Leave it out for "now". Convert the person's words yourself — "morgen früh", "tonight" — and pass the instant; the answer is always rendered in Europe/Berlin. | |
| limit | No | How many departures to return, earliest first (1–15, default 10). The result always says how many more were in the window. | |
| modes | No | Keep only these kinds of service: "bus", "tram", "subway" (U-Bahn), "rail" (every train, including S-Bahn and regional) or "ferry". Omit it unless the person named a kind — "nur Busse", "welche Tram". Several are allowed, which is what "die Busse und Bahnen vor dem Hbf" means. An S-Bahn is "rail": the feed does not always distinguish it, and the line name ("S 6") says which it is. | |
| stop_id | No | The stop's timetable id, exactly as a previous result of this tool gave it ("de:06631:1234"). It skips the name lookup and is exact — use it for a follow-up about a stop this tool has already named, and for one the person picked out of a candidate list. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| duration_min | No | How far past that moment to look, in minutes (5–1440, default 60). Small for "what goes now", a few hours for an evening. To look further ahead (the timetable reaches at least 48 h), move `when` instead of widening this: a window of a whole day returns at most 15 rows and would answer about the wrong half of it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: results carry a live delay/cancellation per row, coverage holds ≥48 h ahead and ≤3 days, 15 rows per call, an attribution line must be shown, and out-of-range requests should be declined rather than attempted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then usage, then exclusions, then constraints — a sensible order. It is dense and peppered with parenthetical German examples and quoted fragments that add length, but each clause carries routing or constraint information. Slightly more cramped than ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must carry the return contract — and it does: per-row live delay/cancellation, a count of further departures in the window, and the attribution line to display. Combined with the window limits and candidate-list fallback for ambiguous stop names, an agent has everything needed to call and present results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so this is largely reinforcement, but the description adds real operational meaning: 'set language on every call' with the failure mode of leaving it defaulted, the advice to move `when` rather than widen `duration_min`, and how bus/tram/rail/ferry map to user phrasing ('nur Busse'). It tops up documented params rather than re-deriving them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Scheduled departures from any German stop') and enumerates covered modes (bus, tram, U-Bahn, S-Bahn, train, ferry), so the agent immediately knows the scope. It also names the sibling it is NOT (get_train_departures), making the boundary unambiguous without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use triggers ("welche Bahnen" at an Hbf, another day, times over 2 h away), an explicit exclusion with the alternative named (railway station now/today → get_train_departures), a pointer to check_transit_disruption for punctuality, and a hard rule for A-to-B journeys ("say so, no call"). This is close to a routing decision table.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the German road rules a visitor needs: low-emission zones (Umweltzone) and which Feinstaubplakette a city requires, speed limits (advisory 130), winter tyres, alcohol, the Sunday lorry ban, tolls (no car toll), Rettungsgasse, what must be in the car, and electric cars (E-Kennzeichen, ad-hoc payment, plugs). Use when someone drives through Germany or asks whether they may enter a city. Do NOT use for live traffic or closures: check_autobahn_traffic; to FIND a charger: find_charging_station. Optional city narrows to its zone. Sourced and dated; show the attribution. Not legal advice.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City the question is about, e.g. "Stuttgart", "München", "Munich". Narrows "lez" to that city's zone and adds the per-city caveat for "ev". Other topics are nationwide. Omit when the question is not about one city. | |
| topic | No | Which rule to answer. "lez" = low-emission zone and Feinstaubplakette, "speed" = speed limits including the Autobahn advisory 130, "winter" = winter-tyre duty, "alcohol" = alcohol and drugs, "toll" = car and lorry toll, "truck_ban" = Sunday and holiday lorry ban, "equipment" = what the law requires in the car, "emergency" = 112/110, rescue lane, breakdown, crash, "ev" = electric car (E-Kennzeichen, charging payment, plugs). Omit for a one-line overview of all nine. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint/idempotentHint already covering the safety profile, the description adds real value: it warns the output is sourced and dated and that attribution must be shown, states it is not legal advice, and flags the language default trap that silently produces a German answer for an English question. It stops short of describing the response structure, so a 4 rather than 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The usage and exclusion guidance is front-loaded and every sentence carries routing or behavioral weight. The long topic enumeration overlaps substantially with the topic enum in the schema, which is redundant bulk, but it is not wasted prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-param, read-only lookup with no output schema, the description covers scope, triggers, exclusions, attribution and the language pitfall. Only the returned shape/form is left unaddressed, which is a minor gap given no output schema exists to describe it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains city scoping, the topic enum values and the language default in detail. The description restates the city narrowing but adds no syntax or behavior the schema lacks; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (returns German road rules) and enumerates the exact subject matter covered, from Umweltzone and Feinstaubplakette to E-Kennzeichen. An agent can distinguish it from traffic, fuel, parking and charger siblings without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger ("when someone drives through Germany or asks whether they may enter a city") and explicit exclusions naming the correct alternatives: check_autobahn_traffic for live traffic/closures and find_charging_station for charger lookups. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Next trains from a German railway station: platform, delay, cancellations. Use when asked when a train, S-Bahn or ICE leaves a named station, or if a train or line from it is late ("RE1 from Köln Hbf late?"); later today ("heute Abend") stays here. A line with no DEPARTURE station ("ist die S1 pünktlich?"; a destination, "nach …"/"zum …", is not one) — check_transit_disruption. Do NOT use for buses, trams, a non-railway stop, another day or a time over 2 h away — get_departures. Train type: categories (ICE/IC/RE/RB/S); no destination filter. ≤ 15 rows, ≤ 120 min. Show the attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| when | No | Start of the window as an ISO-8601 instant with an offset ("2026-09-20T18:30:00+02:00"). Leave it out for "now", which is what almost every question means. Times in the answer are Europe/Berlin whatever you pass. | |
| limit | No | How many departures to return, earliest first (1–15, default 10). More than 15 is refused — that is a board a person can read, not a dataset. | |
| eva_no | No | The station's EVA number (6–8 digits, e.g. 8002549 for Hamburg Hbf), when a previous result gave you one. It skips the name lookup and is exact — use it to answer a follow-up about a station this tool has already named. | |
| station | No | The railway station, as the person says it: "Hamburg Hbf", "Köln Hbf", "Munich Central", "Frankfurt (Main) Hbf". Pass their words — English names and "central station" are understood. If the name fits several stations (a bare "Hauptbahnhof"), call anyway: the result lists them and asks which; do not guess one yourself. Give either station OR eva_no, never both. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| categories | No | Keep only these train types, when the person named one: "ICE", "IC" (also EC, ECE, Railjet, Nightjet), "RE" (also IRE), "RB" or "S" (S-Bahn). "next ICE to …" is ["ICE"], "Fernzug" is ["ICE", "IC"], "Regionalzug" is ["RE", "RB"]. The board then lists only those, so pair it with a longer duration_min. Omit it for "which trains leave". A replacement bus is never a train type. | |
| duration_min | No | How far ahead to look, in minutes (5–120, default 60). Use a small window for "what leaves now" and a larger one for "this evening". Above 120 is refused: a departure board is not a timetable search. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/openWorld/non-destructive, but the description adds real behavioral context beyond them: hard caps (≤15 rows, ≤120 min, 'over 2 h is refused'), the ambiguity-handling behavior (a bare 'Hauptbahnhof' returns a list and asks, so don't guess), the language-default failure mode, and the requirement to show the attribution line. This is disclosure the structured fields do not carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and tightly packed; almost every clause carries routing or constraint information. It is dense to the point of being cryptic in spots (e.g. 'A line with no DEPARTURE station'), but the length is justified by the number of near-miss siblings and edge cases it must disambiguate.
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 tool with no output schema, the description does state the return shape (platform, delay, cancellations, ≤15 rows, attribution line) and all key limits. Minor gaps remain around the not-found/invalid-station failure path and pagination beyond the row cap, but overall it is sufficient to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, and much of the description's parameter text mirrors the schema (e.g. the language/default guidance). It still adds cross-parameter meaning an agent needs: 'Give either station OR eva_no, never both', 'pair [categories] with a longer duration_min', 'no destination filter', and the train-type mapping for colloquial terms.
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?
Specific verb+resource: 'Next trains from a German railway station: platform, delay, cancellations.' It explicitly distinguishes itself from get_departures ('Do NOT use for buses, trams, a non-railway stop, another day or a time over 2 h away') and check_transit_disruption, so an agent can route without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('when a train, S-Bahn or ICE leaves a named station', lateness questions, 'heute Abend' stays here), explicit when-not (buses/trams/non-railway stops/later days/>2 h), and names the two alternative tools with the condition that selects each. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ends a watch this conversation opened with watch_situation, so no further notifications arrive for it. Use when the person no longer needs to be told — "du musst mir nichts mehr zur A8 sagen", "stop watching that charger". No id at hand: pass kind ("weather") and key in the person's words ("A8", "Bamberg", "Kiel"); one match is stopped, several are listed. Do NOT use to look a situation up (call check_road_status), to list what is running (read viafrei://watches), or to cancel anything outside this chat. Another session's watch is never found. Results carry their attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Instead of an id: the watched subject in the person's words, as it was given to watch_situation — a road or place ("A8", "Bamberg"), and with `kind` a place for a weather or charger watch or a stop name for a station watch ("Kiel", "Köln Hbf"), which is resolved the way watch_situation resolved it. The id the watch carries works too. For a station, region, weather or charger watch a key that matches none of them falls back to `kind` alone. Matched against this session's open watches, case and spaces ignored. One match is stopped; several are listed and none is stopped. | |
| uri | No | The watch's resource uri, e.g. "viafrei://watch/12". Give either this or `watch_id`, not both. | |
| kind | No | Instead of an id: the kind of watch the person means, as watch_situation took it ("road", "station", "region", "place", "weather", "charger"). "Turn off the charging alert" is kind "charger" alone. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| watch_id | No | The numeric id of the watch to stop, as `watch_situation` returned it (the 12 in viafrei://watch/12). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only assert readOnly=false/destructive=false/idempotent=false), the description discloses the match-resolution rule (one match stopped, several listed and none stopped), the session-scoping limit (another session's watch is never found), and that results carry an attribution line. These are the behaviors an agent cannot get from the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and its effect, then usage, then exclusions, then fallback behavior. Dense and largely waste-free, though the kind/key enumeration in the prose partially duplicates the schema and the parenthetical example clusters lengthen it.
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 stateful mutation tool with no output schema, the description covers purpose, trigger conditions, alternatives, ambiguous-match handling, cross-session limits, and the attribution of results. An agent has everything needed to call it correctly or choose a sibling instead.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds a genuine decision heuristic for the alternative invocation paths — id vs. kind+key — and notes that the key is matched case- and space-insensitively against this session's open watches. It does not, however, explain anything about `uri` or `language` beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb (ends/stops) and resource (a watch opened by watch_situation) plus the consequence (no further notifications). It explicitly distinguishes itself from watch_situation (create), check_road_status (lookup) and viafrei://watches (listing), so an agent can route correctly without reading any sibling schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to use it with natural-language user examples ("du musst mir nichts mehr zur A8 sagen"), gives explicit negative cases (do NOT look up, list, or cancel outside this chat), and explains the no-id fallback path (kind + key in the person's words) including the ambiguous-match outcome. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Opens a watch so THIS conversation is told when something changes: a road reopening, a stop running late, a weather warning, a charge point turning free. Use when asked to be told later: "sag mir Bescheid, wenn die A8 wieder frei ist", "tell me when a warning comes for Kiel". A name is enough as the key; no lookup first. Do NOT use to look up now, nor for e-mail, SMS or any alert outside this chat — we cannot send one; say so. Set hours (≤ 24, default 3) to cover the time asked about; condition narrows it (only the reopening, one charge point). Session-scoped, ≤ 10 watches. Show attribution.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The thing to watch, in the person's own words — a name is enough and no read tool is needed first; the server resolves it and the answer names the key it resolved to. `road`: a road number ("A8", "B27"). `place`: a town or address ("Fulda"). `weather`: a place name ("Kiel"), resolved to the DWD warn cell it lies in — or a warn cell id ("801002000"); a Land or Kreis is an area and takes no single cell. `station`: a stop or station name ("Köln Hbf", "München, Marienplatz"), resolved to its DHID the way get_departures resolves a stop — or a DHID ("de:14612:28"); an EVA number from get_train_departures ("8000207") is not a DHID and is refused. `charger`: a place ("Würzburg"), resolved to the nearest charging site that reports live occupancy — or a site id from find_charging_station. `region`: an AGS prefix ("14612") from check_transit_disruption. A name that fits several places or stops gets a which-one list and opens no watch; call again with the chosen line. | |
| kind | Yes | What kind of thing to watch. `road` = one motorway or federal road (key: "A8", "B27") — reports a closure or restriction appearing or clearing; `station` = one public-transport stop (key: its name, "Köln Hbf", or its DHID) — reports departures running late past the threshold; `region` = a city or district by AGS prefix (key: "14612") — reports the share of late trips crossing the threshold; `place` = a town or address (key: "Fulda") — reports road restrictions appearing within the radius; `weather` = one DWD warn cell (key: a place name, "Kiel", or the cell id) — reports an official warning coming into force; `charger` = one charging site (key: a place, "Würzburg", or the site id) — reports a point turning free. | |
| hours | No | How long to watch, in hours (default 3, maximum 24). Prefer this over `until`: it needs no knowledge of the current time. Give one of `hours` or `until`, never both. | |
| until | No | An explicit end instant as ISO-8601 with an offset ("2026-09-20T18:40:00+02:00"), at most 24 hours ahead. Use only when the person named a time; otherwise use `hours`. Give one of `hours` or `until`, never both. | |
| language | No | Set this on every call to the language the person is writing in: "en" if they wrote English, "de" if they wrote German. Do not leave it out: it defaults to German ("de"), which is only the fallback when the language is genuinely unclear, so an English question sent without it is answered in German — a wrong answer. Place names, station names and road numbers are never translated in either language; in English the German term is kept in parentheses so the person recognises it on signs and in local apps. | de |
| condition | No | Optional threshold; the keys of each kind, with an example: road {"event": "reopen"} (only the reopening); station {"delay_min": 20}; region {"late_share": 0.3, "delay_min": 5, "min_trips": 20}; place {"radius_km": 10}; weather {"min_level": 3}; charger {"point_id": "2"} (one charge point). Any other key, or a key of another kind, is refused by name; leave it out for the default. The answer repeats the condition it applies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the mutation profile (readOnly=false, idempotent=false, openWorld=false, destructive=false); the description goes well beyond that by disclosing session scoping, a hard cap of 10 watches, the 24h maximum, the default watch length, and an attribution requirement. It also discloses ambiguity handling — a name fitting several places returns a which-one list and opens nothing — which is exactly the kind of behavior an agent cannot infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then usage, then the behavioral caveats, and every clause carries information (limits, attribution, ambiguity, the no-lookup shortcut). The middle is dense with stacked examples, which is slightly crowded but not redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by explaining what a watch reports per kind, how ambiguity and conditions are echoed back, session scope, and the watch cap. For a state-creating tool with a nested condition object, every fact an agent needs before calling it is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already explains key/kind resolution, hours vs until mutual exclusivity, language, and every condition sub-key with examples. The description restates the hours cap/default and that condition narrows the watch, adding a little framing but no syntax beyond what the schema carries. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Opens a watch so THIS conversation is told when something changes' — and enumerates the change types (road reopening, stop late, weather warning, charger free). The closing 'Do NOT use to look up now' cleanly separates it from the large family of check_* / find_* read siblings, so an agent can route correctly without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use with quoted user phrasings ('sag mir Bescheid, wenn die A8 wieder frei ist'), explicit when-not ('Do NOT use to look up now, nor for e-mail, SMS or any alert outside this chat'), and even instructs the agent what to tell the user in that case. It also warns 'A name is enough as the key; no lookup first', heading off the obvious wrong behavior of resolving via a read tool first.
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.
check_autobahn_trafficcheck_road_statuscheck_station_facilitiescheck_transit_disruptioncheck_weather_warningsdescribe_locationfind_addressfind_charging_stationfind_cheapest_fuelfind_fuel_stationfind_hydrogen_stationfind_nearbyfind_parkingfind_placefind_poifind_roadworks_aheadfind_sharingget_departuresget_driving_rulesget_train_departuresstop_watchwatch_situation
Add one secure layer between your agents and this server.