HaulierScope

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds domain context (the 'at least five licences' threshold, that towns come with links), but says nothing about pagination, size of result, or whether the 'largest operators' list is truncated.

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 dense sentence, front-loaded with the resource and then the content inventory. Every clause carries information; the only minor cost is the length of the enumeration, which is justified by the breadth of returned sections.

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 an output schema present, return values need no explanation, and a one-parameter read-only stats tool is well described by a content inventory. The missing piece is any indication of scope relative to sibling aggregate tools.

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 `area` param already documents the accepted slug/letter/name forms with examples, so the description is not obliged to repeat it. Baseline 3 applies; the description adds no extra parameter meaning 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 names a specific resource (statistics for one of the eight GB traffic areas) and enumerates the exact content blocks returned: licences, operators, vehicles/trailers authorised, licence-type mix, largest operators, and towns with 5+ licences. An agent can see this is a per-area aggregate view, though it does not explicitly contrast itself with the overlapping sibling biggest_operators.

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 — call it when you need aggregate figures for a single named traffic area — but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as biggest_operators or search_operators. Adequate but leaves routing 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 and closed-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: the data source (latest DVSA file) and the 'Companies only' restriction, which signals that other entity types are excluded. It stops short of noting freshness or pagination limits, but the annotation bar is already met.

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, front-loaded with the core purpose and then the returned columns. Every clause earns its place; 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 an output schema present, the description need not explain return values, yet it usefully enumerates the row fields. It covers both parameters' semantics and the ranking scope. The main minor gap is the absence of guidance on which mode to pick versus sibling tools, but nothing required to call it correctly 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 coverage is only 50% – the 'kind' enum carries no schema description. The description compensates by explaining what each enum value means ('haulage-companies' = Standard goods licences top 100 nationally; 'coach-and-bus-operators' = PSV licences) and by clarifying that supplying an area yields the top 50 in that traffic area. This adds meaning beyond the raw schema, though the slug/letter/name format is left to 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?

States a specific verb and resource: ranking of companies by vehicles authorised, drawn from the latest DVSA file. It precisely delineates the two output modes ('haulage-companies' top 100 nationally vs 'coach-and-bus-operators' PSV, or top 50 in one traffic area), which distinguishes it from sibling tools like search_operators and area_stats.

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 explains the two selection modes and the ranking scope, which implicitly guides which 'kind' to choose, but it never states when to prefer this tool over search_operators or area_stats. Usage is implied through the scope description rather than explicitly contrasted with alternatives.

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 closed-world, so the safety profile is covered. The description adds behavioural context beyond that: it discloses the coverage of the dataset (five named sources), that a 'last checked for a newer DVSA file' timestamp is tracked, and that every DVSA file held is listed — non-obvious operational detail.

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?

A single sentence with the core claim (date and age of sources) front-loaded and the source list in parentheses. It is dense but every clause earns its place; the parenthetical enumeration is long but functional rather than filler.

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?

An output schema exists, so return-value structure need not be explained, and the description already characterises the content of that output well. With no parameters and annotations covering risk, the only missing piece is explicit when-to-use guidance relative to siblings.

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 input parameters, so the baseline is 4. The description goes slightly further by describing the semantics of a returned/related value (`release`) as consumed by recent_changes, though it adds no parameter syntax because none exist.

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 the exact resource it reports on (date and age of every source behind HaulierScope) and enumerates the concrete sources, so an agent knows precisely what this tool returns. It does not explicitly contrast itself with siblings, but the resource is specific enough to be distinguishable from get_licence, recent_changes and the other lookup tools.

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 supplies a concrete usage hint by stating the DVSA file list is 'usable as `release` in recent_changes', which tells the agent exactly how to chain this tool into a sibling. It stops short of stating when this tool should be preferred over alternatives (e.g. as a freshness pre-check) or any 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, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds that the payload carries the DVSA file date, sources and canonical URL, which is useful context, but says nothing about auth needs, rate limits, or failure behavior for a malformed id.

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, front-loaded with the return type and content, followed by the accepted input formats. Slightly dense phrasing in the list of id examples, but nothing 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?

An output schema exists, so return-value explanation is not required, yet the description still orients the agent on what the text contains. Combined with the concrete id formats, an agent has enough to invoke it correctly; only the id-prefix enumeration and post-search workflow are left to inference.

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 0% for the single `id` parameter, so the description must compensate, and it does: it names three concrete id shapes ('licence:OB1234567', 'company:02155951', 'guide:vet-a-haulier') plus a page URL. That is real added meaning beyond the string/minLength/maxLength constraints, though it does not enumerate all possible prefixes.

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+resource: it returns the full Markdown text of a single result or HaulierScope page. The 'from search' prefix implicitly separates it from the sibling `search` tool, though it never names an alternative outright. An agent can tell what comes back without reading 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?

