Platform Whisperer

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

Annotations already declare this as safe, read-only, idempotent, and open-world, so the description is not carrying the full safety burden. It still adds valuable behavioral context: every candidate is returned with a match quality, no silent choice is made, due_now is included when the expected time passes without a recorded departure, and predictions are unofficial versus official station screens.

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 action and then adds only high-value clauses: due_now inclusion, candidate/match-quality return contract, exact-match destination rule, read-only status, and the unofficial-prediction caveat. 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 6-parameter search tool with no output schema, the description covers result semantics (all candidates with match quality), data reliability, and special temporal handling well. The main remaining gap is that the return shape/fields are not described beyond 'match quality,' which could matter without 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 description coverage is high (83%), so the schema already documents most parameters. The description adds useful nuance for destination matching (station code or full name is an exact match) and for the due_now temporal condition, but it does not clarify headcode, after/before semantics, or include_departed beyond what the schema says.

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 gives a specific verb+resource ('Search for a train') and adds scope details: due_now handling, candidate returns with match quality, and exact-match destination behavior. It implicitly distinguishes itself from a single-result tool like get_train by promising every candidate rather than a silent choice, but it never names any sibling directly.

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?

Usage is only implied. The description explains what the tool does when searching for a train and why candidates/matches are returned, but it does not state when to prefer it over get_train, get_departures, or list_stations, nor does it give 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?

Substantial disclosure beyond annotations: the 15-minute drop rule for trains without a departure, the hiding of departed trains unless include_departed is true, the lifecycle states including platform_withdrawn and due_now, absent fields meaning unknown, and times being London local with offset. It also warns predictions are unofficial and station screens are official — exactly the caveats an agent needs before acting on the data.

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?

Content is dense and largely front-loaded, but it arrives as one long run-on paragraph with deep parentheticals that interrupt the lifecycle explanation. It earns its length in information, though not in structure — bullet-style separation of lifecycle states would help.

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 carries the return-shape burden and does so reasonably: platform, times, lifecycle states, absent-equals-unknown. What it does not address is anything about volume (how many departures typically, any cap) or ordering, which matters for a list-shaped read.

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 80%, so the baseline is high, but the description still adds real semantics for operator (case-insensitive partial name or short form, with examples) and for the behavior tied to include_departed. It leaves window_min's unit/meaning to the schema, which supplies min, max, and default, so the gap is small.

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 opening clause names a specific resource (departures), a scope (the next window), and the key payload (released or predicted platforms), so an agent knows exactly what it gets back. It does not differentiate itself from siblings like find_train or get_train, though the resource noun does most of that work implicitly.

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?

Usage is implied rather than stated: include_departed is explained and the operator filter is given examples, which tells the agent how to broaden results. But there is no explicit 'use this when / use get_track_record instead when' routing against the four siblings, so the agent must infer the boundary.

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, idempotentHint, and destructiveHint=false, and the description adds useful behavioral context: simulated crowd is excluded, predictions are unofficial and may be wrong, and station screens are authoritative. It does not cover return format or pagination, but the added caveats are meaningful 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?

The description is short and front-loads the core output. 'Read only' is redundant with annotations, but the remaining sentences about exclusion criteria and official sources earn their 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?

With no output schema and only 50% parameter description coverage, the description should do more to explain the return shape and the role of the 'days' parameter. It adequately conveys the metric and caveats but is incomplete for an agent needing to call it 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 50%, with 'station' documented in the schema but 'days' undocumented. The description does not mention either parameter, so it does not clarify the meaning of the days window or how station affects the accuracy breakdown, leaving a notable gap for the undocumented parameter.

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 analytical output: measured accuracy by minutes before release, with sample sizes. It clearly distinguishes the tool from train/departure/station lookup siblings by focusing on prediction reliability, though it does not explicitly name 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?

It provides a data-quality warning about unofficial predictions and official station screens, but gives no explicit guidance on when to call this tool versus siblings like get_departures or get_train. There are no exclusions or recommended contexts beyond the caveat.

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, idempotent, non-destructive and openWorld, so the safety profile is covered; the description adds real value beyond that with failure semantics (candidates on ambiguity, non-retryable train_not_on_board) and a reliability caveat that predictions are unofficial and station screens are authoritative. The 'Read only' sentence merely restates the annotation and earns nothing.

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?

Purpose is front-loaded in the first clause and the subsequent sentences each carry distinct information about identification and failure modes. The only wasted line is 'Read only,' which repeats the annotation, and the reliability caveat is dense but worth its space.

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 carries the return-value burden and does so at a high level (platform status, including departed and withdrawn trains) plus explicit error outcomes and non-retryability. It omits what fields the status payload contains and the role of station, which are the remaining gaps for a 4-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?

Schema coverage is 75% and the schema already documents headcode as an alternative to train_id used with time, so the description's headcode+time explanation largely duplicates structured data. The description adds the multi-match candidate behavior, but never mentions the station parameter or its EUS default, so it does not compensate for the one undocumented parameter.

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 opening clause states a specific verb and resource: 'Full platform status for one train id,' and immediately scopes it to include departed, due_now and platform_withdrawn trains. It does not name the sibling find_train, so the agent must infer the boundary, but the resource and return scope are 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 clearly explains the two identification paths (train_id, or headcode plus time 'HH:MM today') and the conditions under which each fails: several matches return candidates, a headcode alone returns train_needs_time, and an off-board train returns train_not_on_board which is explicitly non-retryable. It gives no explicit guidance on when to prefer this over find_train, which keeps it short of a 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, idempotentHint=true, and destructiveHint=false. The description reinforces the read-only nature and adds useful trust context: predictions are unofficial and may be wrong, while station screens are the official source. It does not describe return format or ordering, but the added reliability caveat is meaningful 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?

The description is short, front-loaded with the core action and returned fields, and contains no filler. The 'Read only' sentence repeats the annotation, and the predictions caveat is somewhat tangential to listing stations, but both are brief enough not to undermine conciseness.

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 zero parameters, rich annotations, and no output schema, the description provides enough context to call the tool correctly. It states what is returned and includes an important data-accuracy caveat, though it could more explicitly relate to sibling tools for routing purposes.

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

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

The tool has zero parameters, so there is no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description correctly does not invent input 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 gives a specific verb and resource ('List stations') and previews the returned fields (enabled status, platform range). It does not explicitly distinguish the tool from siblings like find_train or get_departures, but the purpose is clear without opening the schema.

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?

There is no explicit guidance on when to use this tool versus alternatives such as find_train or get_departures. Usage is only implied by the verb 'List stations', leaving the agent to infer its place among sibling tools.

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