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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: this is 'real-time live data', carries MassDOT Open Data License terms, has 'no upstream cost', and requires at least one filter to constrain the live feed. No contradictions with annotations.

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 dense but well-structured: it leads with the core purpose, then output fields, then required filters, then direction semantics, then licensing/cost notes. Every clause adds useful information; only the license/cost details are slightly tangential to invocation, but they are concise and not harmful.

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 a real-time data tool with four optional-but-conditionally-required parameters, the description covers the essential call pattern: at least one of stop or route, direction filtering, and supported transit modes. Since an output schema exists, the description need not restate return structures in detail, and the schema supplies parameter-level examples and limits. Minor gaps like pagination or rate limits are not critical given the rich annotations and schema.

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 all four parameters with examples, defaults, and constraints. The description reinforces the stop/route requirement and direction semantics, but adds little beyond what the schema provides, so the high-coverage baseline of 3 is appropriate.

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 states a specific verb and resource: 'Get real-time arrival and departure predictions for Boston MBTA stops' with live vehicle tracking across subway, bus, commuter rail, and ferry. It names the returned fields (predicted arrival_time, departure_time, direction, status, schedule relationship, associated IDs), which clearly distinguishes it from sibling tools like mbta.transit.alerts, mbta.transit.routes, and mbta.transit.stops.

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 call guidance: 'Requires at least one filter: stop ID ... or route ID' and explains direction filtering with `direction_id` (inbound vs outbound). It does not explicitly name alternatives or state when not to use this tool versus sibling MBTA tools, but the clear scope and filter requirement provide strong practical usage context.

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