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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds useful context that the data is a live 'now' snapshot and that vehicle positions are an opt-in expansion, but says nothing about rate limits, auth, or result size.

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 payload description is front-loaded in a single dense sentence, then the valid city list, then a short service attribution line. Little waste, though the trailing vendor/docs sentence is boilerplate that does not help tool selection.

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 only two parameters, no output schema, and full schema coverage, the description carries the remaining burden by enumerating the returned sections and the shape of station objects. It stops short of describing pagination or volume, which matters somewhat for a fleet-wide vehicle feed but is a minor gap.

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 both parameters are already documented, and the description's note on `vehicles: true` largely restates the schema. The one real addition is enumerating valid city slugs, which the schema omits beyond an 'e.g. london' example; that is genuinely helpful but limited.

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 names the resource and enumerates exactly what comes back: lines, stations (id, name, lines), active service alerts, and optionally live vehicle positions. That is more specific than a bare 'get transit data', though it never uses an explicit verb and only implicitly separates itself from the station-level sibling.

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 gives one concrete usage rule — pass `vehicles: true` to include live vehicle positions — and lists the seven supported city slugs, which steers calls correctly. It offers no when-to-use vs. when-not guidance and does not point to nichedb_transit_station for station-specific queries, so routing still requires inference.

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