Provides access to Deutsche Bahn train timetable and station data, enabling queries about departures, arrivals, and station information.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ViaFrei Find available EV charging stations near Cologne Cathedral"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
German road, rail, parking, charging and fuel data — live, inside your AI assistant.
npx viafreiWelche Züge fahren als Nächstes ab Hamburg Hbf?
Abfahrten ab Hamburg Hbf (nächste 60 Minuten):
09:45 ICE 519 → München Hbf, Gleis 14, +3 min (ca. 09:48)
09:51 IC 306 → Stockholm Central, Gleis 12, pünktlich
09:51 ICE 707 → Berlin Hbf, Gleis 8A-F, +1 min (ca. 09:52)
… seven more
Stand 09:43 · Quelle: Fahrplandaten: Deutsche Bahn AG, DB API Marketplace,
CC BY 4.0, bearbeitet (…) · Bahnhofsdaten: Deutsche Bahn AG,
DB API Marketplace, CC BY 4.0, bearbeitet (…)Every answer ends with a line like that last one. It is the licence talking, and it is meant to be shown to whoever reads the answer — see Using the data you get back. Reproduce the line the server sends you, not this one: it has been shortened here, and the real one names each source's URL, which the licence requires you to keep.
No account, no API key, no sign-up — ask and the answer comes back.
ViaFrei is in its stabilisation and testing phase at the time of writing: live and free, with some sources thinner than they will be, and the occasional tool that answers slowly or not at all. Tell us when that happens — open an issue with what you asked and what came back. The server necessarily sees the question, and sees it fail; what it cannot see is that an answer was useless to you (see What it does not do).
Plain German or plain English, whichever you speak — the answers come back in the language you asked in, not translated from one house language:
Gibt es gerade Stau auf der A8?
Find a rest area with lorry parking on the A9
Sind auf der A8 Baustellen geplant, wenn ich nächste Woche fahre?
Wo kann ich in Leipzig mit Typ 2 laden?
Gibt es eine Unwetterwarnung für Freiburg?
Brauche ich in Deutschland eine Umweltplakette?
Tell me when the A8 reopens — the server can watch a situation and tell your assistant when it changes, so you need not keep asking. The watch lives in the conversation that opened it: it reaches no inbox and no phone, and it ends with the session. Three hours by default; 24 is the longest one can be asked to run
Thirteen tools at the time of writing, and no list of them on this page. A
pasted catalogue goes stale the first time a description changes on the server,
and this page is frozen inside a published tarball — it cannot be corrected
without a release. So there is one source of truth and it is the running
server: connect any MCP client and call tools/list for the catalogue as it
is today. (https://viafrei.de is the live national traffic digest, not a
catalogue.)
Related MCP server: germany-mcp-server
Node 22 or newer. Nothing to install — npx fetches the bridge when your
client starts it.
Claude Desktop (claude_desktop_config.json). The same three lines fit any
client that takes an stdio MCP server, including the .mcp.json an IDE reads:
{
"mcpServers": {
"viafrei": {
"command": "npx",
"args": ["-y", "viafrei"]
}
}
}Restart the client and ask it one of the questions above. There is no account, no API key and no sign-up.
Probably not — and that is deliberate.
Most MCP clients speak Streamable HTTP and should connect straight to
https://mcp.viafrei.de/mcp. They do not need this package at all.
Clients that speak only the older HTTP+SSE transport do not need it either: the
server answers that transport too, at https://mcp.viafrei.de/sse
(claude mcp add --transport sse). It is deprecated in the specification and
carried so that nobody meets a locked door; prefer the address above.
Some clients still speak only stdio. This bridge is for those — and only those: it runs locally, exposes a stdio MCP server, and relays every request to the public endpoint. It is a transport shim: it holds no data and no credentials, and it makes no decision about any answer.
option | what it does |
| endpoint to relay to. Default |
| extra HTTP header on every request, repeatable. For an API key, when there is one |
| per-request timeout, default 30000. The event stream is never timed out |
| print and exit |
VIAFREI_MCP_URL and VIAFREI_MCP_TIMEOUT_MS do the same for clients that
pass environment variables rather than arguments. A flag wins over the
variable; the variable wins over the built-in default.
There is no self-hosted ViaFrei. The server is a hosted service, so --url
is not a way to run your own — it is there for a proxy or gateway in front of
the service, and for the stub server this repository's test suite starts.
Leave it unset and the bridge goes to the hosted endpoint, which is what you
want.
One line to stderr and an exit code that says what happened. No stack traces:
viafrei: cannot reach https://mcp.viafrei.de/mcp: DNS lookup failed (EAI_AGAIN) - check your network connection; --url only if you relay through a proxyexit | meaning |
| clean shutdown (the client closed stdin, or sent SIGINT/SIGTERM) |
| something else went wrong; the line says what |
| bad usage — a flag or a value the bridge does not accept |
| the endpoint could not be reached, stopped answering, or never answered in time |
| the endpoint answered and this cannot continue: it refused (the line names the HTTP status), it forgot the session, it answered with something that is not MCP, or it redirected to another origin |
| protocol version mismatch; the line names the version the server speaks |
An established session is allowed to wobble — a dropped event stream is a warning, not an exit, and the bridge reconnects. It is not allowed to be dead in silence: several failures in a row with nothing succeeding in between end the process with the code above, so the client that started it finds out.
No telemetry, no analytics, no usage counter, no update check. It writes no
file outside the OS temp directory, and it stores no credential — --header is
passed through to the endpoint and never persisted or logged.
It also does not follow a redirect off the origin you pointed it at. Your headers go to that origin and nowhere else: a cross-origin redirect is refused with one line naming both ends, so a server cannot forward your API key somewhere you did not choose. Same-origin redirects are followed normally.
Every result carries an attribution line. Show it to the person reading the
answer. The full register lives at the resource viafrei://attribution, and
SOURCES.md is the readable version of it: every publisher,
what they cover, the licence, and the exact attribution line to reproduce.
Two constraints matter more than the rest, because getting them wrong is a licence breach rather than a style problem:
MTS-K fuel prices are consumer information only. No redistribution in any form — that includes aggregates, comparisons, price tables and anything derived. Answer the person who asked; do not build a product out of it.
DELFI public-transport data is CC BY-SA 4.0. Share-alike travels with anything derived from it, and it must not be blended into a result under a different licence.
Everything else — where each answer comes from, and what each licence asks of you — is in SOURCES.md. See also NOTICE and LICENSE.
The MCP server is offered as a hosted service, and its source is closed. It
is not in this repository and is not published. What is public is the part that
is meant to be: the tool names, their descriptions, their input schemas, the
shape of the results and the attribution lines — everything a client reads from
tools/list, which is the product surface.
This is said plainly so nobody spends an evening looking for the server code.
Yes, please — see CONTRIBUTING.md. Issues and discussions are open. The bridge is small and self-contained, which is exactly what makes it a reasonable thing to send a first patch to.
Never open a public issue for a key, a token or anything that looks like one. See SECURITY.md for the private reporting path.
Apache-2.0 for this code. Data obtained through the server keeps its provider's licence — see NOTICE.
Returns jams, slow traffic, closures and roadworks in force this minute on up to 5 German motorways, with delay and speed. Use when the question is about the road now: Stau, a delay, how it looks, or which closures are reported; name every motorway (Munich→Berlin: A9). Do NOT use for whether a road is open or passable — check_road_status at any clock — nor a closure with no time word or a later one (tonight, the weekend); for Baustellen dated or geplant — find_roadworks_ahead; nor city streets, fuel (find_cheapest_fuel) or 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 ("ist auf der A5 in diesem Moment eine Vollsperrung gemeldet?", "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). Roads keep the order you listed them; within a road, jams come first, then closures and roadworks. | |
| 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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 readOnly, idempotent, non-destructive. The description adds that data is '~5 min old' and instructs to 'Show the attribution line.' It also notes pagination via cursor and result ordering, which are behavioral details not in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loads the core function in the first sentence and structures usage guidance clearly. Every paragraph serves a purpose, though the extended explanation of the 'kinds' parameter inside the main description could arguably be moved to the schema (it's already there) but it's still valuable for the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the absence of an output schema, the description covers the main function, usage boundaries, parameter nuances, freshness, and attribution requirement. It gives enough for an agent to invoke correctly without needing to inspect the schema in depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds substantial context, especially for the 'kinds' parameter, explaining when to set it based on the subject of the question and the default behavior. It also clarifies the 'roads' parameter's requirement to list all motorways on a route. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise statement: 'Returns jams, slow traffic, closures and roadworks in force this minute on up to 5 German motorways, with delay and speed.' It names the specific resource and scope, and immediately distinguishes from siblings like check_road_status and find_roadworks_ahead.
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 ('Use when the question is about the road now') and when-not-to-use, naming each alternative tool (check_road_status, find_roadworks_ahead, find_cheapest_fuel, get_train_departures). It even provides examples of question phrasing that selects this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns whether one German motorway or federal road is open, closed or restricted, now and in the coming days. Use when the question is whether the road is open or passable — "ist die A8 offen", "ist die A8 in diesem Moment gesperrt", "komme ich durch" — at any clock, plus closures tonight, at the weekend or with no time word. Do NOT use for jams and delays, a whole multi-motorway route, or what is reported on a motorway this minute — call check_autobahn_traffic; for roadworks over a date window — find_roadworks_ahead. One road per call, ≤ 14 days, ≤ 11 entries. 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. | |
| road | No | One German motorway or federal road, e.g. "A8" or "B27". "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. Give exactly one of road, place, or lat+lon. | |
| limit | No | Maximum entries to return (1–11, default 10). Closures come first, then restrictions in force, then planned works. | |
| 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 ("A7"), or a street address with a house number ("Hauptstraße 12, 36037 Fulda"). 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: live closures are always included regardless of horizon_days, closures come first in the ordering, and the attribution line must be shown. It doesn't describe the exact return format, but with no output schema and read-only semantics, the added context is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: the core purpose is front-loaded, followed by usage examples, exclusions, and constraints. Every sentence earns its place. It is longer than the HIGH calibration example, but the tool has 7 parameters and multiple sibling distinctions to cover, so the length is justified. A small deduction for the slightly run-on structure of the first sentence.
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 tool with 100% schema coverage, no output schema, and no nested objects, the description covers the key operational details: when to use it, when not to, parameter semantics, constraints, and the attribution requirement. It doesn't describe the exact response shape, but with no output schema and read-only annotations, that is a minor gap. The description is complete enough for an agent to select and 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 baseline is 3. The description adds value beyond the schema by explaining the relationship between road and the planned-works data ('it is the only input that reaches the planned-works data'), giving concrete horizon_days mappings (0 for right now, 1 for tonight, 3 for weekend, 7 for next week), and clarifying that a bare question should omit the argument rather than read it as 0. This goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Returns whether... open, closed or restricted') and a specific resource (one German motorway or federal road), with concrete example queries. It also explicitly distinguishes itself from siblings by naming what it is not for, so an agent can tell it apart from check_autobahn_traffic and find_roadworks_ahead without opening their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance with example phrasings, and explicit when-not-to-use guidance naming the alternative tools ('Do NOT use for jams and delays... call check_autobahn_traffic; for roadworks over a date window — find_roadworks_ahead'). It also states constraints like one road per call, ≤14 days, ≤11 entries, and the attribution line requirement. This is exemplary routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report whether a German railway station's lifts and escalators are working right now: each one, where it is, its state (in service / out of service / unknown) and the operator's own explanation. Use when someone asks about step-free access or a broken lift — "Funktioniert der Aufzug am Kölner Hauptbahnhof?", "is the lift at Hamburg Hbf working?", "Rolltreppe kaputt?", travelling with a wheelchair, a pram or 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, as the person says it: "Köln Hbf", "Hamburg Hbf", "Munich Central". 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond these: it caps results at 50, states that out-of-service facilities are listed first, and notes that results carry an attribution line. This extra information helps set expectations for ordering and attribution, which is useful. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is slightly long but well-organized: it starts with the core purpose, then gives usage examples, exclusions, and a final behavioral note. It is front-loaded with the most critical information and each sentence contributes to clarity. It could be tightened slightly without losing meaning, but it is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema), the description covers the essential aspects: what it reports (state, location, explanation), when to use it, when not to use it, and a key behavioral detail (ordering and cap). The parameter descriptions handle the rest. Nothing critical is missing for an agent 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?
The input schema has 100% coverage with detailed descriptions for all 5 parameters, so the baseline is 3. The description itself does not add significant parameter-level detail beyond the schema; it mentions the 50-facility cap and ordering, but these are already covered in the limit parameter description. The description adds minimal value over the schema for parameter understanding.
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: 'Report whether a German railway station's lifts and escalators are working right now.' It clearly distinguishes itself from the sibling get_train_departures by explicitly naming that tool for train times, platforms, and delays. The scope (German stations, lifts/escalators) is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is explicitly defined: 'Use when someone asks about step-free access or a broken lift' with concrete examples in multiple languages. It also gives a clear exclusion: 'Do NOT use for train times, platforms or delays — call get_train_departures.' This leaves no doubt about when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns how punctual public transport is right now in one German region: the share of distinct trips more than 5 minutes late at least once, trips with a cancelled stop, the trend against the previous window, and how many trips that rests on. Use when the user asks whether buses and trains are running normally, or whether a strike or storm is disrupting local transport. Do NOT use for one line, trip or station — per-line realtime is not available; the region's figures are the answer. Region-wide aggregates only; window ≤ 120 minutes. CC BY-SA 4.0: show the attribution line to the user.
| 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") or a Kreis ("Landkreis Fulda"). 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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?
The description adds substantial behavioral context beyond the readOnlyHint annotations: the exact lateness threshold (5 minutes), what counts as a cancelled stop, the trend comparison window, and the sample size. It also discloses the CC BY-SA 4.0 attribution requirement)Skip to user. These are meaningful operational details an agent would otherwise not know.
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 about four sentences and every sentence earns its place: what it returns, when to use it, when not to use it, and a required attribution. The most important scope and comparison details are front-loaded, with the licensing note cleanly at the end.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description sufficiently explains the returned information (punctuality share, cancelled stops, trend, trip count). The parameter schema covers invocation details, and the description fills the usage and exclusion gaps. Nothing essential is missing for an agent to decide and 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 schema already fully documents lat, lon, region, language, and window_min. The description adds some reinforcing context (region-wide aggregates, window ≤ 120 minutes, trend interpretation) but does not materially expand parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Returns') and names the exact resource ('public transport punctuality in one German region') plus the concrete metrics: share of trips more than 5 minutes late, cancelled stops, trend, and trip count. It also differentiates itself from line/station-level tools by explicitly stating that per-line realtime is not available.
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 clear positive triggers: 'when the user asks whether buses and trains are running normally, or whether a strike or storm is disrupting local transport.' It also gives explicit negative guidance: do not use for one line, trip, or station, and notes that region-wide aggregates are the only answer. This effectively routes an agent away from inappropriate uses.
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 or coordinate — storm, snow, ice, heavy rain, thunderstorm, heat — with the DWD's own Warnstufe 1–4, the area, the local validity window and the official text unaltered. Use when someone asks about weather for a trip, whether it is safe to drive somewhere, or about storm, snow or ice warnings. Do NOT use for a plain forecast (not offered: warnings only) or for closures and jams (call check_autobahn_traffic). Says so when the data is not current instead of reporting an all-clear. Show the result's attribution line to the user.
| 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 ("A7"), or a street address with a house number ("Hauptstraße 12, 36037 Fulda"). 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: it will say when data is not current rather than falsely reporting an all-clear, returns official text unaltered, and requires showing the attribution line. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: result, when to use, when not to use, freshness behavior, and attribution. It front-loads the core purpose and then flows naturally into routing and parameter nuance without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining return contents and it does so explicitly: warning types, Warnstufe, area, validity window, and unaltered official text. Combined with parameter semantics, freshness fallback, and sibling routing, an agent has everything needed to invoke 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 schema carries most parameter meaning. The description nevertheless adds practical guidance beyond the schema, especially for language ('set it on every call', 'an English question answered in German is a wrong answer') and min_level ('raise ONLY when the question names a level', 'Unwetter is not a filter'). This elevates it above the baseline.
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 ('returns'), a concrete resource (official DWD weather warnings in force), and the exact scope (place or coordinate, Warnstufe 1–4, area, local validity window, official text). It clearly names sibling tools it is not, such as check_autobahn_traffic, preventing agent confusion.
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 triggers ('weather for a trip', 'whether it is safe to drive', 'storm, snow or ice warnings') and equally explicit when-not-to-use instructions ('Do NOT use for a plain forecast', 'for closures and jams call check_autobahn_traffic'). This is the strongest possible routing guidance.
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 charging sites 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 ("A7"), or a street address with a house number ("Hauptstraße 12, 36037 Fulda"). 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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 asks for fast charging or names a number: 50 = DC fast, 150 = HPC, 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 mark the tool as read-only, idempotent, and non-destructive; the description adds non-obvious behavior: availability is missing for most operators and must be treated as unknown rather than free, and the caller must show the attribution line. These caveats materially affect how an agent should interpret and present results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: core deliverable, when to use, explicit exclusions, and operational caveats. The most important information is front-loaded, with 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?
For a 9-parameter tool with no output schema, the description plus schema covers what an agent needs: return fields, selection criteria, anti-selection, constraints, data caveats, and required attribution. Exact response formatting is not necessary for correct invocation.
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 input schema already documents all 9 parameters in detail. The description adds only cross-cutting caveats (radius/limit caps, availability semantics) but no new per-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?
The first sentence names the exact deliverable — EV charging sites near a place or coordinate — and lists the key fields returned (operator, connector types, max power, price, live availability). This is a specific verb-resource pairing that easily distinguishes it from find_cheapest_fuel and find_parking.
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 triggers with real query examples ('Wo kann ich laden?', 'CCS 150 kW near Leipzig') and explicit when-not-to-use routing to find_cheapest_fuel for petrol/diesel and get_driving_rules for E-Kennzeichen/Ladekarte rules. It also states hard constraints like radius ≤ 25 km and ≤ 10 sites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the cheapest petrol stations for one fuel grade around a place or coordinate, with price per litre, brand, address, distance and open state. Use when the user asks where to fill up, what fuel costs nearby, or for a cheap stop on a drive. Do NOT use for charging an electric car (call find_charging_station), for price history, or for motorway traffic (call check_autobahn_traffic). Radius ≤ 25 km, at most 10 stations. The result names the age of any price over an hour old. Prices are for consumer information only; the result's attribution line and the MTS-K note must be shown to the user.
| 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 ("A7"), or a street address with a house number ("Hauptstraße 12, 36037 Fulda"). 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond that: a hard radius cap of 25 km, a station cap of 10, that prices over an hour old are flagged, and that the attribution line and MTS-K note must be shown. These are concrete operational constraints that materially affect how an agent uses the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences of core purpose and guidance followed by constraints, all front-loaded with the most important information first. There is no filler or repetition of schema details; every sentence adds unique value, making it dense but efficient.
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?
Despite having no output schema, the description outlines what the result contains (price, brand, address, distance, open state, price age) and notes the attribution requirement. All operational constraints (radius, limit, language) are covered, and the parameter schema is fully documented. An agent has everything needed to call the tool correctly and interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with thorough per-parameter explanations, so the baseline is 3. The description adds practical selection guidance that goes beyond the schema: it emphasizes matching the fuel grade to the driver's vehicle ('a diesel driver is not helped by a petrol price') and mandates setting the language to the user's language to avoid wrong-language answers. These enrich the meaning of the fuel and language parameters beyond their basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Returns the cheapest petrol stations for one fuel grade around a place or coordinate,' and lists the exact data fields (price per litre, brand, address, distance, open state). It also differentiates from siblings by explicitly excluding charging and traffic use cases, making its scope unambiguous.
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 provides explicit when-to-use guidance ('Use when the user asks where to fill up, what fuel costs nearby, or for a cheap stop on a drive') and when-not-to-use guidance with named alternatives ('Do NOT use for charging an electric car (call find_charging_station)... for motorway traffic (call check_autobahn_traffic)'). This leaves no inference needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns parking near a place, a coordinate or along one motorway: rest areas with lorry spaces, car parks and park-and-ride sites, with total spaces and, where published, how many are free now and that reading's age. Use when someone asks where to park, stop, rest or leave the car for the train ("Parkhaus in Köln", "Rastplatz A3", "P+R"). Do NOT use for fuel — call find_cheapest_fuel — or for charging an electric car — call find_charging_station. Radius ≤ 25 km, ≤ 10 sites. No "free now" means the operator publishes no count, not that it is full. Every answer carries 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: "rest_area" = motorway rest and service area (no feed we ingest classifies this category at all, so an answer filtered to it says so and names the parking we do hold), "car_park" = public car park (Parkhaus/Parkplatz), "park_and_ride" = P+R beside a station, "truck" = lorry parking, "any" = all of them. Default "any". Pass a kind only when the person named one — "Rastanlage"/"Raststätte" is "rest_area", 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 the five: 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. | |
| 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 ("A7"), or a street address with a house number ("Hauptstraße 12, 36037 Fulda"). 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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 insists on somewhere with free spaces 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 declare readOnly=true, idempotent=true, and non-destructive, so the safety profile is covered. The description goes further by disclosing semantic nuance: 'No "free now" means the operator publishes no count, not that it is full', the radius/site limits, and that every answer carries source attribution. This is exactly the kind of behavioral context that helps an agent interpret results correctly.
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 a single, well-structured paragraph that front-loads the core behavior before usage guidance, exclusions, limits, and sentinel semantics. Every sentence earns its place; there is no filler or repetition of structured fields. The only minor style trade-off is paragraph length, but it remains efficient given the number of behavioral caveats.
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 adequately explains the return concept: facility kinds, total spaces, live free-count when published, age of that reading, and attribution. Combined with 100% schema coverage of all 9 parameters, required-parameter clarity, and sibling routing, an agent has everything needed to select and invoke this 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 itself carries the full parameter documentation burden. The tool description adds only global constraints already echoed in the schema (radius ≤ 25 km, ≤ 10 sites) and does not need to compensate for missing parameter explanations. Baseline 3 is appropriate because the description adds no significant parameter-level meaning beyond 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 opens with a specific verb and resource: 'Returns parking near a place, a coordinate or along one motorway', and enumerates the facility types and data returned. It also names sibling tools to exclude ('Do NOT use for fuel — call find_cheapest_fuel — or for charging an electric car — call find_charging_station'), so agents can distinguish it from alternatives without even opening their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: 'Use when someone asks where to park, stop, rest or leave the car for the train', with concrete example queries. It also states clear exclusions and redirects to sibling tools for fuel and EV charging. The schema descriptions further encode routing rules like preferring place over coordinates and never combining road with coordinates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the roadworks PLANNED on one German motorway inside a date window: the section and direction as published, what is restricted, and the start and end. Use when a date or window is named, the question says geplant, or someone asks how long a site lasts ("Baustellen auf der A7 in den Sommerferien?"). ONE road 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 — call check_road_status. ≤ 90 days, max 20 sites. Show the attribution line.
| 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 90 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 | Yes | The Autobahn to look at, one per call, e.g. "A7" or "A100" — "A7", "A 7" and "a7" are the same road. Bundesautobahnen only: this feed carries no Bundesstraßen and no city streets. Ask again for a second motorway. | |
| 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. | |
| 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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 supply readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds valuable behavioral context: the planned-not-current nature, the one-road-per-call constraint, ≤90-day and max-20-sites limits, and the requirement to show the attribution line. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence carries distinct value: return contents, usage triggers, exclusions with alternatives, hard constraints, and attribution. It is front-loaded with purpose and contains no filler or redundancy despite being longer than a typical description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, this description covers selection criteria, exclusion rules, constraints, return contents, and attribution. An agent has enough to choose the tool correctly and invoke it with appropriate parameters, especially with the rich parameter descriptions already in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description mentions high-level constraints (one road per call, ≤90 days, max 20 sites) but does not add per-parameter explanation beyond what the schema already provides for from/to/road/limit/language.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact verb-resource pair: 'Returns the roadworks PLANNED on one German motorway inside a date window', and enumerates the specific result fields (section, direction, restriction, start/end). It also explicitly contrasts with sibling tools check_autobahn_traffic and check_road_status, so an agent can distinguish it 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?
Provides explicit when-to-use conditions ('when a date or window is named, the question says geplant, or someone asks how long a site lasts') and when-not-to-use conditions with named alternatives ('all three are check_autobahn_traffic; whether a road is open — call check_road_status'). This is textbook 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 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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 idempotentHint=true, so the agent knows it is a safe read. The description adds valuable behavioral context beyond that: results are sourced and dated and the attribution must be shown, the tool is not legal advice, and the city parameter behaves differently per topic (narrows lez, adds a per-city caveat for ev, while other topics stay nationwide). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place. It front-loads the purpose and topic list, then gives usage rules, exclusions, city behavior, language guidance, and sourcing. It is structured and scannable, though a bit dense. It could be slightly tighter, but it is far from bloated given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 topics, no output schema, and sparse annotations, the description covers everything an agent needs: what it returns, when to use it, when not to, how the city parameter modifies results, the mandatory language setting, and the need to show attribution and note it is not legal advice. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds extra meaning on top of the schema: for 'city' it explains that it narrows only the 'lez' topic and adds a caveat for 'ev' while other topics are nationwide; for 'language' it stresses that the default is only a fallback and must be set to the user's language, and it explains translation behavior (German terms kept in parentheses). These details go beyond the schema's property descriptions, so a 4 is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise statement: returns German road rules a visitor needs, then enumerates the exact topics (low-emission zones, speed limits, winter tyres, etc.). It names the resource (German road rules) and clearly differentiates from siblings by explicitly excluding live traffic and charger lookups, so an agent can tell this apart without reading other 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 use cases ('Use when someone drives through Germany or asks whether they may enter a city') and explicit non-use cases with named alternatives ('Do NOT use for live traffic or closures: check_autobahn_traffic; to FIND a charger: find_charging_station'). It also explains the optional city parameter narrows results and that the language parameter must be set to match the user's language, with a fallback rule. This is fully actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the next departures from a German railway station: time, line, destination, platform, delay and cancellations. Use when someone asks when their train, S-Bahn or ICE leaves, whether it is late, or what is leaving a station now — give the station name as the person said it ("Hamburg Hbf", "Munich Central"); an ambiguous name comes back as a list. Do NOT use for buses or trams (punctuality: check_transit_disruption), for tickets, fares or journey planning, or for motorway traffic — call check_autobahn_traffic. At most 15 departures, window 120 min. Results carry their 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 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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 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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), and the description adds genuinely non-obvious behaviors on top: ambiguous station names are returned as a list rather than guessed, results carry an attribution line, and hard caps of 15 departures / 120-minute window are stated in prose. There is no contradiction with 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?
Four sentences, every one earning its place: purpose and payload fields, when-to-use triggers, exclusions with named alternative tools, then hard limits plus attribution. The core action is front-loaded in the first clauseheb about and the exclusions arrive before any parameter or schema detail.
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 departure-board tool, the description covers selection triggers, exclusions, naming and ambiguity rules, limits)Skipick and attribution, while annotations and rich in-schema docs handle the safety profile and all 6 optional params. The one gap: there is no output schema and the description gives only a flat field list ('time, line, destination, platform, delay and cancellations') without stating edge-case behavior such as an empty result set or an unknown station name.
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 in-schema parameter descriptions are already rich (eva_no for follow-ups, language-set-on-every-call rationale, 'do not guess' for station). The tool description adds little new parameter meaning: 'At most 15 departures, window 120 min' merely restates the schema maximums)Skip and the station-naming rule paraphrases the station parameter's schema text. The baseline 3 for high coverage 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?
Opens with a specific verb and resource: 'Return the next departures from a German railway station', and itemizes the payload (time, line, destination, platform, delay and cancellations). It also carves out what it is not — not buses/trams and not motorway traffic — so an agent can tell it apart from check_transit_disruption and check_autobahn_traffic without opening their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit triggers ('when their train, S-Bahn or ICE leaves, whether it is late, or what is leaving a station now') followed by a hard Do-NOT list with named alternatives (check_transit_disruption for buses/trams, check_autobahn_traffic for motorway) and exclusions (tickets, fares, journey planning). It even states the station-input convention (pass the name as the person said it; ambiguous names come back as a list). 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 change 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". When they name the subject and not an id, take the id from viafrei://watches. 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 — there is nothing subscribed elsewhere. A watch id from another session is not found, never stopped. Results carry their attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| uri | No | The watch's resource uri, e.g. "viafrei://watch/12". Give either this or `watch_id`, not 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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?
Annotations only provide negative hints, so the description carries the disclosure burden. It adds meaningful behavioral detail: the watch is scoped to this conversation, stopping it prevents further notifications, cross-session watch ids are not found and never stopped, and results carry an attribution line. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence front-loads the core action, and the following sentences each earn their place by covering usage triggers, exclusions, and edge cases. It is dense but well-organized; the only slightly cryptic part is the closing line about the attribution line.
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 narrow stop-watch action, the description covers the key aspects: what the watch is, when to stop it, how to resolve an id, and what does not work. With no output schema, the mention of 'Results carry their attribution line' is vague, but it is a minor gap for this simple 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 coverage is 100% and the parameter descriptions are already thorough, giving a baseline of 3. The description adds useful resolution guidance: when the user names a subject instead of an id, the agent should take the id from viafrei://watches. This goes beyond the schema's field-level documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Ends a watch this conversation opened with watch_situation'. It clearly distinguishes this from sibling tools like watch_situation and check_road_status, so an agent knows exactly what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('when the person no longer needs to be told'), gives concrete examples, and lists what not to use it for with named alternatives: check_road_status for lookups and viafrei://watches for listing. It also excludes cancelling anything outside this chat.
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 starting, a charge point turning free. Use when the person asks to be told later: "sag mir Bescheid, wenn die A8 wieder frei ist", "tell me when a charger is free". Do NOT use to look something up now (call check_road_status, check_autobahn_traffic or find_charging_station), and do NOT use when an e-mail, SMS or any alert outside this chat was asked for — we cannot send one; say so. Session-scoped. At most 10 watches, 24 h each. Results carry their attribution line.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The thing being watched, in the vocabulary of `kind`: a road number, a stop id, an AGS prefix, a place name, a DWD warncell, a charging site id. For `road` and `place` it is the person's own words — "A8", "B27", "Fulda" — and needs no lookup. For `station`, `region`, `weather` and `charger` it is an identifier, and it must be the one the matching read tool returned (get_train_departures, check_transit_disruption, check_weather_warnings, find_charging_station): look it up first, because a key nothing matches produces a watch that is simply never triggered. | |
| 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 by its DHID (key: "de:14612:28") — 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` = a DWD warncell (key: "105315000") — reports an official warning coming into force; `charger` = one charging site (key: the site id from find_charging_station) — 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 because it has a default — the default is only the fallback when the language is genuinely unclear, and an English question answered in German is 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. Each key belongs to ONE kind and a key that does not belong to the chosen kind is refused by name; leave it out to use that kind's default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only negative hints (readOnlyHint: false, idempotentHint: false), so the description carries the behavioral burden. It adds genuinely useful facts: watches are session-scoped, capped at 10 and 24 hours each, cannot be delivered outside the chat, and results carry an attribution line. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet complete: six sentences, with the core purpose front-loaded and each subsequent sentence adding a distinct fact—examples, exclusions, limits, delivery constraint, and result attribution. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex six-parameter tool with a nested condition object, the description plus full schema covers invocation, routing, exclusions, and operational limits. However, there is no output schema and the description only hints at results with 'attribution line', leaving the return/confirmation semantics slightly under-specified.
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 and the schema already documents every parameter, including kind-specific key syntax, defaults, and the hours/until mutual exclusion. The description contributes user-phrase examples but no additional parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific action ('opens a watch') and the exact resource ('THIS conversation is told when something changes') plus concrete examples: road reopening, stop running late, weather warning, charge point free. It also distinguishes itself from lookup siblings by explicitly saying it is not for immediate checks.
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 guidance ('asks to be told later') with verbatim user-phrase examples, and explicit when-not-to-use guidance: immediate lookups, naming sibling tools, and out-of-chat email/SMS alerts with the required fallback response. This is model-level routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.0.9check_autobahn_trafficcheck_road_statuscheck_station_facilitiescheck_transit_disruptioncheck_weather_warningsfind_charging_stationfind_cheapest_fuelfind_parkingfind_roadworks_aheadget_driving_rulesget_train_departuresstop_watchwatch_situationScored across 13 tools
Each tool addresses a distinct need: traffic jams, fuel prices, parking, road status, planned roadworks, charging, driving rules, transit disruption, weather warnings, train departures, station facilities, and watch management. Even similar tools like check_autobahn_traffic and check_road_status have clearly delineated scopes with explicit 'do not use' guidance.
Tool names follow a predictable verb_noun pattern (check_, find_, get_), but there is some mixing: watch_situation and stop_watch use different conventions, and get_driving_rules contrasts with check_* tools. The naming is still readable and each verb hints at the action type (check = status, find = locate, get = retrieve).
13 tools is well within the ideal range for a comprehensive travel assistant. Each tool covers a specific facet of German travel (roads, fuel, parking, transit, weather, stations, watches) without redundancy or unnecessary additions.
The tool set covers the full lifecycle of travel-related queries: real-time traffic, road status, planned works, fuel, parking, charging, driving rules, transit disruptions, weather warnings, train departures, station accessibility, and even proactive monitoring via watches. No obvious gaps for the stated domain; exclusions are explicitly noted (e.g., no forecast, no per-line transit).
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Keyless open data for 84 German cities: 12 lean read-only MCP tools covering 67 data types.
GovData.de MCP — Germany's national open-data portal (CKAN API).
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
