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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so safety is covered. The description adds genuinely non-obvious behavior: results are ordered by the sequence in which rules are tried, values come from TfL's raw reason text, and a null cause means unknown. It doesn't say anything about whether the list is static or changes with TfL data updates, which would help an agent decide on caching.

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, both carrying content: one defines the output and ordering, the other connects it to `disruptions` and handles the null case. It's front-loaded with the core definition. The phrasing 'puts disruptions down to' is informal internal jargon that costs a little parse time versus 'attributes disruptions to'.

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 parameters, no output schema and annotations covering the safety profile, the remaining burden is describing what comes back and how to use it — and the description does both, including ordering and the null/unknown convention. An agent has everything needed to call it correctly and interpret results.

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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description does clarify the semantics of the related `cause` value consumed elsewhere, which is a useful adjunct but not a parameter explanation.

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 names a specific resource (the cause codes Tifa derives from TfL reason text) and states its shape (codes with labels) and ordering (rule-trial order). It distinguishes itself from siblings by tying directly to the `cause` field of `disruptions`. It lacks an explicit verb like 'list' or 'returns', relying on a noun phrase, which slightly blunts the statement of purpose.

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 a clear use context: these codes are what `disruptions` accepts as `cause`, and it explains the edge case that a null cause is unknown and `cause=unknown` finds those records. What's missing is an explicit statement of when to call this versus `disruptions` (e.g. 'call this first to discover valid filter values'), so the routing is implied rather than stated.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds substantive behavior: the default window is the last 7 days and the queryable range is capped at 90 days, a constraint absent from the schema. Per-day granularity and the 1440-polls-per-day denominator are also disclosed. That is real added context above 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?

One sentence that front-loads the time scope and then lists outputs in a tight enumerated series; every clause carries content. The opening 'When Tifa was watching' is the one piece of jargon a reader must infer a meaning for.

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 effectively serves as the return-value contract by naming each reported metric, which is exactly what an agent needs to decide whether to call it. It omits pagination/shape details and cost, but for a two-optional-parameter read-only report it is close to sufficient.

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 per-field format details (ISO 8601, epoch seconds, London dates) need no repeating. The description nonetheless adds the effective default range (7 days to now) and the 90-day maximum, which the schema does not state. Modest but genuine value beyond the structured fields.

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 enumerates the specific payload: per-source spans, share of range watched, uncovered gaps, and per-UTC-day poll counts (of 1440) and failures. That is far more concrete than the bare name 'coverage'. It never differentiates itself from siblings such as period_stats or current_status, and the phrase 'When Tifa was watching' is unexplained shorthand, so it falls short of a 5.

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?

Gives a crisp use condition: 'Check it before reading a quiet period as a good one' – i.e. use this to validate whether silence means no data versus no events. It offers no explicit when-not or named alternative among list_lines/period_stats, so it is clear guidance without 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 readOnly/idempotent, yet the description adds substantial behavior beyond them: a one-minute refresh cadence from TfL, the ordering of results (live problems, planned works, good service), and the precise meaning of `stale` including the five-minute threshold and the history-unreadable fallback. That staleness contract is exactly the kind of context an agent needs to decide whether to trust the answer.

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?

Front-loaded with the core purpose, and every clause (ordering, stale definition, disruption payload) contributes information an agent would otherwise have to discover empirically. It is a dense run-on sentence spanning several semicolon-delimited ideas, which slightly hurts scannability but not substance.

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 must describe the return shape, and it does: status text, worst severity, TfL reasons, good-service boolean, live-vs-planned flag, open disruptions with start times and causes, last poll time, and the stale flag. Nothing an agent needs in order to interpret the response is missing.

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 single `mode` parameter is fully documented with an enum, so the schema carries the load. The description's 'every line' hints at the omitted-mode default but adds no new semantics beyond the schema, which is the expected baseline here.

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 picture: it returns the current status of every line plus open disruptions, the last poll time, and a stale flag. The phrase 'every line' implicitly separates it from the per-line sibling line_status, but no sibling is named explicitly, so an agent must infer the boundary rather than read it.

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?

'Right now' and the stale flag imply this is the snapshot tool to use for present-moment questions, but there is no explicit when-to-use versus line_status, disruptions, or period_stats. The exclusion logic is left to inference.

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, non-destructive, closed-world, and the description still adds real behavioral context beyond them: default and maximum time window, sort order, null end while an incident is ongoing, the 'estimated end' flag meaning recording was paused, and how pagination works. Pagination guidance ('call again with next_cursor and the same other arguments') is exactly the kind of behavioral detail annotations cannot convey.

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?

