onebusaway-mcp-server

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

The description is consistent with the readOnlyHint annotation, and adds that it returns route IDs, short names, and descriptions. It does not reveal additional behavioral traits beyond what annotations already indicate, thus performing adequately.

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 action, describing the output, and suggesting follow-up usage. No redundancy or verbose language.

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 4 parameters and an output schema, the description covers the essential aspects: purpose, output format, and result usage. It does not mention edge cases (e.g., no routes found), but given the schema's presence, this is acceptable.

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?

With 100% schema description coverage, the input schema already documents all four parameters. The description only paraphrases the query filter, adding minimal new meaning. No extra constraints or formatting details are provided.

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 'Find transit routes near a location, optionally filtered by name or number', which clearly specifies the action and resource. Although it distinguishes itself from siblings like onebusaway_search_routes by emphasizing location, it does not explicitly contrast with alternatives.

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 on when to use this tool versus siblings such as onebusaway_search_routes or onebusaway_list_routes_for_agency. It only provides post-invocation advice ('Use routeId values...'), but does not help the agent decide between 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 indicate readOnlyHint: true, and the description adds detail about the search behavior (radius limits, return fields). No contradictions. The description enriches understanding 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 sentences with front-loaded purpose, followed by return fields, a usage tip, and optional filter. Every sentence is essential and well-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?

For a simple search tool with 4 params, output schema present, the description covers inputs, output fields, optional filter, and downstream usage. 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 covers all 4 parameters with descriptions. The description adds real-world context: 'the number printed on the stop sign' for query param and 'Max ~1600m before results degrade' for radius. These clarifications are valuable.

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, distinguishing it from sibling tools like onebusaway_find_routes (finds routes) and onebusaway_search_stops (likely search by name/string). It specifies return fields and usage context.

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 guides users to use stopId values with onebusaway_get_arrivals for real-time arrivals. It also mentions the optional stop code filter. While it doesn't enumerate all alternatives, the guidance is clear and actionable.

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 set readOnlyHint=true, and the description adds behavioral details about the response content (summary, description, reason, affected stops/routes, etc.), which goes beyond annotations. No contradictions; the description aligns with 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 effectively convey the purpose and usage context with no wasted words. The structure efficiently front-loads the action and lists key return fields.

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 existence of an output schema, the description need not detail return format. It sufficiently covers the tool's role among siblings, the single parameter source, and the key return fields, making it fully adequate for an agent.

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 schema parameter description already explains the source of the ID. The overall description reiterates this source, adding marginal extra value. Baseline of 3 is appropriate because the schema does the heavy lifting.

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 uses specific verb 'Fetch' and resource 'service alert (situation) by ID'. It lists the returned fields (summary, description, reason, affected stops/routes, consequence, active time windows), which clearly distinguishes this from sibling tools like onebusaway_get_arrivals or onebusaway_get_route.

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 states that situation IDs come from onebusaway_get_arrivals responses, providing clear context for when to use this tool (after retrieving arrivals). It does not explicitly list when not to use it, but the context is sufficient for an experienced 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?

The readOnlyHint annotation is present, confirming safe reads. The description adds behavioral detail beyond annotations: it explains the 'predicted' boolean meaning (GPS-backed vs schedule-only), time windows via minutesAfter/minutesBefore, 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 a focused paragraph of four sentences. It opens with the core purpose and then lists key outputs and usage notes. Every sentence adds useful information without repetition. Slight improvement could structure with bullets, but current form is 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 moderate complexity (3 params, output schema exists, readOnlyHint provided), the description covers all necessary aspects: what it returns, how to interpret data (predicted boolean), how to use IDs, and default time windows. No gaps for agent decision-making.

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?

All three parameters have schema descriptions, giving 100% coverage. The description adds value by explaining defaults (minutesAfter=35, minutesBefore=5) and clarifying that stopId uses agency prefix. It also interprets the 'predicted' field, which is not in the parameters but enriches understanding of the output.

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 uses specific verbs ('returns') and resource ('real-time arrivals and departures at a stop'), and lists concrete data items (predicted arrival times, schedule deviation, etc.). It distinguishes from siblings by mentioning follow-up use of tripId with onebusaway_get_trip and referencing onebusaway_find_stops/search_stops for ID discovery.

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 clearly states the tool's purpose and context (real-time arrivals at a stop). It provides guidance on using tripId for follow-up calls and on the stop ID format, including how to discover IDs. While it does not explicitly state when not to use it, the guidance is sufficient for most scenarios.

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 tool has readOnlyHint: true annotation, so the description adds value by explaining what the output contains ('returns all trips in order with their stop times') and the concept of a block. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, front-loaded with the main action, and each sentence provides essential information: definition, output, use case, and data source. 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?

