onebusaway-mcp-server

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

The annotations already declare readOnlyHint=true, and the description aligns by describing a read-only search that returns data. The description adds modest value by specifying return fields and suggesting further actions, but it does not delve into potential pagination, rate limits, or other behavioral nuances. Given that annotations cover the safety profile, this is adequate but not exceptional.

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 three concise sentences with no filler. It front-loads the primary purpose, immediately states return contents, and then provides a practical tip for using the output. Every sentence earns its place, and the structure is ideal for quick agent comprehension.

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 geographic search tool with six parameters fully documented in the schema and an output schema present, the description covers the essential context: what it finds, what it returns, and how to use the results. It does not mention potential pagination or result limits, but given the output schema and the relative simplicity of the tool, this is a minor omission. The description is complete enough for correct invocation.

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?

The schema describes all six parameters thoroughly, achieving 100% coverage, so the description adds little to parameter meaning. It does mention 'filtered by name or number' which maps to the query parameter, and 'near a location' implies lat/lon, but these are already explicit in the schema. The description adds no new semantic depth beyond the schema, so a 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 clearly states a specific verb ('Find'), resource ('transit routes'), and context ('near a location') with an optional filter. It also lists the returned fields (IDs, short names, descriptions), making the purpose distinct. However, it does not explicitly differentiate from sibling tools like onebusaway_search_routes, which could also locate routes, so it loses a point for not addressing sibling ambiguity.

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 no guidance on when to use this tool versus alternatives such as onebusaway_search_routes or onebusaway_find_stops. It only mentions downstream usage of routeId values, which is helpful for post-call actions but does not help the agent decide between spatially searching routes and other search or retrieval tools. No exclusions or comparative criteria are provided.

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

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

Annotations declare readOnlyHint=true, so the read-only nature is already disclosed. The description adds value by enumerating the returned fields, which is beyond the annotations, but does not elaborate on potential edge cases (e.g., result limits, error behavior, or pagination). It is adequate but not rich in behavioral disclosure beyond what annotations and schema already provide.

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 concise — four short sentences, each adding essential information: purpose, return fields, downstream usage, and optional filter. It is front-loaded with the core purpose and avoids redundancy or filler. Every sentence earns its place.

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?

Given the tool's moderate complexity (4 parameters, all documented, output schema present) and the read-only annotation, the description covers everything needed for correct invocation: what it does, what it returns, how to use the results, and the optional filter. No missing guidance for an agent to call it correctly.

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%, and each parameter is already described in detail (ranges, defaults, exclusivity). The description reiterates the 'stop code' filter ('the number printed on the stop sign') which mirrors the schema. It adds no new semantic meaning beyond the schema; baseline of 3 is appropriate because the schema carries the full load.

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 ('Find bus stops near a location') and lists the returned fields (ID, name, direction, served routes, wheelchair boarding status). This clearly distinguishes it from sibling tools like get_stop (single stop lookup) and search_stops (name/code based search), though it doesn't explicitly name them. The purpose is unambiguous.

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 implies a location-based use case ('near a location') and provides downstream guidance to use onebusaway_get_arrivals with the returned stopId values. However, it does not explicitly state when to choose this tool over alternatives like search_stops or find_routes. Usage is implied rather than clearly delineated against siblings.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces the read-only behavior by describing what data is returned. It adds value by enumerating the returned fields (summary, description, reason, affected stops/routes, consequence, active time windows), which goes beyond the annotation's safety-only disclosure.

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?

Two sentences, front-loaded with the purpose, followed by return contents and ID source. No filler; every sentence contributes useful information.

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 a single parameter and the readOnlyHint annotation, the description covers what the tool does, what it returns, and where the input originates. No critical information is missing for invoking it correctly.

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 the parameter is already documented. The description adds provenance ('Situation IDs appear in onebusaway_get_arrivals responses under situationIds and situations[].id'), which gives the agent guidance beyond the schema's type constraint.

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 'Fetch full detail for a service alert (situation) by ID.' This is a specific verb+resource and clearly distinguishes from sibling tools like onebusaway_get_arrivals, which list alerts rather than fetch detail for a single ID.

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?

