Departure board

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

The description adds meaningful behavioral context beyond the readOnly/idempotent/openWorld annotations: data is live and delay-aware, platforms are real-time with a platform_changed flag, and cancellations/disruptions are surfaced. This complements the annotations and does not contradict them. It does not discuss data freshness limits or empty-result behavior, but the live qualifier covers the key trait.

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?

One front-loaded sentence states the purpose and enumerates the important output fields without redundancy. Parentheticals such as 'real-time, with delay' and 'real-time, platform_changed flag' are compact, and the journey_id cross-reference is a useful single mention.

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 rich input schema, the safety annotations, and the presence of an output schema, the description fills the remaining gap by specifying live/real-time behavior and the link to db_trip_details. Nothing needed to invoke the tool correctly 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 80%, so the schema already explains when, format, minutes, station, and rail_only. The description focuses on output fields rather than adding parameter-level semantics, and with high schema coverage it does not need to compensate. The journey_id reference is about linking to db_trip_details, not about 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?

The description clearly identifies a live departure board and enumerates the data it exposes: time with delay, line, destination, platform with platform_changed, cancellation, disruption notes, and journey_id. It is unambiguous about the resource, but it lacks an explicit verb like 'retrieves' and does not directly contrast itself with db_arrivals or db_journeys.

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?

Intended use is only implied by 'Live departure board' and the real-time departure fields. The description does not explicitly say when to use this tool instead of db_arrivals or db_journeys, nor does it state exclusion criteria. The reference to journey_id for db_trip_details hints at downstream usage but not at tool selection.

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