Open Index

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds the same-level constraint and that each side may carry a different period and source, plus the default that only key figures are returned, but says nothing about response shape or limits.

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 compact sentences with the constraining conditions (same level, same figures) front-loaded and zero filler. Every clause contributes information an agent can act on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry more of the return-value burden, and it only gestures at it via 'key figures by default'. For a comparison tool this is adequate but leaves the agent guessing about output structure and whether extra layers can be requested per side.

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 a 3 is the baseline. The description adds real meaning beyond the schema by disclosing the default behavior of the optional layers parameter ('key figures by default') and clarifying that the period/source can differ per side, which the schema does not convey.

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 a specific operation and resource: two UK areas placed side by side on the same published figures, restricted to the same area level. It implicitly contrasts with single-place siblings (get_place, fetch), though it never names them or explicitly says it is not for one-place 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?

A usage condition is embedded in the first clause ('same level', 'same published figures', 'each with its own period and source'), so an agent can infer the tool is for area-vs-area comparison. However, it never states when to prefer this over get_place or search_places, and no exclusions are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so the safety profile is covered. The description goes beyond that by disclosing the content shape (periods, sources, licences, gaps, citation links) and the 'published level of detail' constraint, which helps an agent judge suitability before calling.

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 tight sentences, no filler, with the core action and lookup key front-loaded. Every clause adds 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?

For a single-parameter read tool with an output schema, the description supplies the input meaning, the content scope, and the fidelity level. The only missing piece is routing guidance relative to get_place, which leaves a small ambiguity.

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

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