Explicitly tells the agent where to obtain the situationId (from onebusaway_get_arrivals under situationIds and situations[].id), which is the key usage prerequisite. It doesn't mention when not to use the tool, but the ID requirement makes the usage context clear.

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

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

Beyond the readOnlyHint annotation, the description explains the meaning of the 'predicted' boolean (GPS-backed vs schedule-only), the return of schedule deviation in seconds, and the presence of vehicle positions and alerts. It also notes that tripId is available for follow-up calls. This adds valuable behavioral context not captured in annotations or output schema.

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 four compact sentences with no filler. It front-loads the core purpose, then details the key behavioral nuance (predicted boolean), follow-up usage, and a critical formatting rule. Every sentence earns its place.

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?

Given the presence of a full output schema and rich parameter descriptions, the description covers the essential behavioral aspects: what real-time data is returned, how to interpret the predicted flag, and how to chain to trip details. It does not explicitly steer users away from schedule-based tools, but that is a minor omission given the clear real-time focus.

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?

The input schema already provides complete descriptions for all parameters (100% coverage), including the stop ID format and default values for minutesAfter and minutesBefore. The description reiterates the stop ID format but adds no new parameter-specific meaning beyond what the schema already documents, so it meets the baseline for schema-covered tools.

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 function: it returns real-time arrivals and departures for a stop, including predicted times, schedule deviation, vehicle positions, and alerts. This distinguishes it from siblings like onebusaway_get_schedule_for_stop (static schedule) and onebusaway_get_stop (stop details) by emphasizing the real-time and predictive nature.

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 implies real-time usage through terms like 'real-time', 'predicted', and 'GPS tracking', but it does not explicitly state when to use this tool versus alternatives such as onebusaway_get_schedule_for_stop. It offers follow-up guidance (use tripId for onebusaway_get_trip) and stop ID format, but lacks direct exclusions or comparisons to sibling tools.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context: it returns all trips in order with stop times and clarifies the block concept. This goes beyond the annotation without contradicting it.

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?

Four concise sentences, front-loaded with the primary action. Each sentence adds distinct value: action, definition, return content, and usage/derivation. No fluff or redundancy.

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 single-parameter, read-only tool with an output schema, the description covers purpose, usage context, and parameter provenance. Nothing essential is missing for a correct invocation.

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% (blockId is described), so baseline is 3. The description adds extra value by explaining how to obtain a valid blockId (from a trip record, with the full chain from arrivals), which is not fully captured in the schema description.

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 action: 'Fetch the full-day block schedule for a vehicle by block ID.' It explains what a block is (ordered sequence of trips) and what is returned (all trips in order with stop times), making it distinct from siblings like onebusaway_get_trip or onebusaway_get_arrivals.

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?

Provides explicit use cases ('when will this bus return?', fleet tracking) and a clear dependency chain: obtain tripId from onebusaway_get_arrivals, then get blockId from onebusaway_get_trip. While it doesn't explicitly compare to alternatives, the workflow is unambiguous.

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

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

The description discloses the exact return fields (short name, description, agency, route type, schedule URL), which is behavioral context beyond the readOnlyHint annotation. It does not mention errors, rate limits, or side effects, but for a read-only fetch these are less critical. The description adds useful information about what the tool returns without contradicting 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?

Two sentences with no redundant wording. The core purpose is front-loaded, followed by the key detail (ID format) and the discovery hint. Every word earns its place.

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 one parameter, a readOnlyHint annotation, and an existing output schema (which covers the return shape), the description fully covers what an agent needs: what the tool does, what it returns, the ID format, and how to get IDs if unknown. No essential information is missing for correct invocation.

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?

The input schema already provides a detailed description for routeId, including the agency-prefixed format, an example, and pointers to discovery tools (100% schema coverage). The description repeats the format example but does not add new meaning beyond the schema. Per the rubric, a score of 3 is appropriate when schema coverage is high and the description offers no additional parameter semantics.

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 fetches details for a specific route by ID, and enumerates the returned fields (short name, description, agency, route type, schedule URL). This distinguishes it from sibling tools like onebusaway_list_routes_for_agency (which lists multiple) and onebusaway_search_routes (which is discovery-focused). The ID format and example remove ambiguity.

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 implies usage context: it's for retrieving a specific route by ID, and it explicitly directs users to onebusaway_find_routes or onebusaway_search_routes for discovering IDs. It does not explicitly state when NOT to use it, but the 'specific route by ID' framing and the discovery guidance effectively communicate the selection criteria. A clear 'when to use' is present, though the 'when not' is implicit.

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

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