The phrase 'a result from search' implies the intended workflow (search first, then fetch an id), but no explicit when-to-use or when-not-to-use guidance is given and no sibling is named. The agent must infer that this is the dereference step after `search` rather than a lookup like `get_licence`.

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/openWorld=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the data is a point-in-time snapshot tied to the register date, results are ranked largest-fleet-first, totals are grouped by traffic area, and the output is not an insolvency signal. It stops short of describing pagination or refresh cadence.

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 short sentences, front-loaded with the resource and scope, followed by the optional filter and the interpretive caveat. No filler; the 'Companies only' fragment carries real filtering 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 an output schema present, return-value explanation is unnecessary, and the description still covers scope, ordering, aggregation and the key interpretive caveat. The remaining gap is the undocumented 'limit' parameter and any statement of data freshness or result-size 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 50%: 'area' is documented in the schema (slug/letter/name), and the description adds that it is optional and restricted to a single area. 'limit' has no description in either place, though 'largest fleets first' implicitly tells the agent the ordering that limit truncates. The description compensates only partially for the coverage gap.

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 resource and scope: companies holding operator licences with accounts overdue at the Companies House register date, sorted largest fleets first, with totals by traffic area. It also explicitly separates itself from the insolvency_watch sibling ('A filing fact, not a sign of insolvency'), so an agent can distinguish the two without opening either 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 clear context for when the tool applies (filing-overdue research, optionally narrowed to one traffic area) and implicitly excludes the insolvency use case. It does not, however, name an explicit alternative to reach for or spell out a when-not-to-use condition beyond the caveat sentence.

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=false, and destructiveHint=false, covering the core safety profile. The description adds the scope of returned data (totals, statuses, inquiries, etc.) but does not disclose behavioral traits like permissions, failure modes, rate limits, or whether historical licences are included.

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 purpose is front-loaded, but the description is a single long sentence with a dense colon-separated list of return fields. Because an output schema exists, enumerating those fields here is largely redundant and reduces 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?

For a one-parameter, read-only tool with rich annotations and an output schema, the description gives enough to invoke it correctly: it states the required input, identifies the company scope, and summarizes the returned data. The main gap is the lack of explicit guidance on when to use it versus sibling tools.

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 already includes the same examples of Companies House numbers. The description repeats the example and says 'by Companies House number' but adds no format constraints, validation details, or semantics beyond what the schema provides.

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 resource ('All operator licences held by one company or organisation') and keying mechanism ('by Companies House number'). It clearly distinguishes itself from get_licence by returning all licences for a company, but does not explicitly name or contrast with any sibling tool, leaving some differentiation to inference.

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?

No when-to-use or when-not-to-use guidance. The description never mentions alternatives such as search_operators or get_licence, nor does it state the context in which this tool should be chosen.

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 non-destructive behaviour, so the description is not burdened with the safety profile. It adds genuine context beyond them: holder names are never sole-trader or partner names (a data/privacy caveat), and stale licences are surfaced with in_current_file: false rather than omitted.

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 in the first clause, then a dense but purposeful enumeration of contents. It is one long run-on sentence without formatting, but essentially every clause carries 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?

