RailRoute journey planner

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds a crucial non-obvious trait: 'It spends a metered upstream call.' This is beyond the annotations and informs the agent about cost/rate limits, influencing call frequency. It also states 'Live' availability, aligning with openWorldHint. No contradictions with annotations are present.

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 waste. It front-loads the core function, then adds the alternative-bookings detail and a practical warning about the metered call. Every sentence earns its place, making it concise 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?

With no output schema, the description should clarify what the tool returns. It mentions 'seat availability per class' and alternative booking options but doesn't describe the response structure, such as how alternatives are listed or whether quotas are included. While the purpose is clear, an agent may not know exactly what to expect from the output, making it incomplete.

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 50%, with descriptions for 'from', 'to', and 'include_rac' but not for 'train_number', 'date', or 'quota'. The description refers to 'one train on one date' implicitly covering train_number and date, and 'per class' implicitly relating to quota, but it doesn't explain these parameters explicitly. It partially compensates for missing schema details but leaves room for ambiguity, especially regarding 'quota' and date format.

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: 'Live seat availability per class for one train on one date' and further specifies it covers alternative booking methods when the through ticket fails. It distinguishes itself from sibling tools like train_schedule or journey_calendar by focusing on booking options and waitlist rescue, with the phrase 'This is the tool that rescues a waitlisted train.' This makes the purpose specific and distinguishable.

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 clear context for when to use it: 'when the through ticket will not confirm' and 'rescues a waitlisted train.' It also advises to query only trains the traveller is actually considering, which is a practical usage guideline. While it doesn't explicitly name alternatives to avoid, the unique use case is well defined, making the intended scenario obvious.

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 the tool as read-only and idempotent, so the description only needs added behavioral context. It provides useful behavior beyond the schema: a place aggregates all stations and airports, and typing a station code like 'CSMT' resolves to its city while reporting which terminal matched. This gives the agent a strong mental model of how results are grouped.

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 front-loaded with the core purpose and the critical usage instruction, followed by a concise explanation of the place concept and a concrete example. Every sentence earns its place with 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 simple read-only lookup with two parameters and no output schema, the description is largely complete: it explains input semantics, output-level behavior (city plus matched terminal), and how the tool fits before plan_journey. It could mention limit behavior or empty-result handling, but these are minor gaps given the tool's simplicity.

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 50%: the query parameter is described in the schema, but limit is not. The description adds value by showing station-code input works and that the result is city-level with terminal matching, but it does not explain the limit parameter or its effect on results. This partially compensates for the schema gap but does not fully cover it.

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 a specific verb and resource: it 'turn[s] what somebody typed into RailRoute place ids'. It clearly distinguishes this lookup/geocoding tool from journey-planning and station-info siblings by explaining that a place is a city with stations and airports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage context: 'ALWAYS call this before plan_journey.' This tells the agent when the tool is needed in the workflow. It does not, however, explicitly state when to choose an alternative like nearby_stations instead, so it stops short of full exclusion 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds a key behavioral boundary: 'Timetable only — it says nothing about seats.' It also implies a focus on direct trains, which is extra contextual nuance. These details help an agent know what to expect without contradicting the 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 concise and well-structured: the first sentence states the core purpose, the second gives usage context, and the third clarifies a critical limitation. Every sentence earns its place with no redundancy, and the most important 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?

The tool is simple and the description gives a solid high-level overview, but it does not describe the exact output format (e.g., a list of dates or a weekly pattern summary). It also leaves the 'days' parameter's meaning and default behavior unexplained, which is a gap given there's no output schema to rely on. An agent might be uncertain about what is returned and how to interpret the 'days' input.

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 75% (from, to, start_date have descriptions), so the baseline is 3. However, the description does not elaborate on the 'days' parameter, which lacks a schema description. The phrase 'span of dates' indirectly references start_date and days, but no explicit meaning is added. The description neither compensates for the missing days description nor enhances the existing ones.

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: 'Day-by-day service over a span of dates for a station pair: which days have a direct train and which have none, plus the weekly pattern.' It specifies a concrete resource (service availability for a station pair) and a distinct behavior (day-level pattern) that separates it from sibling tools like train_schedule or next_confirmed_date.

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 explicit when-to-use guidance: 'Use this when somebody is flexible about when they travel, or asks "does it run on Sundays"' and a clear when-not: 'Timetable only — it says nothing about seats.' It does not name an alternative tool for seat checks, but the context is sufficient to route an agent appropriately.

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 and idempotentHint=true, covering the safety profile. The description adds behavioral detail beyond annotations: it returns 'other' stations (excluding the input one) and orders them nearest first.

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 function and ordering; the second provides targeted 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?

The core purpose and usage are clear, and annotations cover read-only/idempotent behavior. However, with no output schema and zero parameter documentation, the description leaves important operational details about limit and radius_km unstated, making it adequate but not 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?

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It only vaguely references a radius and never names station_code, limit, or radius_km, nor explains units, defaults, or constraints. This is a significant 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 states a specific behavior: returning other railway stations within a radius, ordered nearest first. It also distinguishes itself from the planner, which already does this internally, so an agent can tell it apart from siblings like plan_journey.

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 when to use the tool (a place has no service of its own) and when not to (the planner already handles this internally; reach for it only when asked directly). This gives clear guidance on tool selection relative to 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 and openWorldHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the search horizon of 'up to a month', the route scope of direct and one-change trains, and the operational constraint that it is 'EXPENSIVE' and 'limited to a few calls an hour.'

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 earning its place: core behavior, when to use, and cost warning with an alternative. It is front-loaded with the most important information 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?