The readOnlyHint annotation is already present, and the description adds useful context about the return content (all trips, stop sequences, departure times) and the default date. It doesn't contradict annotations and provides more than just the safety profile, though it doesn't disclose potential response size limits or failure modes. This is adequate given the annotation coverage.

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 wasted words. The first sentence front-loads the core functionality, and the second gives the exclusion. Every part earns its place.

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?

Given the tool's simplicity, the existing output schema, and the read-only annotation, the description covers everything an agent needs: what it returns, the default behavior, and the alternative for live data. No critical information is missing for correct usage.

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% — both routeId and date are well-described in the schema, including the default for date and guidance on finding route IDs. The tool description only restates the default behavior and doesn't add meaning beyond the schema, so the 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 states a specific verb and resource: 'Full-day schedule for a route' with details on what is included (all trips, stop sequences, departure times). It clearly differentiates itself from the live-predictions tool by naming onebusaway_get_arrivals, making it distinguishable among the many siblings.

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?

Explicit guidance is given: 'For live predictions, use onebusaway_get_arrivals at specific stops instead.' This tells the agent when not to use this tool and names the alternative. The default-date behavior is also mentioned, providing clear context for invocation.

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

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

Annotations declare readOnlyHint=true, and the description does not contradict this. It adds meaningful behavior beyond the annotation: the full-day scope, defaulting to today in the agency's timezone, and listing by route and direction. This enriches the operational picture without being verbose.

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?

