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

No annotations, so the description carries the full load and does: unregistered `level` returns an empty list rather than an error, mixed arguments raise, mode 3 never computes a fresh correlation and is registry-backed only, `causal_strength` is always 'not_established', `comparable` is deprecated with a precise mapping, and `caveats` must be carried forward. These are exactly the behavioral traits annotations would otherwise supply.

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?

Long but front-loaded with the when-to-use routing before the mode enumeration, and organized as a numbered list an agent can scan. Some passages, notably the deprecated `comparable` mapping, are verbose, though they still carry migration-relevant 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?

Output schema exists, so return values needn't be documented, yet the description still explains the verdict/uncertainty semantics an agent must interpret correctly. For a six-parameter, four-mode tool with no annotations, nothing needed 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 0%, so the description must compensate and it does: each of the six args is tied to a mode (stat_key, pair_key, stat_key_a/stat_key_b, level only with stat_key, country implied as 'SAME country' with an example). The only gap is that `country`'s accepted format/default is only shown by example, not defined.

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 ('how areas rank or compare on a stat', 'whether two stats can be compared fairly') and explicitly distinguishes itself from the sibling `query_data` for single-area figures. The four modes are enumerated so an agent knows the full scope of the tool 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?

Explicit when-to-use ('question is how areas rank or compare') and when-not ('For one area's own figures use query_data'). It also gives the exact arg-combination rule that selects each mode, warns that mixing arguments raises rather than silently guessing, and notes `level` without `stat_key` raises instead of falling through to mode 4.

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?

No annotations are present, so the description carries the behavioral burden. It discloses the output nature (definition/methodology/caveats), the important constraint that it never returns a current figure, supported country values, and the stat_key dependency; it does not spell out read-only/no-side-effect or error behavior, but the core behavior is clear.

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 structure is front-loaded: usage rule, output scope, exclusions, then parameter provenance. However, the 'when to use' rule is repeated in the opening and again in the fourth sentence, so some trimming is possible.

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 simple two-parameter explanation tool with an output schema, the description supplies the critical routing, scope, and stat_key provenance. No major invocation detail 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 0%, so the description must compensate. It explains that stat_key comes from query_data(country=...) for the same country and lists the supported country values, covering both parameters, though it does not mention the default country or stat_key format.

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 that the tool returns definition, methodology, and standing caveats for one metric, and explicitly says it never returns a current figure. It distinguishes itself from query_data and compare by routing numeric questions to those siblings.

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 explicitly says to use this when the question is about what a metric means or how it is measured, not for a figure, and names query_data/compare as the alternatives. It also states where stat_key comes from, giving the agent a clear invocation path.

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?

With zero annotations the description carries the full burden and does so richly: it discloses that licence differs by stage, that withheld stages produce absences not zeros, that a licence holder is named, that the caller must print scene_hash and the licence line in first/middle/last frames, and that earlier vintages return unknown_vintage. Named error states (licence_refused, unknown_vintage) and anti-loop guidance are exactly the beyond-schema context an agent needs.

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 opening is well front-loaded, but the body is a dense run-on paragraph that mixes parameter semantics, licence rules, and multi-frame rendering instructions. Every element is relevant, yet the lack of structure makes it hard to scan for the arguments an agent must actually pass.

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 4-param tool with an output schema, the description is thorough: it explains absences vs zeros, licence staging, error outcomes, and citation requirements. It even describes return contents (rows, table twin, alt text, receipt, canonical URL) that the output schema likely already covers, and only the 'country' parameter is left unexplained.

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 compensate and it largely does: scene_id (only 'ireland-builds' exists, example given), purpose ('analytical' default or 'promotional' with refusal behavior), and vintage (ISO date, omitted = current, earlier = unknown_vintage). The 'country' parameter (default 'ireland') is never mentioned, which is the one gap preventing a 5.

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: 'The data to DRAW one scene, nothing rendered', and clarifies scope with 'use it when asked for a chart, still or short clip of a figure you can cite.' It implicitly separates itself from data-query siblings (query_data, compare) by being a rendering-input tool, but never names an alternative explicitly.

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 trigger conditions ('when asked for a chart, still or short clip of a figure you can cite') and states that nothing is rendered by the tool itself. It also covers purpose-based refusal (promotional + advertising-forbidden licence → licence_refused). No explicit sibling routing or when-not-to-use exclusion, keeping it below 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?

No annotations exist, so the description carries the full burden and does well: it discloses output fields (`id`, `name`, `level`), that results are slim by default, what `include_parents=True` adds, and the pairing constraint that an `id` must always be used with the SAME `country` in `query_data`. It stops short of mentioning ordering, pagination, or whether the list is exhaustive per level, but the behavioral picture is largely complete for a read-only lookup.

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 use case, then defaults, then caveats, then return shape — a sensible order with no filler sentences. It runs slightly long and repeats the `id`-is-for-`query_data` point twice, which is the only wasted effort.

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-optional-parameter lookup with no annotations, the description covers defaults, country/level coupling, the extended-output option, and the cross-tool key contract. An output schema exists, so the brief return-value sketch is sufficient and nothing needed 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 description coverage is 0%, so the description must compensate and it does: it gives `level`'s default ('county', 26 Irish counties), the country-specific twist that the UK's primary level is 'lad' rather than 'county', the allowed `country` values ('ireland' or 'united-kingdom'), and the exact effect of `include_parents`. That is meaning the schema cannot supply.

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 ('list every geography at one boundary level, for one country') and immediately names its consumer, `query_data`. An agent can distinguish it from `query_data` 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?

Opens with an explicit when-to-use ('Use when you need the ids and names of the areas ... to pass to `query_data`') and clarifies the division of labour by pointing to `compatible_levels` on `query_data` for per-dataset level availability. The when-not is implicit but strong: this tool lists geographies, `query_data` fetches statistics.

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?

With no annotations, the description carries the full behavioral burden and does so well: it explains mode dispatch, error behavior for mismatched country/area, 404s for unknown geography, raises for invalid argument combinations, response sizes, caveat handling, `resolved_from_stat_key`, and `stopped_reporting` status. It also clarifies that `history_months` means actual months rather than periods of the series.

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 long, but the length is largely justified by four distinct modes and several argument interactions. It is front-loaded with a usage statement and structured into numbered modes, though some passages could be tightened without losing meaning.

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 six parameters with zero schema coverage, no annotations, and an output schema, the description provides all the missing invocation context an agent needs. It covers mode selection, parameter dependencies, error cases, output characteristics, and special status handling.

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 0%, so the description must compensate, and it does: every parameter is explained in context, including `area_id`, `country`, `dataset`, `stat_key`, `history_months`, and `council`. It adds semantics the schema lacks, such as country matching, `series_key` sourcing, `stat_key` acceptance, and `history_months=0` meaning all history.

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 multi-mode purpose: finding datasets, area-specific datasets, figures/history for an area and dataset, and Irish council planning data. It explicitly consolidates three former tools and distinguishes the sibling tools `explain_metric` and `compare` by their roles.

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 states when to use the tool and names alternatives for adjacent questions: `explain_metric` for metric meaning and `compare` for rankings. The four modes are keyed to which arguments are supplied, with preconditions such as `area_id` coming from `list_areas` and `dataset` coming from mode 2.

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