For a moderately complex tool with no output schema, the description covers what the tool returns, the search horizon, the journey types included, usage context, cost limits, and an alternative. It does not state what happens if no confirmed date exists within the month, but the phrase 'first date' and 'up to a month' make the behavior reasonably inferable.

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 75% and from/to/date already have clear descriptions like 'Origin station code' and 'The date to search forward FROM.' The description reinforces the date semantics with 'Search forward' but does not clarify the quota parameter or add detail 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 opens with a specific verb and resource: 'Search forward up to a month for the first date this route can actually be travelled with a confirmed berth.' It distinguishes the tool from siblings by explicitly scoping to 'direct trains and one-change journeys together' and by positioning it against check_train_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 gives explicit when-to-use guidance: 'Use it when a traveller is flexible about WHEN and the date they asked for is waitlisted.' It also names the alternative check_train_options for the single-date case, leaving no ambiguity about 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.

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

Annotations already cover readOnly and idempotent safety, and the description adds substantial behavioral context: it explains that the tool aggregates from multiple reservation systems, prices trains per class when train_class is omitted, adjusts departure day with arrive_by, and ranks modes together by default. It discloses that it includes government buses and that they may be the only through service. No contradictions with annotations; the description meaningfully extends beyond the structured metadata.

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 longer than typical but well-structured: purpose first, then bus-specific rationale, then parameter guidance. Every sentence contributes value, and it is front-loaded with the core function. While slightly verbose, it is not padded and reads coherently as a complete usage guide.

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 10 parameters and no output schema, the description covers all essential usage decisions: what results are returned, when to include buses, how to handle train class, modes, arrival-based timing, and the meaning of limit. It also directs the user to find_place for IDs. No critical context is missing for an agent to call the tool 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 90%, so the schema already documents most parameters. The description adds semantic depth for train_class (explains pricing behavior), modes (restriction semantics), and arrive_by (date interpretation), and clarifies that limit applies per kind. However, the quota parameter has no schema description nor any mention in the tool description, leaving a minor gap that the description does not compensate for.

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 and resource: it plans a journey by enumerating all practical modes (direct trains, one-change journeys, flights, mixed, government buses). It explicitly contrasts with sibling tools by framing itself as the comprehensive 'whole answer in one call', and even references find_place for IDs, making its purpose distinct and 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 gives explicit when-to-use guidance, including a dedicated paragraph for bus questions and a concrete example (Mysuru–Mangaluru) where buses are the only through service. It also instructs when to pass train_class, modes='trains_only', and arrive_by, and even states not to ask the traveller to choose modes because the planner is designed to avoid that. This leaves no ambiguity about when to prefer this tool over 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 read-only, idempotent, and closed-world behavior. The description adds meaningful detail beyond that: results are in departure order, contain scheduled times only (not real-time), and represent the full enquiry board for the station.

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 tight sentences deliver purpose, ordering, scope, and the key alternative. The core meaning is front-loaded and every clause 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 simple read-only listing tool, the description fully covers what it returns, how results are ordered, what data they contain, and when to choose it over the main sibling. No output schema exists, but the return semantics are sufficiently described.

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 documents station_code and after with descriptions, and limit has clear defaults and bounds. The tool description does not add parameter-specific detail, so it neither compensates for nor harms the 67% 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 states exactly what the tool returns: every scheduled train at a station in departure order. It also distinguishes itself from a journey plan and from plan_journey, making its purpose 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?

It explicitly gives the decision rule: use plan_journey when the user wants to reach a destination, use station_departures when asking what leaves from this station. This is concrete, actionable guidance that prevents mis-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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds valuable context: that the data is purely scheduled (not real-time) and that stops are returned 'in order,' which are behavioral traits an agent needs beyond the 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, no filler. The core purpose is front-loaded (first sentence states exactly what the tool returns), and the second sentence adds a critical constraint in one clause. Every word earns its place without 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?

The tool is simple (one parameter, no output schema) and the description adequately explains the output content and its scheduling nature. It does not specify the exact format of return values (e.g., whether times are ISO strings), but for such a basic read-only tool this is not a severe omission, and annotations cover the read-only aspect.

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 0% schema description coverage, the description must compensate for parameter documentation, but it does not mention the train_number parameter at all. The name is self-explanatory and the schema gives a pattern, so there is minimal ambiguity, but the description adds no semantic meaning beyond what the schema already 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 the tool returns 'every stop of one train with its scheduled arrival and departure, in order.' This specifies the verb (provide/return), resource (one train's stops), and scope (entire itinerary), distinguishing it from sibling tools like station_departures that cover multiple trains from a single station.

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 says 'Scheduled times only — this says nothing about where the train is today,' which implies this tool is not for real-time tracking, but it does not name specific alternatives or give explicit when-to-use guidance. The usage context is only implicitly derived from the contrast with real-time status, falling short of explicit routing.

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