mbta_get_trips

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

No annotations are provided, and the description is minimal. It does not disclose whether the tool returns a single trip or a list, how pagination works (though page_limit parameter implies it), or any rate limits, data freshness, or side effects. The behavioral transparency is poor given no annotations to lean on.

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 very concise at one sentence, but it sacrifices informativeness. It is front-loaded with the verb and resource, but lacks structural elements like usage context or parameter hints. It is appropriately sized for a trivial tool, but given the complexity of the API, more detail would be justified without being verbose.

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, the description should clarify return values, but it does not. The tool has 4 optional parameters, yet no guidance on default behavior (e.g., retrieving all trips vs. requiring at least one filter). Given the number of sibling tools, this lack of completeness hinders effective use.

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 each parameter already has a description. The tool description adds no extra meaning beyond what the schema provides. For example, it does not explain how direction_id values map to direction names or how pagination interacts with other filters. Baseline score 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 'Get MBTA trip information.' clearly states the verb ('Get') and resource ('trip information'). However, it is generic and does not differentiate from sibling tools like mbta_get_routes or mbta_get_schedules, which also retrieve related data. The schema hints at filtering by trip_id, route_id, etc., but the description lacks specificity about scope.

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?

No guidance is provided on when to use this tool compared to alternatives such as mbta_get_schedules, mbta_get_predictions, or mbta_get_vehicle_positions. The description does not mention any use cases or exclusions, leaving the agent without context for tool selection.

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