UK Data: GB road traffic counts (DfT)

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered; the description adds substantial context beyond them: output units (million vehicle miles and vehicle km), ordering (newest year first), a data-quality caveat that minor-road traffic is a DfT estimate, and a cost of 1 credit. These are exactly the traits an agent needs that structured fields do not carry.

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?

Key facts (what, units, scope, ordering) are front-loaded and every clause carries information — vehicle categories, estimate caveat, sibling routing, credit cost. It is a dense single block with heavy parentheticals, which slightly taxes scanning but wastes no 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?

No output schema exists, so the description must explain the return shape, and it does: totals per year for two vehicle groupings plus road length, in stated units, ordered newest first. Combined with the sibling pointer and the DfT-estimate caveat, an agent has everything needed to call this correctly for a 3-parameter read-only 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 description coverage is 100%, so year, years and local_authority_id are already fully documented, including the id source and the Leeds=63 example. The description adds only the 'newest year first' ordering hint, which lightly clarifies the default behavior, so the schema still does the heavy lifting and 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 a concrete resource and scope: total distance driven on all roads in one GB council area per year, in million vehicle miles and vehicle km, broken out for all motor vehicles versus cars and taxis, plus road length. This is specific enough that an agent can distinguish it from region_traffic_by_vehicle_type and traffic_local_authority_find without opening any 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?

Gives explicit use contexts (council officers, net-zero and carbon plans, consultants comparing areas) and names the alternative tool with the exact condition that selects it: vehicle-type splits for vans/HGVs/buses must go to region_traffic_by_vehicle_type. The agent is routed rather than left to infer.

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 open-world, so safety is covered. The description adds behavior beyond them: a stated cost of 1 credit, the result ordering ("newest year first"), the measurement unit, and the full set of returned series – valuable because there is no output schema. It stops short of covering empty-result or invalid-region behavior, so not a 5.

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 core scope, units and categories are front-loaded in the first sentence, and the sibling routing comes before the trailing cost note. The use-case list (market sizing, journalism, coursework) is slightly expendable, but the rest of the text is dense and non-redundant.

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 three-parameter read-only aggregate with no output schema, the description closes every material gap: what is returned, in what unit, in what order, at what cost, and which sibling to use instead. An agent can select and call this correctly without opening anything else.

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 year, years and region_id are already documented with ranges, defaults and the pointer to traffic_regions_list. The description only adds the geography covered by region_id and the default recency via "newest year first"; it does not explain the year/years interaction beyond what the schema states. 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?

States a specific verb and resource ("Gives annual traffic in one GB region by vehicle type"), pins down the geography (English regions, Scotland, Wales), the unit (million vehicle miles), and enumerates the vehicle categories returned plus road length. It is immediately distinguishable from the sibling tools local_authority_traffic_totals and road_traffic_flow_at_point.

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 scopes the tool ("Regional totals only") and names the alternatives with the exact condition that selects each: local_authority_traffic_totals for a single council, road_traffic_flow_at_point for one road. It also names concrete use cases (market sizing for fleet services, journalism, coursework), so an agent knows when this is the right call.

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/openWorld, and the description still adds material behavior: results are ordered newest year first, some years are DfT estimates with each row flagging that, both directions are aggregated, the vehicle-class breakdown is enumerated, and it costs 1 credit. These are exactly the caveats an agent needs to interpret output and set expectations, none of which appear in 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 core definition and unit of measurement are front-loaded in the first clause, followed by example questions and caveats in a single dense paragraph. Every clause carries information, though the parenthetical cost note and the long vehicle-class enumeration make it slightly heavier than necessary.

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 steps in to describe the returned shape (per-vehicle-class daily flows, one row per year, newest first) and the estimation caveat, which is the critical completeness gap it must fill. Only the count-point source hint and pagination/limit behavior are left to the schema, so it is close to complete for this tool's complexity.

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 all three parameters (year, years, count_point_id) are already documented with types and defaults, establishing the baseline of 3. The description reinforces semantics ('newest year first', default most recent years) but adds no new syntax, ranges, or id-format guidance beyond what the schema states.

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 verb and resource ('Gives average annual daily flow (AADF) at one DfT count point') and immediately defines the metric (average vehicles per day over a year, both directions, split by vehicle class). The scope qualifier 'at one DfT count point' implicitly distinguishes it from region/local-authority aggregates and hourly-count siblings, so an agent can select it without opening other schemas.

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 concrete usage framing ('Answers "how many cars pass this site a day" and "is traffic on this road rising"') and names real use cases (shop, billboard, EV charger, planning work), plus an exclusion: 'it does not cover live traffic or congestion'. That exclusion steers agents away from hourly/live siblings without naming them explicitly, which is the only gap.

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 the description adds substantial context beyond them: credit cost, the weekday 07:00-19:00 coverage window, that counts are raw survey-day data rather than averages, and that many count points are only surveyed every few years (a real data-vintage caveat). The response shape (per-direction hours, busiest hour, 12-hour total) is also disclosed.

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?

