Spick Me — Swiss public transport

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

Beyond the read-only/idempotent annotations, the description discloses the important caveat that times are planned timetable times without live delays or cancellations, and that an ambiguous name returns candidates rather than guessing. It does not mention rate limits, auth needs, or result ordering, but the freshness caveat is the key behavioral fact an agent needs.

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, then inputs, then caveats and an example. The input paragraph is dense with useful detail rather than filler, though it is longer than strictly necessary and repeats the 1–40/default range already in the schema.

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?

An output schema exists, so return format need not be explained. The description covers what the tool does, when to use it versus plan_journey, all input formats, time semantics, and the planned-vs-live data caveat — everything needed to invoke 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%, yet the description adds substantial meaning: accepted station formats (name, address, named place, 'geo:lat,lon', find_place place_id), the nearest-stop fallback for addresses/coordinates, and time interpretation rules (ISO 8601, offsets converted, bare '08:00' means today/tomorrow, omit for now). This goes well past the schema's terse field descriptions.

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

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

The description names a specific verb and resource ('List the next departures from one station or stop') and immediately contrasts itself with the sibling plan_journey. It also defines scope (one station, next departures) which distinguishes it from reachable_area and travel_time_matrix.

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 concrete user phrasings ('what leaves from Bern in the next hour', 'when is the next tram from Bellevue'), states an alternative use case for discovering service frequency, and explicitly routes the 'getting somewhere specific' case to plan_journey. When-to-use and when-to-use-something-else are both stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description is free to add the genuinely useful behavior: results are ranked best-first, each carries a stable place_id, and an ambiguous name returns candidates rather than a guessed single answer. It stops short of describing error handling or result shape, but the output schema covers returns.

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 the purpose, then usage, then a labelled Inputs section and a worked example, so an agent can skim to what it needs. Slightly verbose in places ('Names are read the way a rider types them') but 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 an output schema present, the description need not explain return values, and it supplies everything else an agent needs: when to call it, when not to, accepted input formats, tie-breaking via near, and an end-to-end example showing the place_id flowing into plan_journey.

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 goes beyond the schema's terse 'The name, address or coordinate to look up' by enumerating accepted query forms with real examples ('geo:47.3769,8.5417', 'stop:8503000') and clarifying that limit is 1-10 with default 5.

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

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

States a specific verb and resource ('look up what a place name means in the Swiss public-transport network') and enumerates the resource types it covers: stations/stops, street addresses, named places, coordinates, place_ids. This clearly separates it from plan_journey, departures, and the other routing siblings.

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

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

Gives explicit triggers ('when the user names a place you are not sure of', 'when another tool answered that a name is ambiguous', 'to get coordinates') and an explicit non-trigger ('You do not need it before plan_journey or departures for ordinary names'), even explaining why those siblings handle names themselves.

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

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

Annotations cover the safety profile (read-only, idempotent, non-destructive, closed-world), and the description adds behavior they cannot: ambiguous place names return candidates rather than a guess, end defaults to start making a round trip, departure defaults to now, and a bare '08:00' is interpreted as today. It also notes each leg carries a picture_url. That is meaningful operational context beyond 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 purpose, then routing, then input semantics, then an example — a sensible order with no filler sentences. It is on the long side, and the extensive start-format enumeration overlaps schema documentation, but each block carries usable 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?

An output schema exists, so return-value explanation is not required, and the description still notes the per-leg picture_url. Combined with defaults, disambiguation behavior, and the worked JSON example, an agent has everything needed to construct a correct call.

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 goes further than the schema on several parameters: it enumerates the accepted forms for start (station name, address, named place, 'geo:lat,lon', place_id from find_place), restates the 1–12 stop limit, and clarifies leave_at's night-away semantics. It omits transfer_time_factor, which only the schema documents, so it does not fully compensate.

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 ('Plan a whole day of public transport with time spent at each stop') and unpacks what a day plan contains — outbound train, stay, connection, return — which is a distinct capability from a point-to-point planner. It explicitly contrasts itself with plain journey planners and with the sibling plan_journey, so an agent can separate the two 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 concrete use cases (multi-stop day trip, three towns in a day, evening out and back) and an explicit exclusion: 'For a single A-to-B trip, use plan_journey.' The when-to-use and when-not-to-use conditions are both stated outright.

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

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

Beyond the readOnly/idempotent annotations, it discloses non-obvious behaviors: ambiguous names return candidates rather than a guess, via reduces output to one best journey, and results are planned timetable times with Swiss offsets with no live delay data — with the instruction to say so when it matters. It also explains the picture_url artifact and when to offer it. 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?