Given the tool has one required parameter, no enums, and an output schema explaining return structure, the description provides complete context: what a block is, why to use it, and how to get the required ID. It references sibling tools appropriately.

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 already describes the blockId parameter with a clear description. The tool description adds further elaboration on how to obtain the blockId, enhancing understanding beyond the schema alone.

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'), the resource ('by block ID'), and what it returns ('all trips in order with their stop times'). It also distinguishes from sibling tools by explaining that block IDs appear in onebusaway_get_trip responses.

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 usage context ('when will this bus return?' and fleet tracking) and how to obtain the blockId via other tools. However, it does not explicitly state when not to use this tool or compare it to 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. Description adds value by specifying return fields (short name, description, agency, route type, schedule URL) and ID format, enhancing behavioral understanding beyond the 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: first states purpose and returns, second explains ID format. Front-loaded, no extraneous 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?

For a simple single-ID fetch tool with output schema, the description covers purpose, parameter format, return fields, and discovery alternatives. Complete given low complexity and good annotations.

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 description for routeId. The tool description adds the ID format and example, but the schema already includes similar info. Minimal additional meaning for the parameter beyond what schema provides.

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 'Fetch details for a specific route by ID' and lists return fields. The ID format ties to routes, distinguishing from sibling tools like get_stop 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?

Explicitly mentions using onebusaway_find_routes or onebusaway_search_routes for discovering IDs, implying when to use this tool. No explicit exclusions but context is 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. Description adds that it returns 'up to all trips' and specifies return contents (trips, stop sequences, departure times). No contradictions, though could add pagination or limit details.

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 core purpose, followed by an alternative use case. No wasted words; every sentence serves a 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 only 2 parameters fully described in schema, the description covers all necessary context: what it does, what it returns, when to use alternative. 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 parameters are well-documented in the schema itself. Description does not add new semantic information beyond what is in the schema (e.g., date format, routeId prefix). 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?

