Indian Railways IRCTC

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds the endpoint as a behavioral detail, but doesn't discuss return format, pagination, or data freshness. This is acceptable given the security annotations, but could add more 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 concise sentences. The first sentence front-loads the purpose and usage, the second names the endpoint. No fluff or 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?

With only one parameter, clear annotations, and an output schema present, the description fully covers the tool's operation. It states what it does and the specific endpoint, making it complete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (station_code with example and length constraints). The description's repetition of 'station code' adds no new meaning, so the schema carries the semantic burden. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it's for station arrivals/departures board by station code, and explicitly names the endpoint `/trains/stationLive`. This distinguishes it from sibling tools that focus on specific trains, routes, or PNR status.

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 tells the agent to use this tool when needing a station board by code, providing clear context. It doesn't explicitly mention alternatives to avoid, but the purpose is specific enough to differentiate from siblings like `railway_train_liveStatus` (for a train) without extra 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 the tool read-only and non-destructive, so the description carries a lower burden. It adds useful context by revealing the underlying endpoint (`/trains/betweenStations`) and scoping the geographic context, which supplements the structured metadata effectively.

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?

All three sentences serve a distinct purpose: what the tool does, the underlying API call, and relevant exclusions. There is no fluff or redundancy, making it a model of concise technical writing.

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 full parameter coverage and a documented output schema, the description covers the essentials. The only minor gap is the ambiguous scope of 'when date is not provided' (i.e., what results to expect without a date), but this doesn't detract significantly from overall completeness.

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 both parameters ('from_station' and 'to_station') adequately described as source/destination station codes with examples. The description adds no additional parameter semantics, meeting the baseline for high schema coverage without exceeding 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+resource ('find trains between two station codes') that clearly states what the tool does. The qualifier 'when date is not provided' implicitly distinguishes it from the sibling searchByRouteDate, though it doesn't explicitly name the alternative.

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 both a condition for use ('when date is not provided') and explicit exclusions ('Do not use for non-India routes or booking/payment requests'). However, it stops short of naming a specific replacement tool for the excluded scenarios, keeping it at a 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the specific API call and that it 'returns core train information', which is useful context but does not elaborate on what 'core' includes or any error behavior. With annotations covering the safety profile, a 3 is appropriate—adds some value but not rich behavioral context.

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

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

The description is a single sentence that conveys the main purpose and usage, with zero waste. It is concise, front-loaded, and each clause 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?

The tool has a simple single-parameter input, clear annotations, a 100% schema coverage, and an output schema exists enabling structured results. The description sufficiently covers the use case and behavior for a straightforward lookup tool. It could mention the output format but the output schema handles that, so the description is complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the only parameter 'train_number' is thoroughly described in the schema with format and example. The description adds minimal extra meaning beyond the schema, but the schema already carries the load. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Use this tool when the user asks train details for a known 5-digit train number.' It specifies the verb ('get train details'), the resource ('train number'), and distinguishes it from siblings by emphasizing the known 5-digit number. The internal call '/trains/getTrain' adds specificity.

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 when-to-use guidance: 'Use this tool when the user asks train details for a known 5-digit train number.' It implies the condition of knowing the train number, but does not explicitly mention alternatives like route-based search or live status. Given sibling tools exist for those, the guidance is clear enough to differentiate, though it could explicitly state 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 declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat that. It adds that the tool returns 'current status and running position details,' which is useful, but it does not disclose any limitations, error conditions, or the fact that journey_date is ignored (though that appears in the schema). Overall, it provides some value beyond annotations but is not particularly rich.

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

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

The description is two sentences, front-loaded with usage instruction, and contains zero filler. Every word contributes to clarity, making it appropriately concise.

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, 1 required, has output schema) and strong annotations/schema, the description is nearly complete. It does not mention that journey_date is ignored, but that information is in the schema. It clearly defines what to expect in return, so it is sufficiently complete for a straightforward read-only API.

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 both parameters effectively. The description does not add any parameter-specific meaning beyond what the schema provides; it only mentions 'known train number' which essentially restates the train_number parameter. Baseline 3 applies due to high 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 explicitly states the tool's purpose: to provide current running status/location for a known train number. It specifies the endpoint and the returned information, distinguishing it clearly from sibling tools like station live boards or route inquiries.

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 first sentence gives a clear directive: 'Use this tool when the user wants current running status/location for a known train number.' This provides explicit usage context, though it does not mention alternatives or when NOT to use it, so it loses a point for lacking exclusions.

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 destructiveHint=false, so the safety profile is covered. The description adds the endpoint path `/trains/pnrstatus` but does not disclose additional behavioral details such as response characteristics or error handling; this is acceptable given the annotations but not especially rich.

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 long, front-loaded with the core purpose, and includes the endpoint without unnecessary filler. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, read-only, single-parameter tool with an output schema and clear annotations, the description is largely complete. It could have added a brief note about when to prefer this over railway_train_liveStatus, but the core information needed to select and invoke the tool is present.

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 the single `pnr` parameter fully described as a 10-digit PNR number, including min/max length and an example. The description merely restates this information, adding no new semantic 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 the tool checks ticket PNR status using a 10-digit PNR number, using a specific verb and resource. It distinguishes itself from sibling tools like railway_train_liveStatus by explicitly referring to 'ticket PNR status' rather than train status.

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 opens with 'Use this tool to check ticket PNR status,' which gives an explicit purpose but does not discuss when not to use it or compare it with alternatives. Usage context is implied rather than fully articulated.

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 destructiveHint=false, so safety is covered. The description adds the endpoint call to /trains/getRoute and specifies the input is a known train number, but it does not disclose additional behavioral details such as pagination, availability windows, or partial route responses.

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

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

The description is two sentences, front-loaded with the core use case and a short endpoint reference. Every word earns its place and there is no extraneous content.

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?

This is a simple one-parameter, read-only tool with an output schema provided and accurate annotations. The description fully explains the scope (complete route and stoppages by known train number), so no additional context is needed for the agent to invoke it 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?

Schema coverage is 100% and the single train_number parameter is described as a 5-digit train number. The description adds no additional semantic information beyond reaffirming "known train number," so the baseline of 3 is appropriate since the schema carries the burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool provides "complete route and stoppage details of a known train number," which is a specific and clear purpose. This distinguishes it from sibling tools like live status or PNR status by focusing on full route/stoppage data.

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 "Use this tool for..." when route and stoppage details are needed for a known train number. It does not mention alternatives or exclusions, but the context is clear enough for the agent to choose it among siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context beyond annotations by revealing the actual API endpoint and usage restrictions (India-only, date window), which helps an agent predict behavior without repeating annotation 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, zero fluff. First sentence states exactly when to use, second sentence lists exclusions. Every word earns its place; 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?

For a simple read-only search tool with only 3 params and an output schema, the description covers all key aspects: purpose, endpoint, and exclusions. It doesn't need to describe return values since an output schema exists. The only minor gap is not explicitly stating the response is a list of trains, but that's implied by the name and schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%—all three parameters have clear descriptions and examples. The description text doesn't add any parameter-specific details beyond the schema, which is fine since the schema is self-explanatory. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool does 'date-based route search when source, destination, and journey date are known' and even names the underlying endpoint. It distinguishes itself from siblings by focusing on the route-date search use case and explicitly excluding non-India routes, booking/payment, and future dates beyond 60 days.

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 states when to use ('when source, destination, and journey date are known') and gives three clear negative constraints ('Do not use for non-India routes, booking/payment requests, or dates beyond 60 days'). This effectively tells an agent when NOT to invoke this tool, even though it doesn't name alternative tools.

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