Get realtime status for a stop or line

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

No annotations are provided, so the description carries the full burden. It discloses what kind of output to expect (counts of on-time/delayed/cancelled for stops, active vehicle counts and delays for lines) and implies a read-only operation. However, it does not address edge cases like both parameters being supplied, invalid IDs, or data freshness/rate limits, leaving some behavioral gaps.

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 with no filler. The primary verb and resource are front-loaded, and the two usage modes are explained in parallel structure. Every clause earns its place, making it both concise and scannable.

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 no output schema and only two optional parameters, the description covers the core usage and expected result types. It explains what each mode returns, which is sufficient for a simple status summary. It falls short of specifying what happens if neither or both parameters are provided, and does not outline error handling, but these are minor for a low-complexity tool.

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 100%, so the schema already documents both parameters with types, patterns, and context. The description adds a bit of semantic clarity by explaining the relationship between the parameter and the summary type, but it essentially reiterates the schema info without adding substantial new meaning. Hence a baseline 3.

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 as 'Get a realtime health summary' and then breaks down the two distinct modes: stop-level (summarizing on-time/delayed/cancelled departures) and line-level (active vehicles and delays). This specific verb+resource framing distinguishes it from siblings like get_departures (raw departures) and get_vehicle_positions (vehicle locations), which are different operations.

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 gives explicit guidance on which parameter to pass for which scenario ('For a stop, pass stop_place_id' and 'For a line, pass line_id'), making selection clear. However, it does not explicitly contrast with alternative tools (e.g., 'use get_departures for detailed times') or state when not to use this tool, so it stops short of full exclusion criteria.

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