Clearly states 'Full-day schedule for a route' with specific resources (trips, stop sequences, departure times) and distinguishes from 'onebusaway_get_arrivals' for live predictions. References sibling tool explicitly.

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 when to use (for full-day schedule) and when not to ('For live predictions, use onebusaway_get_arrivals at specific stops instead'). Also mentions default date behavior.

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 behavioral context such as 'Full-day departure schedule' and 'lists every departure by route and direction,' which enriches understanding beyond annotations without contradiction.

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 with front-loaded purpose, followed by a separate usage guideline line. Every sentence is essential and there is no wasted 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 (2 params, no enums, output schema present), the description fully covers purpose, usage, parameter guidance, and alternative tools, leaving 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 coverage is 100%. The description adds value by providing concrete examples for stopId and noting the date default, though most information is already in the schema. The addition of discovery guidance for stopId is helpful.

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 'Full-day departure schedule for a stop' with a specific verb and resource, and explicitly distinguishes from sibling 'onebusaway_get_arrivals' by stating 'For live predictions, use onebusaway_get_arrivals instead.'

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: 'Useful for planning or when real-time data isn't needed. For live predictions, use onebusaway_get_arrivals instead.' This gives clear when-to-use and when-not-to-use directions.

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 mark readOnlyHint=true, and the description lists what data is returned (name, coordinates, etc.), adding helpful behavioral context beyond annotations. 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 with no redundant information. The main action and key details (what's returned, ID format) are front-loaded and efficiently communicated.

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 output schema exists, the description adequately covers all needed context: purpose, input format, and output contents. No gaps for a straight-forward single-parameter 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?

The input schema covers the stopId parameter with a description and example, and the description adds the format {agencyId}_{localId} and references discovery tools, enhancing understanding beyond the schema alone.

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 stop by ID, listing returned fields (name, coordinates, direction, routes, accessibility). This distinctive purpose is well-separated from sibling tools for finding stops, routes, or 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 the stop ID format and references using onebusaway_find_stops or onebusaway_search_stops to discover IDs, giving clear guidance on how to obtain required input. It lacks explicit when-not-to-use guidance, but the 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?

Annotations already declare readOnlyHint=true, and the description adds behavioral details: returns vehicle position, schedule deviation, current phase, and remaining stops. 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 with no waste. First sentence gives purpose and output, second provides usage guidance. Front-loaded 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 output schema exists and annotations are present, the description covers purpose, input suggestions, and return value summary. Complete for a 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 coverage is 100%, so the baseline is 3. The description adds minor context (e.g., 'Only needed for trips from a previous service day' for serviceDateMs) but does not significantly extend schema details.

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 'Real-time status and stop sequence for a trip,' specifying the verb (get) and resource (trip status). It distinguishes from sibling tools like onebusaway_get_arrivals by mentioning using tripId from that tool, clarifying 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?

The description instructs to 'Use tripId from onebusaway_get_arrivals to look up a specific vehicle's progress,' providing clear context. It does not explicitly list when not to use it, but the guidance is sufficient for a narrow tool.

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?

Discloses that route filtering is client-side (all vehicles fetched first) which is valuable beyond the readOnlyHint annotation. 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?

Three sentences, front-loaded with purpose, no filler. Each sentence adds value.

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 and annotations cover read-only, description fully addresses purpose, usage, parameters, and a key behavioral detail.

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 has 100% coverage, but description adds context: routeId is 'agency-prefixed' and 'client-side filtering' explains behavior beyond 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 'Real-time positions of all active vehicles for an agency', with a specific verb and resource. It distinguishes from sibling tools like get_arrivals by focusing on vehicle positions.

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 references onebusaway_list_agencies for obtaining agencyId. However, it does not explicitly state when not to use this tool or compare to all 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?

The description adds value beyond the readOnlyHint annotation by specifying the exact data returned (IDs, names, contact info, etc.) and the scope ('served by this instance'). 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 concise sentences: the first states the action and scope, the second connects to other tools. No unnecessary words or repetition.

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 zero parameters, existing output schema, and simple functionality, the description is fully complete. It explains what the tool returns and its relevance to other tools.

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?

With zero parameters and 100% schema coverage, the description does not need to add parameter semantics. However, it compensates by describing the output, which is useful for an agent. The baseline for 0 params is 4, and this is met.

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 for the OneBusAway instance and specifies the returned fields. It distinguishes itself from siblings as the only tool for listing agencies, and the mention of agency IDs being needed for other tools reinforces its role.

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 connects this tool to downstream tools (onebusaway_list_routes_for_agency, onebusaway_get_vehicles) by stating that agency IDs are required. While it does not provide when-not-to-use guidance, the simple nature of the tool with no parameters 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?

Annotations already provide readOnlyHint=true. Description adds that it returns route IDs, names, and descriptions, which is useful but does not disclose additional behavioral traits like pagination or rate limits beyond what annotations cover.

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 short sentences, each serving a purpose: function description, return contents, usage guidance. No fluff.

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 one parameter, high schema coverage, existing output schema, and annotations, the description covers purpose, when to use, return format, and parameter sourcing. Fully adequate.

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?

Input schema has 100% coverage, so baseline is 3. Description adds value with examples ("1" for Metro Transit) and cross-reference to list_agencies, beyond the schema's brief 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 a given agency, a specific verb-resource combination. It distinguishes from siblings like onebusaway_find_routes and onebusaway_search_routes by implying full enumeration, and from onebusaway_get_route which is singular.

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 this before searching for a specific route, and references onebusaway_list_agencies to get agencyId. Does not explicitly say when not to use, but context is clear enough.

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 reiterate safety. The description adds behavioral context that the tool returns 'matching routes with IDs', which is useful beyond the annotation. 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: first states the core action, second provides a concrete use case. No unnecessary words, perfectly 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?

For a simple search tool, the description covers the core functionality, parameter guidance, and a concrete use case referencing downstream tools. With an output schema present, no need to detail return values. Complete and context-rich.

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 having a clear description in the schema. The tool description adds minimal extra value (e.g., the example '44'), but baseline 3 is appropriate since the schema already covers the semantics adequately.

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 'Search', the resource 'routes', and the search criteria 'by name or number'. It further specifies the purpose: to resolve a route short name to a route ID for downstream lookups, distinguishing it from potential siblings like 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?

The description explicitly states when to use this tool: 'to resolve a route short name (e.g. "44") to a route ID for schedule or vehicle lookups with onebusaway_get_vehicles or onebusaway_get_schedule_for_route'. This provides clear context and references specific sibling tools as downstream uses.

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 mark it as read-only. The description adds that it returns matching stops with IDs and coordinates, which is consistent and provides additional context beyond the 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?

The description is two sentences, each earning its place: the first defines action and output, the second provides the use case. 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?

Given the output schema, annotations, and full schema coverage for parameters, the description is sufficient. It covers purpose, output, and context for use, leaving no critical 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?

The schema descriptions already cover both parameters (query and maxCount) at 100%. The description does not add substantial new meaning to the parameters beyond what the schema provides.

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 searches for stops by name or code and returns IDs and coordinates. It distinguishes itself from siblings by explicitly mentioning its use for arrivals lookups with 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?

It provides a clear use case: resolving a stop name/code to a stop ID for arrivals lookups. However, it does not explicitly exclude scenarios or compare with other search tools like onebusaway_find_stops.

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