Given one fully documented parameter, a rich output schema and full annotation coverage, the description is nearly complete; the only missing piece is error behaviour when a licence number does not exist (vs. the disclosed in_current_file: false case). Enumerating return fields is partly redundant with the output schema but still useful as a summary.

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 already documents the OB/P prefix and traffic-area encoding in the schema. The description only restates 'by its number' and adds no format, validation or edge-case detail beyond it, so the baseline of 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 resource (one GB operator licence) and the lookup key ('by its number'), which distinguishes it from the list/search siblings like search_operators, licences_ended and biggest_operators. The enumerated field list further pins down exactly what kind of record this is.

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 phrase 'by its number' signals a single-record lookup, so an agent can infer it should not be used for browsing. However, no sibling is named as an alternative and there is no when-to-use/when-not statement.

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). The description adds real context beyond them: facts are dated to the register, whether an operator licence continues is a Traffic Commissioner matter, and the results are companies only. It doesn't discuss pagination or how freshness interacts with the limit default.

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 result set before secondary details, and the alternative-tool routing is placed mid-description where it is useful. Dense but nearly every sentence carries information; the disclaimer sentence is slightly less actionable but justified for a legal-status 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 an output schema present, return format needn't be restated. The description covers domain, geography, ordering, exclusions and a data-freshness caveat, leaving only the undocumented 'limit' parameter as a gap. Sufficient for correct invocation.

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 50%: 'area' is well documented in the schema, but 'limit' has no description anywhere. The phrase 'Optionally for one traffic area' reinforces the area parameter, but nothing clarifies the limit or the interaction between 'largest fleets first' and the default of 50, so the description only partially compensates for the coverage gap.

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 resource and scope: operator-licence holders shown by Companies House in liquidation, administration or receivership, ordered largest fleets first, with totals by traffic area and Gazette notices. It explicitly distinguishes the 'Companies only' domain and names the sibling it is not (filing_watch).

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 an explicit exclusion with a named alternative: 'Accounts overdue is not insolvency: use filing_watch.' It also states the optional per-traffic-area scoping condition, so an agent knows both when to use it and when to route elsewhere.

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 safe read-only, idempotent, closed-world profile, yet the description adds real behavioral context beyond them: monthly publication cadence, the field set returned, and the attribution rule that companies are named while sole traders and partnerships are counted only. That last point materially affects how results must be interpreted.

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 resource and the optional filter are front-loaded in the first sentence, the attribution caveat follows, and the wording directive is a single tight imperative. No sentence is padding.

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 annotations covering the safety profile and an output schema present, return-value explanation is largely optional; the description nonetheless enumerates the returned fields. The only real gap is the absence of any pointer to sibling tools for adjacent queries, which keeps it just short of complete routing coverage.

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 67%: area and month are documented in the schema, while limit carries only default/min/max. The description's 'Optionally for one traffic area' merely restates the area parameter and adds no syntax or semantics beyond the schema, so this sits at the baseline for partially covered parameters.

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+resource: operator licences published by the Traffic Commissioners as revoked, surrendered or terminated in one month. It is clearly distinguishable from the sibling new_licences by the licence-status focus, though it never names that sibling explicitly, so the differentiation is implicit rather than stated.

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 notes the scope ('Optionally for one traffic area') and gives a presentation directive ('Quote the official heading; do not restate a surrender or termination as a revocation'), but never says when to choose this tool over recent_changes, new_licences or tc_decisions. Usage is implied by the resource, not spelled out.

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 safe read-only, idempotent, closed-world profile, so the bar is lower. The description adds genuine behavioral context: the provenance (weekly Applications and Decisions / Notices and Proceedings bulletins) and an important coverage caveat that sole traders and partnerships are counted but not named.

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?

Effectively one dense sentence that front-loads the core resource and scope before the enumerations. The field list and coverage caveat are slightly packed in, but every clause 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?

With an output schema present, return values need no explanation, and the description supplies scope, source and coverage caveats. Only the unexplained 'limit' parameter leaves a small gap for a list-returning 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 67% and the description's only parameter-relevant addition is 'optionally for one traffic area', which maps to 'area' and largely restates what the schema already documents with slugs, letters and names. The 'limit' parameter is never addressed, so the description does not compensate for the coverage gap.

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+resource ('New goods vehicle and PSV operator licences granted') and scopes it to one publication month, with named source documents. An agent can distinguish it from licences_ended, tc_decisions and search_operators on the name alone.

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 implies usage context – data exists per publication month, and an optional traffic-area narrowing – but never states when to prefer this over siblings such as licences_ended or tc_decisions, nor any exclusions. Constraints are clear; routing guidance is absent.

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 as read-only, idempotent, non-destructive, and closed-world. The description adds valuable non-annotation context: companies are listed with before/after values while sole traders and partnerships are only counted, and the default release behavior is clarified. No permissions or rate limits are mentioned, but the added output asymmetry is meaningful.

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 purpose and then adds behavioral and parameter details. It is dense but every sentence contributes useful information; minor improvements could come from breaking the long first sentence into a clearer list, but it remains efficient.

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 annotations covering the safety profile and the presence of an output schema, the description need not explain return values. It adequately covers the tool's scope, the default release behavior, and an important output asymmetry for different entity types. Nothing critical is missing for an agent to invoke 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?

With 60% schema description coverage, the description compensates by explaining the release parameter format (YYYY-MM-DD, default latest, and that data_status lists them) and by enumerating change categories that map to the change_type enum. It does not elaborate on area, limit, or offset beyond what the schema already provides, so it is not fully comprehensive.

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 what the tool does: it reports changes between consecutive DVSA operator licence files and enumerates the types of changes included. It distinguishes the resource and verb ('what changed between... file and the one before'), though it does not explicitly contrast with sibling tools like new_licences or licences_ended.

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 by the description of output and the note that it defaults to the latest file and accepts a release parameter. However, there is no explicit guidance on when to choose this tool over alternatives such as new_licences or area_stats, nor any stated 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, non-destructive and closed-world behavior, so the safety profile is covered. The description adds the useful workflow trait that results are ids intended for a follow-up fetch call, which is not derivable from the annotations — though it does not discuss result counts, relevance ranking, or empty-result behavior.

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 load-bearing: the first gives scope and return contract, the second handles sibling routing. Front-loaded with no filler.

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 single-parameter lookup tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what is searchable, what comes back, and which sibling to use instead when structured results are required.

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 0%, so the description must carry the query semantics; it does by enumerating what the query string may contain (company name, licence number, company number). Constraints like the 100-character maximum and the single-required-parameter shape are left to 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?

