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

Annotations already declare readOnly/idempotent/non-destructive and open-world, so the description doesn't need to restate safety. It adds substantive behavior instead: results are scheduled times, never live ETA or proof of service, the search window is fixed at 24 hours, approximate spellings are labeled rather than treated as matches, and missing metadata stays null rather than being inferred. It does not mention pagination, ordering, or rate/coverage errors, which keeps it from a 5.

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?

Nearly every sentence carries operational information: mode separation first, then discovery workflow, then field provenance caveats, then time-window and exclusivity constraints. The only cost is structure—sentences are hard-wrapped across lines, so related clauses (e.g. 'The search covers 24 hours. stop_id and coordinates are mutually exclusive.') are visually split, which slows scanning slightly.

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?

For an 8-parameter, zero-schema-description tool with an output schema present, the description supplies the temporal semantics, mode workflow, coordinate-vs-id exclusivity, and data-provenance limits an agent needs to call it correctly. Return values need not be described because an output schema exists. The unaddressed radius_m and the absence of any guidance on combining line with coordinates are the only substantive omissions.

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?

With 0% schema description coverage the description must explain all 8 parameters, and it covers most: at (ISO datetime with UTC offset, defaults to now in Europe/Istanbul), stop_query/limit discovery mode, stop_id, lat/lon mutual exclusivity, and line (published route short name). radius_m is never mentioned, which is the one notable gap given coordinates are supported. stop_code/stop_desc/platform_direction_text are explained as output fields rather than parameters, which is still useful.

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 two distinct modes with specific verbs and resources: name-based GTFS stop discovery via stop_query, and published departures for a stop_id or coordinates. Explicitly warns 'This mode returns stops, NOT departures', which prevents the most likely confusion with a sibling transit tool. The distinction from other Istanbul tools is implicit but the naming and scoping are sharp enough for an agent to route correctly.

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?

Gives explicit when-to-use rules for each mode ('Use stop_query with limit only to discover stop_id candidates'), an exclusion ('never choose the first automatically', 'Same-name stops remain separate'), a workflow ('Ask the user to select a candidate ... then call with stop_id'), and hard constraints ('stop_id and coordinates are mutually exclusive', 'Outside-calendar queries are unavailable'). This is about as complete a routing guide as a two-mode tool can have.

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