get_departures

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

There are no annotations, so the description carries the behavioral disclosure burden. It does disclose that the tool returns real-time predictions, countdowns, and alerts, which conveys read-only behavior. However, it does not clarify that no parameters are marked required in the schema despite needing at least one query mode, nor does it describe error behavior or what happens if conflicting parameters are supplied.

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 two sentences, front-loads the core purpose, and adds the key query-mode distinction without any filler. Every sentence earns its place, and the structure makes the tool's behavior immediately understandable.

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?

The description covers the tool's purpose and the two query modes, but it does not explicitly state that at least one mode is required, despite the schema listing zero required parameters. There is no output schema, so the description's brief mention of predictions, countdowns, and alerts partially compensates, but the missing invocation constraint leaves a meaningful gap for correct usage.

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 meaningful grouping by explaining that parameters can be combined as either a Stop ID or a Route ID + Direction ID + Place Code. This adds relational meaning beyond the individual parameter descriptions in the schema, although it stops short of explaining mutual exclusivity or required groups.

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 uses a specific verb ('Get') with a clear resource ('real-time departure predictions, vehicle countdowns, and stop alerts') and scopes it to 'a Metro Transit stop or station.' It is clearly distinct from the sibling tools like get_route_stops or get_service_alerts, so an agent can identify what this tool is for without ambiguity.

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?

The description explains the two accepted query modes ('Stop ID' or 'Route ID + Direction ID + Place Code'), which gives practical input guidance. However, it does not explicitly say when to prefer this tool over siblings, nor does it mention exclusions or conditions such as needing get_route_stops to obtain a place code. Usage is implied rather than fully spelled out.

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