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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description ('load earlier or later train connections') is consistent with these hints but does not add additional behavioral context beyond what annotations provide.

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

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

Two sentences with no filler. The first sentence states the primary action, and the second provides a critical usage hint. 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?

The tool has no output schema, but the description does not explain what the response looks like (e.g., same format as search_connections). However, given the simple pagination use case and rich annotations, the description is mostly complete. Minor gap: no mention of output format or pagination behavior.

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 adds practical context: collection_id comes from a prior search, and direction selects earlier/later. This adds value beyond the schema definition by clarifying usage flow.

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 loads earlier/later train connections from a previous search, using a collection ID. It specifies the verb 'load', resource 'train connections', and distinguishes from sibling tools like search_connections that perform initial searches.

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

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

The description explicitly says to use the collection ID from search_connections results, providing clear context for when to use. It does not explicitly exclude alternative scenarios or mention when not to use, but the context is sufficient for an 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 declare read-only and idempotent. Description adds that it supports specific discount cards and batching limits. 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 tightly packed sentences: purpose, discount support, batching instruction, and source requirement. No wasted words, all relevant.

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?

Sufficient for a simple tool with schema coverage and annotations. Doesn't describe return format, but the tool is straightforward (prices). Minor gap but adequately complete for selection.

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 basic descriptions. The description adds critical context for trip_ids (source and validity) and reinforces discount card meanings. Adds some value 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?

Explicitly states it gets ticket prices in CHF for train connections, specifies discount support, and distinguishes from siblings like search_connections (which doesn't return prices) and get_trip_details.

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?

Clearly advises to use trip_ids from search_connections, to avoid inventing IDs, and to batch up to 10 per call. However, it doesn't explicitly state when to use alternatives, but the context is clear given 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?

The description adds valuable behavioral context beyond annotations: 'On mobile with SBB app installed, opens directly in the app with Halbtax/GA applied automatically.' This discloses platform-specific behavior and default discounts. It aligns with annotations (readOnlyHint=true, no destruction). No 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?

The description is concise with three sentences, each serving a clear purpose: first states the core function, second provides usage guideline, third adds mobile behavior. 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 9 parameters and no output schema, the description is fairly complete. It explains the output (a direct purchase link) and special mobile behavior. However, it lacks information about error handling, or what the link looks like, which could be useful. Still, it covers the essential aspects.

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 does not add significant meaning beyond the schema; it mentions the link is for a specific ticket but does not explain how parameters like reduction_card affect the generated link. The description is adequate but not enriching.

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: 'Get a direct purchase link to buy a train ticket on SBB.ch.' It specifies the verb 'Get' and resource 'direct purchase link', and distinguishes from siblings by stating 'Only call this when the user wants to buy a specific ticket.'

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

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

The description explicitly says 'Only call this when the user wants to buy a specific ticket.' This provides clear context for when to use the tool. However, it does not explicitly mention alternatives or when not to use it, though the sibling tool names (e.g., get_prices, get_trip_details) imply such distinctions.

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 readOnly and idempotent. The description adds specific behaviors: showing intermediate stops, platforms, and occupancy. This enriches the agent's understanding 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 short sentences: first covers purpose and content, second covers prerequisite. No unnecessary words. Front-loaded with the key action.

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?

While there is no output schema, the description lists key return elements (intermediate stops, platforms, occupancy). For a simple read-only tool with one parameter, this 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?

Schema description coverage is 100% for the single parameter trip_id, with the same prerequisite text as the tool description. The description adds no new semantic meaning beyond what is 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 'Get detailed information about a specific train connection' and lists contents (intermediate stops, platforms, occupancy). It distinguishes from siblings like search_connections by specifying a single trip ID.

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

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

The description explicitly says 'Use a trip ID from search_connections results,' providing a clear prerequisite. While it doesn't list when not to use, the context and sibling list imply this is for detailed view after search.

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, destructiveHint=false, and idempotentHint=true, indicating a safe, non-destructive read. The description adds valuable behavioral context: 'name resolution happens internally' (explaining input handling), 'Live data: includes delays and cancellations for trains departing within 30 min' (scope of real-time data), and the nuanced behavior of the 'arrival_time' parameter (defaults to departure time, only set true for explicit arrival requests). 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 a single paragraph but is well-structured and front-loaded with the main purpose. Every sentence adds value: input acceptance, return contents, live data scope, and parameter clarification. It is not overly long, though a slight restructuring could improve scanability. Overall, it is appropriately sized for the complexity.

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 5 parameters, no output schema, and sibling tools, the description is remarkably complete. It explains input formats, what is returned (times, duration, transfers, trip IDs), live data scope, and how to use parameters like 'arrival_time' correctly. It also hints at downstream usage (trip IDs for pricing/details/tickets). The description fully covers the tool's behavior without needing an output schema.

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

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

Schema coverage is 100%, so parameters are described in the input schema. The description adds significant semantic value beyond the schema: it clarifies that station names can be used directly (not just IDs), explains the 'arrival_time' parameter's default and when to override, and specifies that 'time' is treated as departure by default. This extra guidance is helpful for correct use.

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 'Find train connections between two Swiss stations', using a specific verb ('Find') and resource ('train connections'). It further specifies input flexibility (station names or UIC IDs) and output details (live schedules, delays, cancellations). This effectively differentiates from sibling tools like 'search_stations' (station search only) and 'get_trip_details' (details for a specific trip).

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

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

The description provides clear context: it accepts station names or IDs, returns live schedules, and mentions that live data includes delays for departures within 30 min. It also explains the behavior of the 'arrival_time' parameter and when to set it to true. However, it does not explicitly state when not to use this tool or recommend alternatives (e.g., 'get_more_connections' for pagination), so it misses some explicit 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 indicate read-only, idempotent, non-destructive behavior. The description adds value by specifying the format of returned IDs (e.g., '8503000') and the context of use. 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 wasted words. Purpose is front-loaded, and every 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 no output schema and simple parameters, the description is adequate. It explains return format and usage context. Minor gaps like pagination or empty results handling are acceptable for a simple search.

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. Description provides examples ('Zurich', 'Bern') but no additional semantics beyond what the schema already offers.

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 Swiss train stations, addresses, or POIs by name and returns UIC IDs. It distinguishes itself from 'search_connections' by explaining when this tool is needed.

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

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

The description explicitly says the tool is only needed when the user asks for station info or needs disambiguation, and notes that 'search_connections' accepts names directly, providing clear when-to-use guidance.

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