SL – Stockholm public transport

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses fuzzy matching behavior ('typos are fine, abbreviations are not'), that a query can return several distinct stops, how to disambiguate, and the exact one-line-per-stop return shape. These are behavioral traits an agent could not 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 purpose and return values, then usage routing, then the negative case, then ambiguity handling, then output shape. Every sentence carries distinct information; there is no filler or restatement of the title.

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 two-parameter lookup with no output schema, the description supplies the missing return format ('<id>: <town>, <name> (<modes>)'), the disambiguation policy, and the sibling routing. Nothing an agent needs to call it correctly and interpret results is absent.

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

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

Schema coverage is 100% and the schema already documents both 'query' (including the typo/abbreviation note) and 'limit' with its bounds and default. The description reinforces query semantics and hints that results may be multiple, but adds no new naming syntax or formatting details beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Find Stockholm public transport (SL) stops by name') plus what is returned (ids, names, transport modes). It clearly distinguishes itself from siblings by naming get_departures and plan_trip as consumers of the resulting ids.

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

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

Explicitly routes the agent: use this to obtain a siteId for get_departures or a stop id for plan_trip, and explicitly excludes street addresses ('pass those to plan_trip as text instead'). It also gives a resolution strategy for ambiguous multi-match results (pick by name/modes or ask the user).

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

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

Annotations only cover read-only and open-world, but the description adds real behavioral traits: real-time SL data capped at 3 departures per line and direction, a 3-hour horizon, and the important edge case that an unknown siteId returns an empty list rather than an error. It stops short of covering error modes, rate limiting, or what live-vs-scheduled mixing looks like, so it is strong but not exhaustive.

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 action and return payload, then routing, then data limits and edge cases — a sound order with no filler. The final `towards` guidance is a long compound sentence that could be split for readability, which keeps it off a 5.

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

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

There is no output schema, and the description compensates by enumerating returned fields, the 3-per-line/direction cap, and the time horizon. Combined with the sibling routing and the empty-result caveat, an agent has everything needed to call this 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 does add real meaning beyond the schema for `towards` (final destination only, with the 'mot T-Centralen' workaround), which lifts it slightly, but the other five parameters are left to 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?

States a specific verb and resource ('List live departures from one SL stop, soonest first') and then enumerates exactly what comes back: line, mode, final destination, direction, platform/bus stop letter, time, delay, cancellation, notes. It explicitly names the siblings it is not (plan_trip, get_disruptions), so an agent can route without opening a schema.

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

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

Gives a concrete use case ('when does the next X leave from Y') and names both alternatives with the condition that selects them: plan_trip for A-to-B, get_disruptions for track work and broken lifts. It also supplies a negative rule for the `towards` filter, telling the agent to omit it and read the direction from results rather than 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 only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing that the text is Swedish, truncated at 800 characters, and server-cached for 1 minute. These are exactly the traits an agent needs to interpret results correctly and avoid spurious retries.

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 what the tool returns, followed by when to use it and the behavioral caveats; nearly every clause earns its place. Slightly dense as a single run-on paragraph, but no filler sentences.

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 still tells the agent what a result contains (affected lines, until when), what language and length to expect, and how fresh it is. For a two-parameter read-only lookup, nothing material is missing.

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

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

Schema coverage is 100% and the schema already documents both parameters with examples and an enum, so the description only adds the omission semantics ("Leave both filters out to list everything"). Baseline 3 is appropriate since the schema carries the parameter meaning.

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

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

States a specific verb and resource ("List disruptions SL has announced") and enumerates the content covered: track work, closed entrances, broken lifts, replacement buses, affected lines, and validity window. An agent can immediately distinguish this from find_stop, get_departures, and plan_trip.

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

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

Gives a concrete scenario ("check a line or the stops of a trip before travelling, e.g. lifts for a wheelchair") and explicitly names the alternative for the adjacent case: "For live delays and cancelled departures, use get_departures instead." It also clarifies the default behavior when filters are omitted, which prevents unnecessary parameter 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?

Beyond the readOnly/openWorld annotations, the description discloses result cardinality (up to 3 trips), a non-obvious fallback (walking all the way when under 30 min), the per-item fields returned and the fuzzy-match echo behaviour. It also states the error surface (unknown stops, identical stops, out-of-timetable times) and a real capability limit (SL cannot plan step-free trips), which no annotation conveys.

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

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

The primary purpose and the sibling exclusion are front-loaded, and the denser return-shape sentence earns its space because there is no output schema. It is a long, dense block with a slightly tangential accessibility coda, but nearly every clause carries information an agent would otherwise have to discover by trial.

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

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

For a 6-parameter routing tool with no output schema, the description covers input interpretation (stops vs fuzzy-matched addresses), output shape (rides vs walks and their fields), failure modes and a domain limitation. Nothing an agent needs in order to call it correctly and interpret the response is missing.

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

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

Schema description coverage is 100%, so all six parameters are already documented, including the Stockholm-time format and prefer's default. The description reinforces a few meanings (Stockholm time, prefer 'least walking' as the accessibility workaround) but adds no new syntax or semantic detail about from/to, modes, or arriveBy, 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 opening sentence states a specific verb (plan), the resource (trips), the exact scope (between two stops or street addresses) and the time semantics (leave or arrive at a given time). It is immediately distinguishable from get_departures because of the origin/destination requirement.

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 names the concrete user intents it serves ('how do I get to X', 'when must I leave') and explicitly routes single-stop departure queries to get_departures. It also gives a conditional alternative path for step-free travel (use prefer 'least walking' plus get_disruptions), which is when-to-use guidance for a whole class of requests.

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