onebusaway-mcp-server

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

Annotations already indicate readOnlyHint=true. The description adds that it returns IDs, short names, and descriptions, which is useful but does not substantially extend beyond the annotation's safety profile.

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 succinct sentences plus a usage note; every sentence adds value with no redundancy or filler. Front-loaded with the core purpose.

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 output schema present and good annotations, the description adequately covers purpose and return shape. Minor omission: no mention of result limits or pagination, but overall complete for a list 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 parameters well. The description adds minimal parameter context beyond what the schema provides, maintaining the baseline score of 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 verb 'Find' and the resource 'transit routes near a location', with optional filtering by name/number. It differentiates from siblings like get_route and search_routes implicitly, but does not explicitly contrast with other find/search 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 hints at follow-up usage ('Use routeId values to fetch...'), but provides no explicit guidance on when to prefer this tool over alternatives like onebusaway_search_routes or onebusaway_find_stops.

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 adds that results include wheelchair boarding status and served routes. No contradictions; description adds useful behavioral context beyond 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 tightly written sentences with a clear next-step pointer. No wasted words; front-loaded with purpose.

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, the description sufficiently covers tool behavior, return fields, and usage. It does not mention result limits, but overall complete for this complexity.

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%, but the description adds value by clarifying the query parameter as 'number printed on the stop sign' and radius cap at 1600m. This enhances schema descriptions.

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 finds bus stops near a location and lists the fields returned (ID, name, direction, served routes, wheelchair boarding). It distinguishes from siblings like search_stops by focusing on location-based search.

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 explains when to use the query parameter (optional stop code filter) and how to use results with onebusaway_get_arrivals. However, it does not explicitly exclude alternatives like search_stops.

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 indicate readOnlyHint=true. Description adds detail on return content (fields and structure), which is behavioral beyond annotations. No side effects or destructive actions implied.

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: first states purpose and output, second explains input source. No redundant information, highly 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?

Single parameter with full schema coverage, readOnly annotation present, output schema exists (not shown but indicated). Description sufficiently covers what the tool does 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 covers 100% with description. Tool description adds context by explaining the parameter's origin (from onebusaway_get_arrivals), which is helpful beyond the schema.

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?

