Bus arrival times

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

Annotations only supply readOnlyHint and openWorldHint, so the description carries the return-semantics burden and does it well: it explains the arrival strings, that later buses are reported as minutes after the next one, and that low-floor/wheelchair-ramp data appears only in cities that publish their fleet. It does not mention failure modes for an unknown route name or whether results are cached, which keeps it out of 5 territory.

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 return-value detail is front-loaded in the first sentence, followed by a short narrowing hint and a compact example, with no filler. The middle parenthetical about fleet data is dense but earns its place; the standalone fragment "Give stop to see one stop only" reads slightly clipped.

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 needs to convey what comes back, and it does: arrival text, minutes to subsequent buses, and an optional low-floor/ramp attribute. Combined with a fully documented 5-parameter schema, an agent has enough to call this correctly; only rate-limit and error behavior are unaddressed.

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 `city`, `stop`, `directions`, `limit` and `routeName` are already fully documented in the schema, including enums and route-name lookup with bus_route_search. The description only restates the `stop` narrowing and supplies an illustrative triple of values, adding little beyond the schema. 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: live estimated arrival of the next buses at the stops of a route, with the shape of the returned values ("4 min", "arriving now", "last bus has passed"). It distinguishes route-level results from single-stop results via "Give stop to see one stop only", but it never names bus_stop_arrivals or bus_positions, so the agent must infer the boundary from the sibling list.

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 implied rather than stated: narrow with `stop`, and a concrete example ("Taipei", "307", "西門") shows a valid call. There is no explicit when-to-use/when-not guidance and no routing to the obvious alternatives for a single stop or for vehicle positions, so the agent has to infer the choice.

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