Terminus schedules

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

With no annotations, the description carries the full burden. It clearly describes the data returned (grouped by terminus, max upcoming times per line/direction) and the effect of data_freshness (realtime vs base_schedule). It does not explicitly state that the operation is read-only, but the nature of a schedule query makes this implicit.

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 concise, consisting of two sentences that deliver the core purpose, required inputs, and a helpful default note. No unnecessary words or 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?

Given the moderate complexity (5 parameters, no output schema), the description sufficiently explains why this tool exists and how to use it. It lacks an explicit output format description or differentiation from related tools, but the station-display analogy and parameter hints cover most needs.

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 schema descriptions are comprehensive and cover all parameters (100% coverage). The description adds meaningful context about the items_per_schedule default and the necessity of resolving line_id through search_pt_objects, going slightly beyond 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 clearly states the tool's purpose: a departure board for a specific line at a stop, grouped by terminus, exactly what a station display shows. It also specifies the required inputs (stop and line) and how to obtain them.

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 guidance to resolve the line ID via search_pt_objects and notes the requirement for both stop and line. It also mentions the default for items_per_schedule to manage output size. However, it does not compare usage to sibling tools like next_departures or stop_schedules.

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