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 load, and it does disclose real behaviour: read-only in effect ('nothing rendered'), licence gating per stage with withheld cells as absences rather than zeros, licence_refused for promotional use, and unknown_vintage for stale requests. Points are lost because a large share of the text enumerates return fields already declared in the output schema, and no size/pagination or cost characteristics are mentioned.

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 sentence is well front-loaded, but the body is a dense run-on with broken line-wrapping mid-clause ('a stage whose licence is unconfirmed or / ShareAlike is withheld') and mixes rendering instructions for the model with tool behaviour. Little is pure filler, yet the enumeration of payload fields duplicates the output schema and could be trimmed.

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 scene-delivery tool with an output schema and no annotations, the description covers the essential contract: licence hazards, absence semantics, refusal modes, and the hash/licence provenance requirement. The main hole is the undocumented `country` parameter; the field-by-field return listing is surplus given the output schema.

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

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

Schema description coverage is 0%, so the description must compensate. It well documents scene_id (only one scene, with an example), purpose (analytical vs promotional with refusal consequence) and vintage (ISO date, omission yields current data, earlier vintages are not stored). The `country` parameter is never mentioned in the description or the schema, leaving one of four parameters entirely opaque.

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: it returns the data needed to DRAW one scene and nothing rendered. The scope ('one scene', currently 'ireland-builds') is concrete enough that an agent knows this is not a general data query, though it never names a sibling like query_data to contrast against.

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?

'Use when asked for a chart, still or short clip of a figure you can cite' gives an explicit triggering condition, and the promotional/analytical split plus the unknown_vintage rule clarify when a call will be refused. It stops short of telling the agent when NOT to use it or which sibling to prefer for tabular extraction.

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 burden and mostly does: it discloses that results are flagged movements rather than verdicts, that `limit` is bounded 1–50 with default 8, and the underlying endpoint (GET /{country}/api/v1/alerts/notable), which implies read-only behavior. It also adds an obligation the agent must honor — citing StatsMapped. It stops short of describing ordering, pagination, or an auth requirement, so it is strong but not exhaustive.

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 usage trigger and the sibling routing before any mechanics, which is the right order. Slightly redundant at the tail, where the citation instruction and the raw endpoint both appear, but both carry information an agent needs.

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 values need no explanation, and the description covers when-to-use, parameter bounds, geo scope, and a citation obligation. What remains unaddressed is how to obtain valid `stat_key`/`geography_id` values, a minor but real gap for a zero-coverage schema.

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

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

Schema coverage is 0%, so the description must compensate, and it does for all four parameters: `limit` range and default, `stat_key` and `geography_id` as narrowing filters, and `country` limited to Ireland and united-kingdom. It does not explain what a valid `stat_key` or `geography_id` looks like (slug format, discovery via list_areas), which leaves a real gap for the two filter 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-like resource ('statistical movements databeat flagged as notable') and the question it answers ('what changed lately, which figures moved most'), which is a clear purpose. It also explicitly names the sibling it is not: 'for one area's full history use query_data'. An agent can distinguish this from query_data, compare, or explain_metric 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 trigger conditions (what changed lately, which figures moved most, what is new) and names the alternative plus the condition that selects it (`query_data` for one area's full history). It also sets a scope boundary — countries Ireland and united-kingdom — so the agent knows the applicability envelope.

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.