CrimeMapsUK

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

Annotations already cover the safety profile (readOnly, idempotent, non-open-world), so the description wisely spends its words elsewhere: it discloses the normalization denominator, that anti-social behaviour is folded into the counts, that each row carries page_url, and it warns 'these are published rates, not safety ratings.' That interpretive caveat is genuinely useful context beyond structured fields.

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, front-loaded with the scope and metric, ending with a compact caveat. Every clause carries information — geography, denominator, inclusion of ASB, row payload, and the interpretation warning.

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 isn't required, yet the description still sketches row contents (rate, counts, page_url). The main remaining gap is routing: methodology and area_summary exist for definitions and non-ranked views, and the description doesn't mention them.

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 limit/order/category meanings are already documented. The description only adds marginal signal — that an empty category means all street-crime records including ASB, echoing the schema's default. Baseline 3 applies since the schema does the heavy lifting.

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 precise verb+resource ('Postcode districts in England and Wales ranked by published street-crime records') with scope (England and Wales), metric basis (per 1,000 Census 2021 residents) and what each row contains. It is clearly distinguishable from area_summary/postcode_summary by being a ranked list, though it never names those siblings 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 by the word 'ranked' — an agent can infer this is the tool for ordered comparisons rather than summaries. But there is no explicit when-to-use/when-not-to-use guidance and no pointer to area_summary or postcode_summary for non-ranked views, leaving the choice 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, closed-world behavior. The description adds meaningful traits: last 12 published months, district-level aggregation, returned citation/attribution, and a conditional free_report_url for full postcodes, though it does not cover invalid-input or error 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?

Front-loads the resource and scope, then describes return contents, then the conditional free_report_url. Each sentence earns its place and the description is compact for the amount of behavior it discloses.

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 full schema coverage and an output schema, the description supplies the key scope and conditional behavior an agent needs to call it correctly. No major contextual gap remains.

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 the baseline is 3. The description adds interpretation rules beyond the schema: a full postcode such as 'E8 1AA' is answered as its district 'E8', never as the exact postcode.

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 ('published street-crime figures') and scope ('postcode district'), and explicitly distinguishes the exact postcode case by saying it answers 'never for the exact postcode'. This clearly separates it from the exact-postcode-oriented sibling postcode_summary.

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 input condition and aggregation rule, so an agent knows to use this for district-level crime figures rather than exact-address lookup. It does not explicitly name a sibling alternative or give broader when-not-to-use guidance beyond the exact-postcode distinction.

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, closed-world, and non-destructive behavior, so the description need not restate safety. It adds useful context by enumerating the methodology topics covered and noting that the methodology page_url is included, which tells the agent this returns explanatory documentation rather than live figures.

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 definition is a single sentence with no filler and leads with the core purpose. The trailing list is dense but earns its place by scoping the methodology content, though the phrase 'with the methodology page_url' is slightly awkwardly attached.

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

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

For a zero-parameter documentation tool with an output schema, the description covers the main topics and notes the page_url. Combined with annotations and the output schema, an agent has enough to call it correctly; only an explicit usage cue would make it fully complete.

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 tool has zero parameters, so the baseline is 4. No parameter semantics are needed or missing, and the description appropriately spends no space on input arguments.

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 identifies this as a documentation/metadata tool: notes on how CrimeMapsUK builds its figures. It lists the covered topics (coverage, locations, rates, rankings, outcomes, citation), distinguishing it implicitly from the data-returning siblings area_rankings, area_summary, and postcode_summary. It does not explicitly contrast itself with those siblings, so a 4 rather than 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: an agent can infer this is the tool to consult for methodology and definitions. There is no explicit when-to-use, when-not-to-use, or named alternative, nor any prerequisite such as calling it before interpreting sibling results.

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 it as a safe, idempotent, open-world read, and the description adds real context on top: an API key is needed, free results expose only a subset (total, window, coverage state, largest category) while keyed calls return every category, and staleness differs (6 hours vs 15 minutes) so figures can briefly diverge after a publish.

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 payload scope before credentials and freshness caveats, and essentially every clause carries information. The sentences are long and comma-heavy, which slightly slows parsing, but little 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 an output schema present, the description needn't enumerate return fields, and it still sketches the free-tier payload shape and the freshness caveat. For a one-parameter read tool that is close to complete; only the sibling-routing guidance 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 100% and the single postcode parameter is fully documented with an example in the schema, so the baseline of 3 applies. The description contributes only the 0.5 km fixed-radius framing, no extra syntax or format guidance 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?

Opens with a specific verb+resource and scope: published street-crime records in a fixed 0.5 km circle around a postcode over the last 12 published months. That is far more precise than the title alone, though it never names area_summary or area_rankings to make the sibling boundary explicit.

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 fixed-radius, postcode-anchored scope implies when this is the right tool versus area-level siblings, but no sentence states 'use this instead of X when...' or any exclusion. An agent must infer the routing rule from the scope wording alone.

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