Front-loaded with the core question (what counts as a row) and then constraints, filtering, and pagination in that order. The middle enumeration of returned fields is long but earns its place since there is no output schema; only mild density cost.

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 available, the description takes on the responsibility of describing row shape (start, end, minutes, severity, status, category, planned, cause, estimated end) plus envelope fields total and next_cursor. Combined with the complete parameter schema, an agent has everything needed to call and page 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% — every parameter already documents format, defaults, enums, and cross-references to list_lines and causes. The description's 'filter by line, category, cause and planned' restates the schema rather than adding syntax or constraints beyond it, so the baseline 3 applies.

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?

States the specific resource and scope: recorded disruptions overlapping a time range, with the exact grain of a result row (one spell of one severity on one line). An agent can tell this apart from current-status siblings because the description makes clear it is historical/recorded overlap search, not a live snapshot.

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?

Gives clear operating context: default window (30 days to now), hard cap of 366 days, oldest-first ordering, and filter dimensions. It does not explicitly say when to prefer this over current_status or line_status, so it stops short of full sibling routing.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: exactly which metric families and time windows are computed and that reasons/causes are TfL-sourced. It stops short of mentioning cost, latency, or data freshness.

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?

It is a single dense sentence, but the scope ('One line in depth') is front-loaded and every clause enumerates a distinct return category rather than padding. Slightly run-on, but no sentence is wasted.

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 one parameter, the description carries the burden of explaining what comes back, and it does so across all the metric groups and time windows. It does not describe response shape or ordering, which is a minor residual gap for an agent parsing the result.

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?

There is a single required parameter with 100% schema description coverage; the schema already states it is a line id from list_lines with concrete examples. The description adds nothing about the line argument, so the baseline 3 applies.

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 ('One line in depth') and enumerates the exact resource scope: open disruptions, 24h/7/30/90-day disruption metrics, latest disruptions with TfL reasons and causes, and hour-of-day onset patterns. It is clearly differentiated from list_lines by being per-line and 'in depth,' though it never names the sibling tools it supersedes.

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 'in depth' framing implies this is the detailed per-line drill-down versus the aggregate siblings (current_status, period_stats), but no explicit when-to-use or when-not guidance is given. An agent must infer that it should reach for this tool after list_lines resolves a line id, which is only hinted at via the schema's reference to list_lines.

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, closed-world, non-destructive, so the safety profile is fully covered. The description adds the useful detail that results are exhaustive ('every line') and what fields come back, but says nothing about ordering, pagination, or freshness. Useful context beyond annotations, but thin.

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 waste: the first enumerates the payload, the second explains the downstream use of the ids. Front-loaded with the core identification.

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?

There is no output schema, so the description must carry the return-value burden — and it does, naming the exact fields and the mode values. For a zero-parameter, annotation-covered read tool, nothing an agent needs is missing.

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?

Zero parameters, so the baseline of 4 applies; there is nothing the description could add on this dimension. The description correctly doesn't waste words on inputs.

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?

States a specific verb (list) and resource (every line Tifa records) and enumerates the returned fields: id, name, mode, and shared-track lines. The mode enumeration (tube, elizabeth-line, overground, dlr) makes it distinguishable from the status-oriented siblings at a glance.

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 the ids returned are what line_status, disruptions and period_stats take, which strongly implies this tool is the discovery/prerequisite step before those. It stops short of an explicit 'call this first / use when you need line ids' directive, so it lands at 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 read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful context beyond that: times are epoch seconds here unlike other tools, change comparison requires both periods at least 80% watched, and results include per-day/per-week bins and a per-line table.

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?

Front-loaded with the core purpose and metrics, then the time-unit caveat. It is dense and somewhat run-on, but every clause conveys useful information for a complex aggregate tool.

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 by enumerating the figures, bins, and per-line table. It also clarifies the unusual epoch-seconds convention and the 80% watched caveat, making it sufficiently complete for an agent to use 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 100%, so the three parameters are already well documented. The description adds a useful note that the returned `period` object exposes `prev` and `next` ends to pass when walking adjacent periods, but it does not materially deepen the input parameter semantics 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?

Clearly states this returns period figures for the network or a single line, and enumerates the metrics in the result. It distinguishes itself from siblings mainly through bundling coverage/causes/disruptions into one aggregate and by the 'Unlike the other tools' time-format note, though it does not explicitly name which sibling to use 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?

Usage is implied: omit `line` for network-wide figures, supply `line` for one line, and use `end`/`span` to choose the period. However, there is no explicit guidance on when to prefer this over `coverage`, `causes`, `disruptions`, or `line_status`.

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