Four tight sentences, front-loaded with what is returned, followed by use case, coverage caveats, and cost. No filler; each sentence contributes either scope, routing, or a limitation the agent would otherwise miss.

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 three simple parameters, the description carries its weight by explaining the return structure, temporal coverage, survey-frequency limitation, and cost. An agent has everything needed to decide to call it and to interpret 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?

Schema coverage is 100%, so all three parameters (year, direction, count_point_id) are already documented with defaults and enum-like values. The description reinforces that data is tied to a single survey year and one count point, but adds no syntax or format detail beyond the schema — 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 a specific verb and resource (returns hour-by-hour manual traffic counts from DfT) at one count point, broken down by direction and including busiest hour and 12-hour totals. The scope language ('manual counts', 'one count point', 'survey day') distinguishes it from the aggregate siblings like region_traffic_by_vehicle_type and local_authority_traffic_totals without needing extra lookups.

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 concrete use case ('peak-hour questions such as how busy is this road at 8am') and target audience, plus clear exclusions: not averages, not night-time, single weekday 07:00-19:00 only. It does not explicitly name which sibling to use for averages or region-wide totals, so routing to alternatives is left partly 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 cover safety (readOnly, idempotent, non-destructive, open world), and the description adds genuinely new behavior: partial-name matching with concrete examples, dual accepted input formats, coverage that includes retired councils, and a 1-credit cost. The one unaddressed trait is ambiguity handling — 'Kingston' plausibly resolves to several councils, and the description does not say whether the result is one match, a list, or an error.

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 return value, then accepted inputs, then call ordering, then scope limits — the four things an agent needs, in priority order. Every clause earns its place, including the short parenthetical credit cost, and there is no filler or repetition of the title.

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 correctly states what comes back (id, ONS code, region), so the agent knows what it will receive. Given the tool is a simple single-param lookup with full annotation coverage, the only meaningful omission is what a multi-match or zero-match partial name returns.

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 parameter is already documented as 'council name or part of it, or an ONS code like E08000035'. The description reinforces this with additional worked examples ('Leeds', 'Bristol', 'Kingston') and confirms partial matching works, but adds no format rules or disambiguation beyond the schema. Baseline 3 is appropriate when the schema carries the parameter 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?

States a specific verb (finds) and precise resources (DfT local authority id, ONS code, region) scoped to councils. It also distinguishes itself from a near-miss sibling by saying explicitly 'it is not a postcode lookup', so an agent can rule out postcode_lookup without opening a 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?

Gives explicit ordering guidance: 'Use it before local_authority_traffic_totals or traffic_count_points_in_council', naming both downstream alternatives and the sequencing condition. It also states a when-not ('not a postcode lookup') and the geographic scope (Great Britain, as DfT lists them), including former councils for older years.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the exact result set size (11 regions), the fields returned, the geographic exclusion, and the 1-credit cost — a real operational constraint for budgeting calls.

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: what it returns, what to use it for, and what it excludes, with the cost note at the end. Front-loaded with the resource and scope, no filler or repetition of the name.

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 zero-parameter lookup with no output schema, the description covers the result cardinality, the fields returned, the intended downstream use and the geographic gap. It lacks only a note on output ordering or format, which is minor given no output schema exists.

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 are zero parameters, so the baseline is 4. The description usefully explains that the output carries region_id, ONS codes and country, which is meaning about the payload beyond the empty schema and is exactly what an agent needs to chain into the traffic tool.

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 and resource (lists the 11 GB regions DfT uses for traffic statistics) and enumerates coverage exactly — nine English regions, Scotland, Wales — plus the fields returned (DfT region ids, ONS codes, country). It is unmistakably distinct from region_traffic_by_vehicle_type.

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 names when to use it: to obtain the region_id needed for region_traffic_by_vehicle_type. It also states a boundary condition (Northern Ireland is not covered by DfT road traffic statistics), so an agent knows when this tool does not apply.

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