Two sentences plus a routing sentence, with the core purpose front-loaded. Every sentence earns its place; no fluff. The structure is ideal for quick parsing by an agent.

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 an output schema present and full parameter documentation, nothing is missing for correct invocation. The description covers the functional scope, the date default, and the alternative for live data. This is complete for a read-only schedule lookup 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% — both parameters (stopId, date) are documented in the schema. The description adds no extra parameter-level detail beyond the schema, so the baseline 3 applies. It provides no additional syntax or edge-case guidance beyond what the schema already covers.

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 ('full-day departure schedule for a stop') and explicitly differentiates itself from the sibling onebusaway_get_arrivals by noting the alternative for live predictions. An agent can immediately tell what this tool does and how it differs from nearby options.

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 provides clear guidance on when to use this tool ('for planning or when real-time data isn't needed') and when not to, explicitly naming the alternative (onebusaway_get_arrivals). This is model routing guidance.

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

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

Annotations declare readOnlyHint: true, so the description is not required to state that. It adds value beyond the annotation by enumerating the returned fields and explaining the ID format, giving the agent concrete expectations for the operation's behavior. 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?

Two sentences, zero waste. The action and output summary are front-loaded, followed by the essential ID format detail. Every word earns its place; no redundant qualifiers or filler.

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 single-parameter read-only tool with a complete schema description and output schema present, the description covers everything an agent needs: what the tool does, what it returns, and how to construct the ID. Nothing essential is missing given the low complexity and available structured data.

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 parameter is already documented. The description and parameter text add extras: the agency-prefixed format with examples and pointers to discovery tools, which are not present in the bare schema. This meaningfully enhances understanding of how to fill the parameter correctly.

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 action ('Fetch details') and the resource ('a specific stop by ID'), lists the returned fields (name, coordinates, direction, served routes, wheelchair accessibility), and differentiates from sibling tools by focusing on a single stop's details rather than schedules, arrivals, or routes.

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 clear context that this tool is for fetching stop details, and the parameter schema advises using onebusaway_find_stops or onebusaway_search_stops to discover IDs. It does not explicitly contrast with other 'get' siblings like get_schedule_for_stop, but the purpose is unambiguous enough for correct selection.

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

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

The annotation readOnlyHint=true already declares the tool read-only, so the description's main contribution is specifying the return data (position, deviation, phase, remaining stops) and noting that includeSchedule defaults to true. It also discloses that serviceDateMs is only needed for previous service days. These details add context beyond the annotation, helping the agent understand what to expect without contradicting it.

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?

Two sentences with zero fluff. The first sentence immediately conveys the verb, resource, and output, while the second provides actionable usage guidance. Front-loaded with the core purpose, every word earns its place.

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 tool with 3 parameters (1 required), a rich output schema, and read-only annotation, the description is sufficiently complete. It explains what the tool returns and how to source the input. It could optionally mention that tripId is required, but that is already in the schema. The absence of pagination or error details is acceptable given the tool's scope and the presence of an output 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%, with each parameter (tripId, serviceDateMs, includeSchedule) already documented. The description adds minimal extra meaning: it mentions where to obtain tripId (arrivals) but does not elaborate on parameters beyond what the schema provides. Per the guideline, a baseline of 3 is appropriate when the schema does the heavy lifting, and the description offers no further parameter insight.

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: 'Real-time status and stop sequence for a trip' and enumerates the specific outputs (vehicle position, schedule deviation, current phase, remaining stops). It also differentiates from siblings by focusing on a single trip and explicitly referencing onebusaway_get_arrivals as the source of tripId, making it distinct from the many search/list tools.

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 a concrete usage scenario: 'Use tripId from onebusaway_get_arrivals to look up a specific vehicle's progress.' This implies when to use the tool (when you have a tripId from arrivals) and clarifies the relationship with a sibling. However, it does not explicitly state when not to use it or compare with other trip-related tools (e.g., get_block, get_route), so a clear exclusion is missing.

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

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

Beyond the readOnlyHint annotation, the description discloses that route filtering is client-side, meaning all agency vehicles are fetched before filtering, which is a performance-relevant behavior. It also enumerates returned fields (GPS coordinates, heading, schedule deviation, current trip), adding value beyond the bare annotation.

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?

Two concise sentences front-load the primary function and optional filter, then add a practical usage example. Every sentence contributes, and there is no filler or redundancy.

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 read-only tool with two parameters (one required), both fully documented in the schema, and an existing output schema, the description covers the essential usage context. It includes the critical client-side behavior and points to agency discovery, leaving no meaningful gaps.

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% — both agencyId and routeId already have detailed descriptions, including the client-side filtering caveat. The tool description adds no new parameter semantics beyond what the schema captures; it only echoes the filter behavior and the agency-listing pointer. This meets the baseline for full schema coverage.

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 core function: returning real-time positions of active vehicles for an agency, with an optional route filter. It is specific about the resource (vehicles) and the output (GPS coordinates, heading, schedule deviation, current trip), and it is easily distinguishable from sibling tools like get_arrivals or get_trip.

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 provides a concrete use case ('where are all the buses on route X right now?') and directs the agent to onebusaway_list_agencies for agency IDs. It does not explicitly enumerate when not to use this tool or name alternative tools, but the use-case framing gives clear context. Sibling names like get_arrivals imply alternatives without being called out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering safety and scope. The description adds what data fields the response contains, which is beyond the annotations but not contradictory. It does not discuss pagination or rate limits, but given the simple list nature and closed world, this is sufficient context.

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?

Two sentences deliver the purpose, return fields, and usage context without redundancy. The core action is front-loaded, and the downstream tool linkage is a practical addition. Every word earns its place.

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 parameterless list tool with an output schema and annotations declaring read-only and closed-world behavior, the description provides the key information: what it returns, and why it matters (agency IDs for other tools). Nothing an agent needs to call it correctly is missing.

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?

The tool has zero parameters, so there is nothing to describe. The schema is empty and coverage is 100% vacuously. Per the rubric, baseline for 0 parameters is 4, and the description does not need to compensate for any parameter documentation gap.

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 action ('List all transit agencies') and resource scope ('served by this OneBusAway instance'). It also specifies the return fields (IDs, names, contact info, timezone, coverage center), which distinguishes it from any sibling that might return agency data with different scope. No ambiguity.

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 explicitly notes that agency IDs are needed for two downstream tools, implying when to use this tool (prior to those). It does not mention alternatives because there are none among siblings that list agencies. While it doesn't explicitly say 'use this when you need a list of agencies,' the context is clear and useful for an agent planning a sequence of calls.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this by describing a list operation with no side effects. It adds useful behavioral detail beyond annotations by specifying the exact return fields ('route IDs, short names, and descriptions') and the full-scope nature ('all routes'). No contradictions with annotations; the behavior is consistent.

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 four short sentences with no filler. It leads with the core action, then return values, then usage context, then parameter source. Every sentence serves a purpose, and the structure is logical and efficient.

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?

Given the tool's simplicity (one required parameter), the presence of an output schema, and annotations that cover read-only behavior, the description addresses everything an agent needs: what it lists, what it returns, when to use it, and where to get the parameter. No critical information is missing.

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%, and the parameter description in the schema already includes examples and guidance ('Use onebusaway_list_agencies to discover IDs'). The tool description repeats the same advice without adding new meaning, so it does not go beyond what the schema provides. 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 ('List'), a resource ('routes operated by an agency'), and the returned data ('route IDs, short names, and descriptions'). It clearly distinguishes this tool from siblings like search_routes and find_routes by emphasizing the full-service enumeration scope, leaving no ambiguity about what it does.

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 explicitly says 'Use to enumerate an agency's full service before searching for a specific route,' providing clear context for when to call it. It also directs the user to onebusaway_list_agencies for discovering agencyId. However, it does not explicitly name alternatives or state when NOT to use it (e.g., when you already know the route), so it stops short of a perfect 5.

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

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

The annotation readOnlyHint=true already covers the safety profile. The description adds that it returns matching routes with IDs, which is a basic behavioral trait. It does not disclose other behaviors like pagination, result ordering, or error handling, and since annotations already declare read-only, the description is not heavily burdened. A score of 3 reflects adequate but not rich behavioral context.

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, front-loaded with the core purpose ('Search for routes by name or number') followed by a concise usage note. There is zero waste and every word adds value. It is efficiently structured.

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?

Given the tool's simplicity (2 params, clear output schema exists), the description covers the essential context: the tool resolves a short name to an ID and pairs with specific follow-up tools. It does not explain the output format, but that is provided by the output schema. The description is complete for an agent to decide when and how to use it.

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 both parameters are already well documented. The description adds a concrete example '44' and mentions 'route short name', which are also present in the schema. It does not provide new semantic meaning beyond the schema, so the 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 the verb 'Search' and the resource 'routes by name or number', and it clearly indicates the purpose: to resolve a route short name to a route ID for further lookups. However, it does not explicitly differentiate from the sibling tool 'onebusaway_find_routes', which may overlap in function. It is specific and actionable, but lacks explicit sibling differentiation.

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 provides explicit guidance on when to use this tool: 'Use to resolve a route short name (e.g. "44") to a route ID for schedule or vehicle lookups'. It names the downstream tools (onebusaway_get_vehicles, onebusaway_get_schedule_for_route) that benefit from this resolution. However, it does not mention when not to use it or present alternatives such as find_routes, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds that it returns IDs and coordinates, which is helpful context, but does not disclose any additional behavioral traits such as rate limits, ordering, or edge cases. With annotations covering safety, the extra value is moderate.

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 fluff. It front-loads the core function, then the use case. Every word earns its place, making it efficient for an agent to parse quickly.

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?

Given the presence of an output schema (which presumably defines the return structure), the description doesn't need to detail return fields beyond mentioning IDs and coordinates. The required parameter and optional maxCount are clearly defined in the schema. The description provides context for why an agent would call this tool, which is sufficient for correct invocation.

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?

The schema covers both parameters fully (100% coverage), with descriptions for 'query' noting it accepts a name fragment or code, and for 'maxCount' including default and limits. The tool description adds no further semantics beyond what the schema already provides, so a 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 states a clear verb ('Search'), a specific resource ('stops'), and the distinguishing scope ('by name or code'). It also specifies what is returned ('matching stops with IDs and coordinates'), making it easy to differentiate from other search tools like onebusaway_search_routes.

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 explicitly tells when to use the tool: 'Use to resolve a human-readable stop name or number to a stop ID for arrivals lookups with onebusaway_get_arrivals.' This provides a concrete use case and implies the tool is for obtaining stop IDs, though it does not explicitly mention alternatives or when not to use it.

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