The single parameter 'id' has 0% schema description coverage, so the description must carry the meaning. 'By its canonical page path' does real work here, telling the agent the value is a page path rather than a place name, postcode, or numeric id.

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 ('Read one UK area's overview figures') and adds the lookup key ('by its canonical page path'). It does not explicitly distinguish itself from the closest sibling get_place, so an agent cannot tell the two apart from the description 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 phrase 'by its canonical page path' implies the required input, but there is no statement of when to use this tool versus get_place, search_places, or the other siblings, and no exclusions or conditions. Usage is left entirely 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 behavioral detail: the default returns key figures while supplying a topic returns everything including gaps and their reasons, and it enumerates the fields each figure carries (period, publication date, rank, comparisons, source, link).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, and the core scope (published figures for one UK area) is front-loaded before the mode split and the field inventory. The second sentence earns its length by compensating for the absent output schema.

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 safety, a fully documented schema and no output schema, the description sensibly supplies the return shape and the default/topic mode behavior. The remaining gap is the absence of routing guidance against the six siblings, which an agent comparing similar tools would benefit from.

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 both parameters are fully documented in the schema, which sets the baseline at 3. The description adds the default behavior when topic is omitted, which the schema does not state, but its topic wording ('gaps and their reasons') largely duplicates the schema text, so the net gain over structured data is modest.

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: retrieving published figures for one UK area, with the default (key figures) and the expanded mode (every figure in one topic) both named. It distinguishes scope from siblings like compare_places and get_ranking by emphasizing a single area, though it 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?

Usage is implied through the default-vs-topic distinction ('key figures by default, or every figure in one topic'), which tells the agent how to widen scope. However, there is no guidance on when to prefer this over compare_places, get_ranking, or search_places, so the alternative-selection burden is left to inference.

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

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

Annotations already establish readOnly/idempotent/non-destructive behavior, and the description adds real context beyond them: results are limited to the latest period only, and measures like deprivation cannot be ranked cross-nation. It does not cover output format or pagination, but the added scope constraints are genuinely useful.

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 tight sentences with the core scope statement front-loaded, followed by the one edge-case caveat that matters. No filler or redundancy.

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 safe read-only annotations and no output schema, the description covers period, geographic scope, and the cross-nation caveat, which is enough for correct invocation. It omits any note on the limit/order defaults, which is a minor gap for a ranked-list 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 60%, so the schema carries much of the load. The description loosely maps to the 'layer' parameter ('one measure') and the 'scope' categories (UK/nation/English region), but says nothing about limit, order, or place, 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 gives a specific verb+resource ('Councils ranked') and pins the scope (UK/nation/English region) and timeframe (latest period), which an agent can distinguish from siblings like compare_places or get_place. It stops short of naming those alternatives explicitly, so it's clear but lacks direct sibling differentiation.

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 implies when the tool applies (ranking one measure, latest period) and adds a meaningful caveat that measures handled differently per nation are ranked within one nation only. However, it never routes the agent between this and compare_places/get_place when multiple councils are involved, leaving usage inference to the caller.

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, non-open-world, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond them: partial inputs (district/sector) return only councils, and NI coverage is absent. Return format/pagination is not mentioned, but the tool is a simple 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?

Two sentences with no filler, front-loaded with what the tool returns and followed by input-form and coverage caveats. 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?

With no output schema, the description compensates by describing the returned areas and their codes/pages, plus the geographic coverage limit. It is complete for a one-parameter lookup, though it never says what an invalid or unknown postcode yields.

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 parameter's description already enumerates full postcode, sector and district formats. The description's restatement of E8 / E8 1 formats largely duplicates the schema, adding little beyond the output-oriented framing.

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 a specific resource (the areas a GB postcode sits in, with codes and pages) and enumerates the area types returned, so an agent can tell what it produces. It does not name or contrast with any sibling (get_place, search_places, fetch), so the differentiation is left 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?

Usage is implied by the input-form guidance (district, sector, full postcode) and one explicit exclusion ('Northern Ireland postcodes are not available'), which functions as a when-not. There is no guidance on when to choose this over get_place or search_places for geographic lookups.

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, and the description still adds a genuine constraint not present in structured data: Northern Ireland postcodes are excluded. It also notes that GB postcodes are treated as identifying their area, which is non-obvious behavior for a text search.

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 short sentences, front-loaded with what the tool returns, then the query semantics, then the exclusion. No filler and nothing repeated from annotations or schema.

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 listing page paths, titles and citation URLs is slightly redundant, but the NI postcode exclusion and postcode-as-query behavior make the definition usable as-is. The one gap is the absence of any routing signal against the similarly named sibling search_places.

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 'query' string, so the description must carry the load — and it does, clarifying that the query is a place name and that postcodes are also accepted (GB only). That is materially more than the bare 'string, maxLength 100' 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 verb ('Find') and resource ('UK area overview documents') plus the query dimension ('by place name'), which is enough for an agent to know this returns documents rather than places. It does not name or explicitly contrast with the sibling search_places, so an agent must infer the split from the phrase 'documents' vs 'places'.

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 one real usage constraint — GB postcodes resolve to their published area, Northern Ireland postcodes are unsupported — which tells the agent when a query will fail. Beyond that, 'for research' is vague and no alternative (search_places, get_place, lookup_postcode) is named or excluded.

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 (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real value by disclosing what comes back (official code, level, page URL) and that matching data layers are also returned — important because there is no output schema. It stops short of 5 by saying nothing about result ordering or limits.

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 dense sentence with the action front-loaded and no filler; the entity enumeration earns its place by defining scope. Slightly packed, 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?

With no output schema, the description usefully covers return contents (code, level, URL, data layers), which is the main completeness gap it needed to fill. Minor omissions remain around the undocumented limit parameter and whether full postcodes are required, but nothing essential to invoking the tool 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 50%: query is documented in the schema with examples (Dalston, Leeds, E8) while limit (default 8, max 20) is undocumented anywhere. The description adds no detail on either parameter, so the undocumented limit/result-count behavior remains 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+resource ("Find UK places ... and postcodes by name") and enumerates the covered entity levels (nations, regions, councils, constituencies, towns, wards, neighbourhoods), which tells an agent this is a multi-level name/postcode search rather than a single-entity fetch. It does not explicitly contrast with siblings like get_place or lookup_postcode, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the agent can infer this is the tool for finding places by name or postcode, but there is no explicit when-to-use, no exclusion of alternatives (get_place, lookup_postcode, compare_places), and no statement about what to do when no match is found. Adequate but with clear gaps.

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