Clearly states verb 'Fetch full detail' and resource 'service alert (situation) by ID'. Enumerates return fields (summary, description, reason, etc.). Distinguishes from siblings by specifying where alert IDs originate (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 context: use after obtaining an ID from onebusaway_get_arrivals. Does not explicitly name alternatives or when-not-to-use, but sibling tools target different entities, making usage 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?

Annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds valuable behavioral details: the meaning of the predicted boolean (schedule-only vs GPS) and the agency-prefixed stop ID format. No contradictions.

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 with five focused sentences. Each sentence adds value: purpose, return fields, behavioral detail, follow-up suggestion, and ID format. No unnecessary words.

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?

The description covers the tool's purpose, key return fields, stop ID format, and defaults. With an output schema present, it does not need to detail every field. Minor gap: no mention of pagination or result limits, but adequate for a read-only data 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 baseline is 3. The description adds context for stopId (how to discover IDs) and explains the predicted field, but these are minor enhancements beyond the schema defaults.

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 retrieves real-time arrivals and departures at a stop. It distinguishes itself from sibling tools like onebusaway_get_stop by focusing on dynamic arrival data and explicitly linking to onebusaway_get_trip for follow-up.

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 when to use it (need real-time arrivals) and provides a direct use case for follow-up calls. However, it does not explicitly exclude alternative tools or state prerequisites, leaving some ambiguity.

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 description adds value by explaining the ordered sequence of trips and stop times returned. No contradictions. It doesn't cover rate limits or auth, but for a read-only tool this is acceptable.

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: two sentences plus a usage hint, front-loaded with the purpose, no redundant 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?

Given the tool has one parameter, an output schema (exists), and simple behavior, the description adequately covers what the tool does, what it returns, and how to get the input. No 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%, so baseline 3. The description adds context about the parameter's source (blockId from onebusaway_get_trip) but does not add meaning beyond the schema's own description, which already explains how to obtain the block ID.

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 it fetches the full-day block schedule for a vehicle by block ID, explains what a block is, and distinguishes from sibling tools by specifying how to obtain the blockId from onebusaway_get_trip and tripId from 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?

The description provides explicit use cases ('when will this bus return?', fleet tracking) and a clear workflow: obtain tripId from onebusaway_get_arrivals, then onebusaway_get_trip for blockId, then this tool. It implicitly excludes other uses by focusing on block schedule retrieval.

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 description does not need to address safety. It adds value by specifying the ID format with an example, but does not detail other behavioral traits like return structure (handled by 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?

Two sentences: first states purpose and returns, second explains ID format. Every sentence is essential and front-loaded, no waste.

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 annotations covering safety, the description fully addresses how to get a route ID and what fields are returned, leaving no gaps for a simple fetch 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 covers the routeId parameter with 100% description, including its format and discovery tools. The description restates the format and provides an example, offering marginal added value beyond the schema.

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 'Fetch details for a specific route by ID' and lists returned fields (short name, description, agency, etc.), directly distinguishing it from sibling tools like onebusaway_find_routes (discovery) and onebusaway_get_schedule_for_route (schedule).

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 explicitly says to use onebusaway_find_routes or onebusaway_search_routes to discover IDs, providing clear guidance on when to use this tool (after obtaining an ID) and when not to (for discovery).

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 aligns with that by describing a read-only query returning schedule data. The description adds context about the scope (full-day) and default date, but does not discuss auth requirements or rate limits, which are expected given the read-only nature.

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: the first efficiently defines the tool's function and scope, and the second provides a clear alternative. No unnecessary words, and key information is front-loaded.

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 parameters, read-only, with output schema), the description covers the essential context: what the schedule includes, the default date, and a pointer to live predictions. 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 coverage is 100% with both parameters documented. The description adds value by pointing users to onebusaway_find_routes or onebusaway_search_routes for routeId discovery, which is not in the schema. It also clarifies the date's default behavior, though that is already in the schema.

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 verb 'get schedule' and resource 'route', specifying it returns full-day schedule with all trips, stop sequences, and departure times. It also distinguishes from sibling tool onebusaway_get_arrivals for live predictions.

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 contrasts with onebusaway_get_arrivals for live predictions, providing a when-not-to-use guideline. It also mentions the default date behavior. However, it does not explicitly state when other sibling tools like onebusaway_get_trip might be more appropriate.

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. Description adds behavioral context: the schedule covers a full day, groups by route/direction, and defaults to today. It does not mention other behaviors like authorization or caching, but the transparency is adequate for this straightforward read operation.

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?

Three sentences, each serving a distinct purpose: stating the main function, adding context, and providing an alternative. No wasted words, front-loaded with the core purpose.

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 low complexity (2 parameters, output schema present), the description covers all necessary aspects: what it does, when to use, and an alternative. No gaps identified for a read-only schedule retrieval 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 coverage is 100% and the description does not add new parameter-level information beyond what the schema already provides (date defaults, stop ID format). The description's mention of 'full-day departure schedule' is more about output behavior than 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?

Clearly states the tool returns a full-day departure schedule for a stop, listing departures by route and direction. Distinguishes from sibling tool onebusaway_get_arrivals by specifying this is for planning rather than real-time.

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 states when to use ('planning or when real-time data isn't needed') and when not ('use onebusaway_get_arrivals instead for live predictions'), providing a clear alternative.

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, no contradiction. Description adds transparency by specifying it's a fetch operation, listing return data, and explaining ID format. Beyond annotations, it provides useful 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?

Two sentences, front-loaded with action ('Fetch details...'), no wasted words. Efficient and direct.

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 simple, single-parameter tool with output schema, description covers purpose, parameter usage, and discovery. No gaps given the tool's complexity.

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% (baseline 3). Description adds meaning by explaining ID format with concrete examples and referencing how to discover IDs via sibling tools, going beyond 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?

Description clearly states 'Fetch details for a specific stop by ID' and enumerates returned fields (name, coordinates, etc.). It distinguishes from siblings by explicitly referencing ID format and discovery via sibling 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?

Provides clear context for when to use (when stop ID is known) and references sibling tools for discovery. Lacks explicit exclusion statements, but context is sufficient.

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 adds behavioral context beyond the readOnlyHint annotation by detailing what information is returned (vehicle position, schedule deviation, current phase, remaining stops). It does not contradict the annotation and provides useful insight into the tool's output.

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 sentences, each serving a clear purpose: stating the function, listing outputs, and providing usage guidance. It is front-loaded with the primary action and contains no 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?

Considering the presence of an output schema and annotations, the description adequately covers the tool's purpose, parameters, and usage. It lacks explanation of error cases or when the trip might be inactive, but for a real-time status tool it is sufficiently complete.

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 describes all three parameters with full coverage. The description adds minor value by suggesting the tripId source, but the schema's descriptions are already sufficient. 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 specifies the tool returns 'Real-time status and stop sequence for a trip' with concrete fields (vehicle position, schedule deviation, current phase, remaining stops). It also references a sibling tool (onebusaway_get_arrivals) to obtain the tripId, clearly distinguishing this tool from others like onebusaway_get_vehicles 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?

The description explicitly advises to 'Use tripId from onebusaway_get_arrivals to look up a specific vehicle's progress', providing a clear usage context. It does not explicitly list when not to use the tool or alternatives, but the mention of obtaining the trip ID from another tool effectively guides the agent.

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 indicate readOnlyHint=true. Description adds key behavioral detail: filtering is client-side (all agency vehicles fetched first). No contradictions.

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 usage tip, front-loaded with main purpose. No wasted words.

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 output schema exists (declared in context signals) and annotations are present, description covers what the tool does and returns. Adds useful usage context.

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%, and description adds minimal extra context beyond what schema already provides (e.g., examples for agencyId). Baseline 3 applies.

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?

Clearly states it returns real-time positions of all active vehicles for an agency, with optional route filtering. Distinguishes from sibling tools that focus on routes, stops, alerts, etc.

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 a concrete use case ("where are all the buses on route X right now?") and directs to use agencyId from onebusaway_list_agencies. Lacks explicit when-not-to-use or alternatives.

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 the return fields but does not reveal additional behavioral traits like rate limits or result pagination. The added value is moderate, resulting in a score of 3.

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: the first clearly states the purpose and return data, the second links to dependent tools. Every word adds value, and the structure is front-loaded with no extraneous text.

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 (no parameters, read-only, output schema exists), the description is fully complete. It covers what the tool does, what it returns, and how its output connects to other tools. No additional context is needed.

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, and schema description coverage is 100% (vacuous). With no parameters to document, the description appropriately focuses on the output. The baseline for 0 parameters is 4, and the description effectively adds no parameter-related meaning, which is acceptable.

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 lists all transit agencies served by the instance and specifies the returned fields (IDs, names, contact info, timezone, geographic coverage center). It distinguishes this from sibling tools like onebusaway_list_routes_for_agency by noting the dependency on agency IDs.

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 explains that agency IDs from this tool are needed for onebusaway_list_routes_for_agency and onebusaway_get_vehicles, providing useful context for when to use this tool. However, it does not explicitly state when not to use it or name direct alternatives, leaving room for slightly better 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 already declare readOnlyHint=true, so the description aligns. It adds transparency about returned fields (IDs, short names, descriptions) but does not elaborate on authentication, rate limits, or error handling. With annotations covering the safety profile, the added context is sufficient but not exhaustive.

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?

Three sentences, no redundant content. The main action and return type are front-loaded, and usage guidance follows efficiently.

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 (not shown), the description sufficiently covers the purpose, parameters, and usage context for a simple list tool with one required parameter. No significant 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 coverage is 100%, so baseline is 3. The description does not add new meaning beyond what the schema already provides for agencyId; it merely repeats the advice to use list_agencies, which is already 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 tool lists all routes for an agency, specifies return fields (route IDs, short names, descriptions), and differentiates from siblings like onebusaway_find_routes by indicating it is for enumeration before specific searching.

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 says to use for enumerating an agency's full service before searching and provides a cross-reference to onebusaway_list_agencies for obtaining agencyId. This guides when to use over alternatives.

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 matching routes with IDs, which is the output behavior. It does not discuss pagination or the maxCount parameter's effect on behavior, but those are covered in the 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?

Extremely concise: two sentences convey purpose, output, and use case. No wasted words. The structure is front-loaded with the core action and outcome.

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 description is complete enough. It explains the search capability, return type, and typical use case. The presence of an output schema (not detailed in description) reduces the need to describe return values. Could briefly mention maxCount, but the schema already does.

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% with good descriptions for both parameters. The tool description does not add significant new meaning beyond the schema; it mentions the query parameter implicitly through examples but does not enhance understanding of maxCount.

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?

Description clearly states it searches routes by name/number and returns IDs. The verb 'search' and resource 'routes' are specific. It identifies the tool's role in the workflow but could more explicitly differentiate from the sibling 'onebusaway_find_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?

Explicitly describes when to use: to resolve a route short name to an ID for subsequent lookups with 'onebusaway_get_vehicles' or 'onebusaway_get_schedule_for_route'. It lacks explicit 'when not to use' but provides sufficient context via reference 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. The description adds that it returns IDs and coordinates, which is useful behavioral context. No contradictions or missing safety info.

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, no filler. Every sentence adds value: action, output, and usage guidance.

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 good annotations, the description covers the essential context. Could mention that query is required, but that is clear from the 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 coverage is 100%, so parameters are well-documented in the schema. Description does not add significant new meaning beyond what is in the property descriptions.

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?

Clearly states 'Search for stops by name or code' and describes the output. However, it does not explicitly differentiate from the sibling tool onebusaway_find_stops, so it misses the chance to guide the agent on which search tool to use.

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 a use case ('Use to resolve a human-readable stop name or number to a stop ID for arrivals lookups with onebusaway_get_arrivals.') but does not mention when not to use it or alternatives among siblings.

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