Front-loaded with purpose and usage, then inputs, then a single example — a logical order with no wasted sentences. It is on the long side and the picture_url sentence borders on promotional, but each paragraph carries information the agent needs.

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 an eight-parameter planning tool with an output schema, the description covers everything an agent must know to call it correctly: formats, time semantics, mutual exclusions, alternatives limit, and the absence of real-time data. Return-value detail is legitimately delegated to the output 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 coverage is 100%, so baseline is 3, but the description adds real value beyond the schema: accepted input formats for from/to (station, address, named place, 'geo:lat,lng', 'stop:8503000'), the departure/arrival mutual exclusion, ISO 8601 Swiss local time with offset conversion, and the bare '08:00 means today' rule. Only transfer_time_factor is left to the schema alone.

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

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

The description opens with a specific verb+resource ('Find the best connections by train, tram, bus, boat and mountain railway between two places in Switzerland') and names the data source (Spick Me's routing engine over the official Swiss timetable). This is clearly distinguishable from siblings like travel_time_matrix, reachable_area and plan_day_out, which it also explicitly routes away from.

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 concrete triggering phrases ('how do I get from A to B', 'I need to be in Bern by 9') and an explicit exclusion: to stop somewhere along the way, use plan_day_out instead. It also tells the agent how to obtain a place_id (find_place) and what an ambiguous name does (returns candidates, no guessing).

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds material behavior: results are timetable minutes on the planned timetable with live delays excluded, an address or coordinate is snapped and the answer names the stop, and an ambiguous name returns candidates rather than guessing. These are exactly the traits an agent cannot infer 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 core behavior and the routing alternatives before the input detail, and a worked example closes it usefully. It is on the long side and the parenthetical asides could be tightened, but each sentence 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?

An output schema exists, so return-value explanation is unnecessary, and the description nonetheless covers the behavior an agent needs: defaults (60 minutes, 50 results), waiting included in the budget, and the timetable-only caveat. Complete for a six-parameter read 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%, so the baseline is 3, but the description adds real value beyond the schema: accepted 'from' formats (station name, address, named place, 'geo:lat,lon', 'stop:8503000' place_id), ISO 8601 departure semantics including offset conversion and the bare '08:00' meaning today. It omits transfer_time_factor, which the description never mentions, so it is not fully additive.

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 (list) and resource (every station/stop reachable) with scope and ordering ('nearest first, with the earliest arrival at each'). It explicitly distinguishes itself from travel_time_matrix and plan_journey, so an agent can route correctly without opening schemas.

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

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

Gives concrete user-intent examples ('where can I get to from Bern in 45 minutes', catchment areas, isochrones) and names the alternatives with the condition that selects them ('for travel time between specific places use travel_time_matrix; for how to make a particular journey, plan_journey'). 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.

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds real operational context: one search per origin regardless of destination count (cost shape), ambiguous names return candidates rather than guessing, addresses/coordinates are snapped to their nearest stop, planned timetable only with no live delays, and null where no connection exists.

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

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

Front-loaded with the core operation, then cleanly segmented into usage, inputs, output, and a worked example. Dense and well organized, though the illustrative 'which office site / which flat / how well a venue is connected' clause is mildly redundant with the preceding 'built for comparing locations'.

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 5-parameter, open-world, computed tool with an output schema, the description still supplies the return semantics (minutes[i][j], waiting for the first vehicle included, null for no connection) and the timetable caveat. Nothing needed to invoke it correctly is missing; transfer_time_factor is left to the schema, which documents it thoroughly.

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%, but the description adds meaning the schema lacks: the full accepted place grammar (stop name, address, named place, 'geo:lat,lon', find_place place_id), departure-time parsing rules (ISO 8601, offsets/Z converted, bare '08:00' means today or tomorrow if long past, omit for now), and the row/column meaning of the answer. This goes well beyond the terse schema strings.

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 ('compute the public-transport travel time... from each of several origins to each of several destinations'), plus scope (Switzerland, one departure time) and the matrix shape. It explicitly distinguishes itself from plan_journey and reachable_area, 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?

'Use it when there are several places on either side' gives the positive condition, and it names the two alternatives with their selecting conditions: plan_journey for one pair with the actual connection, reachable_area for everywhere reachable. That is explicit when-to-use plus when-not-to-use routing.

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