States a specific verb (search), the resource (HaulierScope operators and guides), the accepted identifier types (company name, licence number, company number), and the return contract (ids to pass to fetch). It also explicitly distinguishes itself from the sibling search_operators, which is the operator-results tool.

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 routes the agent: use this tool to obtain ids for fetch, and prefer search_operators when structured operator results are wanted. Both the condition for using this tool and the alternative for the adjacent case are named.

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, not open-world), so the description's value-add is the ranking behavior and the name-matching limitation, both of which materially affect how results should be interpreted. It stops short of discussing empty-result or pagination behavior.

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, front-loaded with what the tool does and the accepted keys, then ranking and matching caveats, then filters. No filler and no repetition of annotation-covered facts.

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 search tool with an output schema, the description supplies the matching semantics, ranking and filter surface an agent needs to invoke it correctly. Minor gaps remain around empty-result and pagination behavior, but the output schema covers the return shape.

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 67%, and the description compensates by enumerating the filter axes (traffic area, vehicle category, status, licence type, presence in the latest DVSA file) and giving a licence-number example format. It adds interpretation (e.g. names match organisations only) beyond the raw field descriptions, though it doesn't document each filter value's syntax in prose.

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 (find) and resource (GB goods vehicle and PSV operators), plus every accepted search key. It reads distinctly from lookup siblings like get_licence or get_company, which require an identifier rather than performing a search.

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?

Explains the matching model and its limits (exact licence/company numbers rank first; names match companies and organisations only, so sole traders are only found by exact licence number), which tells the agent when this search will and won't succeed. It does not, however, name a sibling alternative (e.g. get_licence for full detail on a known number).

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), so the bar is lower. The description adds genuine behavioral context beyond them: the result includes counts by outcome and traffic area, and a data-coverage caveat that only companies are named while sole traders, partnerships and individuals are counted only. This is useful disclosure about what the result set contains and omits.

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 content (what the dataset is, what fields it returns) is front-loaded in the first sentence, with filtering and caveats following. It is dense but every clause carries information; the parenthetical outcome list is slightly long but serves as scope definition. No filler sentences.

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 filtered-list tool with an output schema, this covers the essentials: what is returned, what the filters mean, where the outcome code comes from, and the key coverage caveat. Return-value details are handled by the output schema, and safety by annotations, so nothing critical is missing for correct invocation.

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 67% (area and outcome are documented; limit is not). The description adds that the outcome code must come from by_outcome and gives an example ('revocation'), and clarifies that area and outcome are optional filters that can be combined. It says nothing about limit or the default of 50, so it does not fully compensate for the coverage gap.

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 (written regulatory decisions published by the Traffic Commissioners on GOV.UK) and enumerates the fields returned (company, licences, outcome, decision date, appeal status, document). It is clearly a decision-record retrieval tool rather than a licence/operator tool, though it never names a sibling to route against. Clear but not explicitly differentiated from siblings like search or recent_changes.

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 says the area and outcome filters are optional and combinable ('one traffic area and/or one outcome code'), which implies a filtered browsing use case. However, there is no when-to-use/when-not statement and no mention of alternatives such as search or area_stats for related questions. Usage is implied rather than guided.

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), but the description adds genuinely non-obvious behavior: sole traders and partnerships are counted rather than named, and being called to an inquiry is not a finding against the operator. Those are interpretive facts the schema and 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?

Three sentences, each front-loaded and purposeful: what is listed, the scope modifier, then two caveats. Nothing is padded, though the returned-field enumeration is partly redundant given the output schema exists.

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 an output schema present, return values need not be spelled out, and the description still covers source, scope, and important interpretation caveats. It is complete enough for correct invocation; only the missing relationship to tc_decisions leaves a small gap.

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 'area' parameter is fully documented in the schema, including accepted forms. The description only restates that area is optional ('optionally for one traffic area') without adding syntax or constraint detail, 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 names a specific resource (Traffic Commissioner public inquiries) with an explicit verb sense ('listed for companies'), and enumerates the fields returned (date, time, venue, legal grounds, official notice) plus the source publications. It is clear what the tool does, but it never distinguishes itself from the adjacent sibling tc_decisions, which an agent could plausibly confuse with this.

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 when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The only usage signal is 'optionally for one traffic area', which is a scoping detail rather than routing guidance, so the agent must infer when this beats tc_decisions or search.

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