Search UK street crime, outcomes, stop and search, and neighbourhood teams (Scotland: BTP only).
Scored across 6 tools
Each tool has a clearly distinct purpose: finding neighbourhoods, listing reference data, searching crimes, searching outcomes, searching stop-and-search records, and fetching crime outcome histories. The descriptions explicitly delineate when to use one over another (e.g., search_crimes vs search_outcomes) and cross-reference each other, leaving no ambiguity.
All tools follow a consistent ukcrime_<verb>_<noun> snake_case pattern with no deviations. Verbs are standard (find, get, list, search) and nouns clearly denote the resource.
Six tools are well-scoped for a read-only UK police crime data API, covering lookup, search, and detailed retrieval without redundancy. The count is neither thin nor bloated.
The surface covers neighbourhood discovery, reference decoding, crime search, outcome search, stop-and-search search, and detailed outcome histories. Minor gaps exist, such as no explicit category filter for crime search or outcome-type filter for outcome search, but these are workable given the returned counts and pagination.
Find the police force and neighbourhood policing team for a point, or look one up by force and neighbourhood id. Returns the team's description, contact channels and police stations, its current priorities with the action taken, team members' ranks and names, and upcoming engagement events. include adds the boundary polygon, needed only to split a neighbourhood too large to search into smaller polygons: ukcrime_search_crimes, ukcrime_search_outcomes and ukcrime_search_stops take the neighbourhood directly through area 'neighbourhood'.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude, WGS84 decimal degrees, to look up by point (with lng). | |
| lng | No | Longitude, WGS84 decimal degrees, to look up by point (with lat). | |
| force | No | Force id such as 'leicestershire', or its name such as 'Leicestershire Police' (ukcrime_list_reference topic 'forces' lists both), to look up by id (with neighbourhood_id); case-insensitive, spaces, underscores and hyphens match each other, '&' matches 'and', and a trailing 'Police', 'Police Service' or 'Constabulary' is optional. | |
| include | No | Optional sections to load: 'priorities', 'team', 'events', 'boundary'. Omitted: priorities, team and events. [] loads none of them. | |
| neighbourhood_id | No | Neighbourhood id from ukcrime_list_reference topic 'neighbourhoods', to look up by id (with force). Case-sensitive; only trimmed. |
| Name | Required | Description |
|---|---|---|
| gaps | No | The force's known coverage gaps, each ending with the date the table was verified. |
| team | No | Team members' ranks and names; present when include has 'team' and they loaded. |
| error | No | Present when the call failed. Absent on success. |
| force | No | The police force the neighbourhood belongs to, as published. |
| found | No | True when data.police.uk holds a neighbourhood team for the point or id. |
| events | No | Every upcoming engagement event the force published, soonest first and undated last; present when include has 'events' and they loaded. |
| notice | No | Parts that could not be loaded from data.police.uk, and how to retry. |
| boundary | No | The neighbourhood boundary; present when include has 'boundary' and it loaded. |
| guidance | No | Why nothing was found and what to try instead; present when found is false. |
| data_note | No | What these records can and cannot say; read it before drawing conclusions. |
| priorities | No | The team's current priorities, force-written; present when include has 'priorities' and they loaded. |
| attribution | No | Open Government Licence attribution for data.police.uk data. |
| events_total | No | Upcoming events published; every one is in events. |
| located_from | No | The point looked up, for a point lookup. |
| neighbourhood | No | The neighbourhood policing team and its public channels, as the force publishes them; an optional field is absent when unpublished, and all text is force-written. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds genuinely useful context beyond them: the content returned (priorities with action taken, team ranks/names, events), and the specific operational reason the boundary polygon exists. It does not state what happens if no lookup arguments are supplied, which matters given zero required parameters.
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 dense sentences, front-loaded with the core action and scope, then the return contents, then the sibling routing. Every clause carries information, though the middle enumeration of returned sections is long enough to slightly slow scanning.
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 detail return values, and annotations cover the safety profile; params are fully documented in the schema. The only real gap is the absence of any statement about behavior when neither lookup mode is supplied, which is notable for a tool with zero required parameters.
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 and the schema already documents lat/lng/force/neighbourhood_id in detail. The description earns above-baseline credit by explaining the intent of 'include' beyond the schema's 'Optional sections to load' — specifically that boundary is only for subdividing oversized neighbourhoods — and by clarifying how downstream search tools consume the neighbourhood.
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 ('police force and neighbourhood policing team'), and explicitly names both supported lookup modes: by lat/lng point or by force + neighbourhood_id. This is unambiguous and clearly distinguishable from the list/search 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?
Explains the two lookup paths and then routes the agent away from unnecessary use: the boundary in 'include' is 'needed only to split a neighbourhood too large to search into smaller polygons', and search_crimes/search_outcomes/search_stops 'take the neighbourhood directly through area neighbourhood'. This is explicit when-to-use and when-not-to-use guidance naming alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full police outcome history of up to 25 crimes by persistent_id — the 64-character id on crimes from ukcrime_search_crimes and ukcrime_search_outcomes. Returns each crime with every outcome, oldest first, and lists the ids data.police.uk does not hold. Anti-social behaviour records carry no persistent id.
| Name | Required | Description | Default |
|---|---|---|---|
| persistent_ids | Yes | 1–25 persistent ids from the persistent_id field of ukcrime_search_crimes or ukcrime_search_outcomes results. A comma- or space-separated string is also accepted; ids are lower-cased and repeats dropped. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| crimes | No | The crimes found, in the order their ids were given. |
| failed | No | Ids whose lookup still failed after retries for a reason other than a missing crime (outage, timeout, rate limit). Empty when none. |
| guidance | No | What to do about ids in not_found or failed; absent when every id resolved. |
| data_note | No | What these records can and cannot say; read it first. |
| not_found | No | Ids data.police.uk holds no crime for. |
| attribution | No | Open Government Licence attribution. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and openWorld, so safety is covered. The description adds behavior the annotations cannot: results are ordered oldest first per crime, ids not held by data.police.uk are listed rather than silently omitted, and the 25-id cap is stated. This is meaningful operational context beyond the structured hints.
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 dense sentences with no filler; the core action and the id cap lead, followed by return ordering and the ABS caveat. Well front-loaded, though the clause about ids data.police.uk does not hold is slightly compressed and could read ambiguously.
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 a fully documented single parameter, an output schema, and annotations covering safety, the definition supplies everything needed to invoke correctly: input source, limit, ordering, and the ABS edge case. Return-value details are legitimately delegated to 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 coverage is 100% and the schema already documents the 64-hex pattern, 1–25 range and comma/space tolerance. The description still adds provenance (the id comes from the persistent_id field of two named sibling tools) and reinforces the 25-item ceiling, which is the parameter's most consequential constraint.
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 ('Fetch the full police outcome history of up to 25 crimes by persistent_id') and names the sibling tools that supply the input id, so an agent can distinguish it from ukcrime_search_crimes and ukcrime_search_outcomes without opening a 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?
It tells the agent where the required id comes from (the persistent_id field of ukcrime_search_crimes / ukcrime_search_outcomes) and adds a real exclusion ('Anti-social behaviour records carry no persistent id'). It stops short of an explicit 'use this instead of X when Y' statement, so it is clear context rather than full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decode the vocabulary the other ukcrime tools take: police force ids, crime category slugs, a force's neighbourhood ids, and data availability — the published months, and which forces published stop and search in each. Use it when a force, category, neighbourhood id or month is unknown; name_contains filters forces and neighbourhoods by name. The Metropolitan Police has about 680 neighbourhoods, so filter by name there; to get the force and neighbourhood covering a latitude and longitude, call ukcrime_find_neighbourhood instead.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Force id such as 'leicestershire', or its name such as 'Leicestershire Police'; case-insensitive, spaces, underscores and hyphens match each other, '&' matches 'and', and a trailing 'Police', 'Police Service' or 'Constabulary' is optional. Required for topic 'neighbourhoods'. On 'availability', where 'btp' (British Transport Police) is also accepted, adds the months this force did and did not publish stop and search. Not accepted on 'forces' or 'categories'. | |
| month | No | Month as YYYY-MM. Topic 'availability' only: return just that month's row. | |
| topic | Yes | What to list: 'forces' (force ids), 'categories' (crime category slugs), 'availability' (published months and stop-and-search publication), or 'neighbourhoods' (one force's neighbourhood ids; needs force). | |
| name_contains | No | Words that must all appear in the name, in any order — case, accents and punctuation ignored, so the value needs at least one letter or digit. Topics 'forces' and 'neighbourhoods' only. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| force | No | Topic 'neighbourhoods': the force whose neighbourhoods are listed. |
| topic | No | The topic listed; its list field below is the one present. |
| forces | No | Topic 'forces': the forces data.police.uk lists, plus British Transport Police ('btp'), which ukcrime_search_stops takes with area 'force' and ukcrime_search_crimes with area 'force_unplaced'. |
| notice | No | Why a list is empty — a name filter that matched nothing, or a month that is not published — and what to do instead. |
| categories | No | Topic 'categories': every crime category. |
| attribution | No | Open Government Licence attribution for data.police.uk data. |
| availability | No | Topic 'availability': the published-month window and stop-and-search publication by month. |
| neighbourhoods | No | Topic 'neighbourhoods': the force's neighbourhoods, sorted by name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, so the safety profile is covered. The description adds genuine operational context: what the returned vocabulary is used for downstream, the scale of the Met neighbourhood list, and the advice to filter by name there. It does not discuss pagination or rate behavior, but an output schema exists so return-shape disclosure is not required.
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 list before the when-to-use and alternative routing. Dense but every clause carries signal; the only mild redundancy is restating the name_contains scope that the schema already gives.
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 explain return values, and it covers topic selection, prerequisite parameters, filtering guidance, and the sibling alternative. An agent has everything needed to call 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?
Schema coverage is 100% and the schema already documents cross-topic parameter acceptance in detail, so baseline is 3. The description's mention that name_contains filters forces and neighbourhoods adds only marginal 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?
Opens with a specific verb and resource: decode reference vocabulary (force ids, category slugs, neighbourhood ids, availability). It clearly frames this as the lookup/reference tool, which separates it from the search/outcome siblings without needing their schemas.
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 states when to use it ('when a force, category, neighbourhood id or month is unknown') and routes the geo case to the alternative by name ('to get the force and neighbourhood covering a latitude and longitude, call ukcrime_find_neighbourhood instead'). Includes a concrete filtering caveat for the Met's ~680 neighbourhoods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search street-level crimes recorded in one month, or with month_from a range of up to 12 months, inside an area — a point with a 1-mile radius, a polygon, a snapped location_id from an earlier result, or a police neighbourhood — or list the crimes a force could not place on the map (area 'force_unplaced'). Returns the total, counts by category and by latest police outcome, the busiest map points, each month's total for a range, and a page of crimes, each with the persistent_id that ukcrime_get_crime_outcomes takes; for what police resolved in a month, whenever the crime was recorded, use ukcrime_search_outcomes. Locations are anonymised map points, not crime sites. data.police.uk can refuse an area holding more than about 10,000 crimes, whatever the category — then search smaller polygons.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude, WGS84 decimal degrees, for area 'point'. | |
| lng | No | Longitude, WGS84 decimal degrees, for area 'point'. | |
| area | Yes | Area to search: 'point' (lat and lng; a 1-mile radius), 'polygon' (polygon), 'location' (location_id), 'neighbourhood' (force and neighbourhood_id), or 'force_unplaced' (force alone: the crimes that force could not place on the map). An area field the chosen area does not use is rejected. | |
| force | No | Force id such as 'leicestershire', or its name such as 'Leicestershire Police' (ukcrime_list_reference topic 'forces' lists both); case-insensitive, spaces, underscores and hyphens match each other, '&' matches 'and', and a trailing 'Police', 'Police Service' or 'Constabulary' is optional. For area 'neighbourhood' (with neighbourhood_id) and 'force_unplaced' (alone), where 'btp' (British Transport Police) is also accepted. | |
| limit | No | Crimes on this page, 1–200. Default 25. | |
| month | No | Month as YYYY-MM, or the last month of the range with month_from. Omitted: the latest published month, echoed as month in the result. | |
| offset | No | Rows to skip before this page; pass next_offset from the previous result. Default 0. | |
| polygon | No | For area 'polygon': 3–2,500 vertices as { lat, lng } objects, or the string 'lat,lng:lat,lng:…'. The ring closes itself (the last vertex joins the first). [lng, lat] pairs are not accepted. | |
| category | No | Crime category slug such as 'burglary', or its display name such as 'Violence and sexual offences'; case-insensitive, and spaces, underscores and hyphens match each other ('vehicle_crime' finds 'vehicle-crime'). Omitted: every category (all-crime). ukcrime_list_reference topic 'categories' lists them. | |
| month_from | No | First month of a range, YYYY-MM, searched through month — up to 12 months, with a total for each in by_month. Omitted: month alone. | |
| location_id | No | For area 'location': location.location_id from an earlier result — one anonymised map point. | |
| neighbourhood_id | No | For area 'neighbourhood', with force: a neighbourhood id from ukcrime_list_reference topic 'neighbourhoods', or from ukcrime_find_neighbourhood for a point. Case-sensitive; only trimmed. |
| Name | Required | Description |
|---|---|---|
| cap | No | Page limit applied. |
| area | No | The area as the server searched it. |
| error | No | Present when the call failed. Absent on success. |
| month | No | The month searched, or the last month of the range, YYYY-MM. |
| shown | No | Rows on this page. |
| total | No | Crimes matched in the area over the month or range. |
| crimes | No | This page of matched crimes: oldest month first over a range, then by category, then location_id, then id. |
| notice | No | Defaulted month, coverage gaps, why a result is empty, and how to page on. |
| by_month | No | Crimes matched in each month of the range, oldest first; their totals sum to total. Present only when month_from was given. |
| category | No | The crime category searched. |
| data_note | No | What these records can and cannot say; read it first. |
| truncated | No | True when more rows remain after this page. |
| by_outcome | No | Matched crimes by latest police outcome, most first; anti-social behaviour is always '(not recorded)'. |
| month_from | No | First month of the range searched, YYYY-MM; present only when month_from was given. |
| attribution | No | Open Government Licence attribution. |
| by_category | No | Matched crimes by category slug, most first. |
| next_offset | No | Pass as offset for the next page; absent on the last page. |
| top_locations | No | Up to 10 map points holding the most matched crimes. Absent for area 'force_unplaced'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety (readOnly, idempotent, openWorld), so the description adds context the structured fields cannot: a service-side refusal threshold with a workaround, the anonymisation caveat that locations are map points rather than crime sites, and the shape of the aggregated response. This is behavior beyond the annotations, not a restatement of them.
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 paragraph, front-loaded with the core search scope before the returns list and the sibling routing. It is long and slightly run-on, but nearly every clause carries distinct information (area modes, aggregation contents, chaining, limits) 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?
For a 12-parameter, multi-modal search tool with an output schema, the description covers area modes, range semantics, cross-tool chaining, and the operational limit. Return-value detail is present but not required, and nothing an agent needs to invoke 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 100%, so 3 is the floor, but the description adds relational meaning the schema states only per-field: month_from pairs with month to form a range, month omitted defaults to the latest published month (echoed back), and location_id is a 'snapped location_id from an earlier result'. It stops short of clarifying the area-specific parameter combinations in full, which the schema handles.
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 (search street-level crimes) and immediately bounds the scope: one month or a range up to 12 months, inside one of four area types or 'force_unplaced'. It explicitly distinguishes itself from the sibling ukcrime_search_outcomes by contrasting recorded-vs-resolved crimes.
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 when-to-use routing ('for what police resolved in a month, whenever the crime was recorded, use ukcrime_search_outcomes'), explains how outputs chain into ukcrime_get_crime_outcomes via persistent_id, and states the failure condition (>~10,000 crimes refused) with the corrective action (search smaller polygons).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the police outcomes recorded in one month inside an area — a point with a 1-mile radius, a polygon, a location_id, or a neighbourhood — for crimes recorded that month or any earlier one. Returns the total, counts by outcome and by the month each crime was recorded, and a page of outcomes, each with its crime and persistent_id. Use it for what police resolved in a month; ukcrime_search_crimes gives the latest outcome of the crimes recorded in a month instead. Court results are not published; the result says when a force publishes no outcomes.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude, WGS84 decimal degrees, for area 'point'. | |
| lng | No | Longitude, WGS84 decimal degrees, for area 'point'. | |
| area | Yes | Area to search: 'point' (lat and lng; a 1-mile radius), 'polygon' (polygon), 'location' (location_id), or 'neighbourhood' (force and neighbourhood_id). An area field the chosen area does not use is rejected. | |
| force | No | For area 'neighbourhood', with neighbourhood_id: a force id such as 'leicestershire', or its name such as 'Leicestershire Police' (ukcrime_list_reference topic 'forces' lists both); case-insensitive, spaces, underscores and hyphens match each other, '&' matches 'and', and a trailing 'Police', 'Police Service' or 'Constabulary' is optional. | |
| limit | No | Outcomes on this page, 1–200. Default 20. | |
| month | No | Month as YYYY-MM. Omitted: the latest published month, echoed as month in the result. | |
| offset | No | Rows to skip before this page; pass next_offset from the previous result. Default 0. | |
| polygon | No | For area 'polygon': 3–2,500 vertices as { lat, lng } objects, or the string 'lat,lng:lat,lng:…'. The ring closes itself (the last vertex joins the first). [lng, lat] pairs are not accepted. | |
| category | No | Count only outcomes for crimes in this category: a slug such as 'burglary' or a display name such as 'Violence and sexual offences'; case-insensitive, and spaces, underscores and hyphens match each other ('vehicle_crime' finds 'vehicle-crime'). Omitted or 'all-crime': every category. ukcrime_list_reference topic 'categories' lists them. | |
| location_id | No | For area 'location': location.location_id from an earlier result — one anonymised map point. | |
| neighbourhood_id | No | For area 'neighbourhood', with force: a neighbourhood id from ukcrime_list_reference topic 'neighbourhoods', or from ukcrime_find_neighbourhood for a point. Case-sensitive; only trimmed. |
| Name | Required | Description |
|---|---|---|
| cap | No | Page limit applied. |
| area | No | The area as the server searched it. |
| error | No | Present when the call failed. Absent on success. |
| month | No | The month searched — when the outcomes were recorded — YYYY-MM. |
| shown | No | Rows on this page. |
| total | No | Outcomes matched, after the category filter. |
| notice | No | Defaulted month, coverage gaps, why a result is empty, and how to page on. |
| category | No | The crime category counted; absent when every category was (no category, or 'all-crime'). |
| outcomes | No | This page of matched outcomes, sorted by the crime's month, newest first, then crime id. |
| data_note | No | What these records can and cannot say; read it first. |
| truncated | No | True when more rows remain after this page. |
| by_outcome | No | Matched outcomes by outcome, most first. |
| attribution | No | Open Government Licence attribution. |
| next_offset | No | Pass as offset for the next page; absent on the last page. |
| by_crime_month | No | Matched outcomes by the month their crime was recorded, newest first. |
| unfiltered_total | No | Outcomes recorded in the area and month before the category filter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, open-world behavior, so the bar is lower; the description still adds non-obvious traits — the temporal quirk that outcomes cover crimes recorded that month or earlier, the suppress-the-result behavior when a force publishes no outcomes, and the absence of court results.
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 dense sentences, front-loaded with scope, then routing, then caveats. Every clause carries information, though the first sentence is long and would read better split, which keeps it from a 5.
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-value detail is optional, yet the description still sketches the payload (total, per-outcome and per-recorded-month counts, a page with crime and persistent_id). With 11 params fully documented in schema and annotations covering safety, nothing needed for a correct call 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%, so baseline is 3. The description goes further by naming all four area modes and clarifying that the outcome rows are for crimes recorded that month or any earlier one — a semantic 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?
States a specific verb and resource (list police outcomes) plus the scope constraint (one month, inside an area) and enumerates the four area modes. It explicitly contrasts itself with ukcrime_search_crimes, so an agent can separate them 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?
Includes a direct routing rule: use this for what police resolved in a month, use ukcrime_search_crimes for the latest outcome of crimes recorded in a month. It also warns that court results are never published and that a force may report no outcomes, which sets correct expectations before invoking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search police stop and search records for one month, or with month_from a range of up to 12 months, inside an area — a point with a 1-mile radius, a polygon, a location_id from an earlier result, or a police neighbourhood — or across a whole force with area 'force', which includes stops the force could not place. Returns the total and counts by search type, self-defined and officer-defined ethnicity, outcome, object of search, legislation, age range, gender, whether the outcome was linked to the object of search, and whether more than outer clothing was removed, each month's total for a range, and a page of stops. filters narrow the counts and the page together, so filtering one field and reading another's breakdown gives a cross-tab. Forces skip months and some publish none; the result names each force it finds for the area that did not publish, with the months it skipped.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude, WGS84 decimal degrees, for area 'point'. | |
| lng | No | Longitude, WGS84 decimal degrees, for area 'point'. | |
| area | Yes | Area to search: 'point' (lat and lng; a 1-mile radius), 'polygon' (polygon), 'location' (location_id), 'neighbourhood' (force and neighbourhood_id), or 'force' (force alone: every stop the force published for the month or range, placed or not). An area field the chosen area does not use is rejected. | |
| force | No | Force id such as 'leicestershire', or its name such as 'Leicestershire Police' (ukcrime_list_reference topic 'forces' lists both); case-insensitive, spaces, underscores and hyphens match each other, '&' matches 'and', and a trailing 'Police', 'Police Service' or 'Constabulary' is optional. For area 'neighbourhood' (with neighbourhood_id) and 'force' (alone), where 'btp' (British Transport Police) is also accepted. | |
| limit | No | Stops on this page, 1–200. Default 15. | |
| month | No | Month as YYYY-MM, or the last month of the range with month_from. Omitted: the latest published month, echoed as month in the result. | |
| offset | No | Rows to skip before this page; pass next_offset from the previous result. Default 0. | |
| filters | No | Up to 8 filters, all of which a stop must match; they narrow the counts and the page together. Fields: type, self_defined_ethnicity, officer_defined_ethnicity, outcome, object_of_search, legislation, age_range, gender, outcome_linked_to_object_of_search, removal_of_more_than_outer_clothing. | |
| polygon | No | For area 'polygon': 3–2,500 vertices as { lat, lng } objects, or the string 'lat,lng:lat,lng:…'. The ring closes itself (the last vertex joins the first). [lng, lat] pairs are not accepted. | |
| month_from | No | First month of a range, YYYY-MM, searched through month — up to 12 months, with a total for each in by_month. Omitted: month alone. | |
| location_id | No | For area 'location': location.location_id from an earlier result — one anonymised map point. | |
| neighbourhood_id | No | For area 'neighbourhood', with force: a neighbourhood id from ukcrime_list_reference topic 'neighbourhoods', or from ukcrime_find_neighbourhood for a point. Case-sensitive; only trimmed. |
| Name | Required | Description |
|---|---|---|
| cap | No | Page limit applied. |
| area | No | The area as the server searched it. |
| error | No | Present when the call failed. Absent on success. |
| month | No | The month searched, or the last month of the range, YYYY-MM. |
| shown | No | Rows on this page. |
| stops | No | This page of matched stops, oldest first, then by location_id. |
| total | No | Stops matched after filters, over the month or range. |
| notice | No | Defaulted month, coverage gaps, why a result is empty, and how to page on. |
| by_type | No | Matched stops by search type, most first. |
| filters | No | Filters applied, case-insensitively; empty when none. |
| by_month | No | Stops matched in each month of the range, oldest first; their totals sum to total. Present only when month_from was given. |
| unplaced | No | Matched stops with no location — the force's unplaced stops, for area 'force'. |
| by_gender | No | Matched stops by gender, most first. |
| data_note | No | What these records can and cannot say; read it first. |
| truncated | No | True when more rows remain after this page. |
| by_outcome | No | Matched stops by outcome, most first; '(not recorded)' is often the largest. |
| month_from | No | First month of the range searched, YYYY-MM; present only when month_from was given. |
| attribution | No | Open Government Licence attribution. |
| next_offset | No | Pass as offset for the next page; absent on the last page. |
| by_age_range | No | Matched stops by age range, most first. |
| by_legislation | No | Matched stops by legislation, most first. |
| force_published | No | Whether every force found for the area (the one it names, or each located at a point, a polygon's centre and outermost vertices, or a location's map point) published stop and search this month, or in every month of a range: false when any month was missed. Otherwise absent when no force was found, when a month has no row in the publication list, or when none of those found is missing yet a polygon point could not be looked up. |
| unfiltered_total | No | Stops in the area over the month or range, before filters. |
| by_object_of_search | No | Matched stops by object of search, most first. |
| by_self_defined_ethnicity | No | Matched stops by ethnicity as the person defined it, most first. |
| by_officer_defined_ethnicity | No | Matched stops by ethnicity as the officer perceived it, most first. |
| by_outcome_linked_to_object_of_search | No | Matched stops by whether the outcome was linked to the object of search ('true', 'false' or '(not recorded)'), most first. |
| by_removal_of_more_than_outer_clothing | No | Matched stops by whether more than outer clothing was removed ('true', 'false' or '(not recorded)' where the force sent no value, as some do for vehicle-only searches), most first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/idempotent annotations, it discloses genuinely non-obvious behavior: filters narrow the counts and the page together so cross-tabs are possible, and forces skip months or publish none with the gaps named in the result. These data-quality caveats are exactly what an agent cannot infer from 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?
The core operation is front-loaded in the first clause and the three sentences carry almost no filler. However the second sentence is a sprawling enumeration of return fields that is partly redundant given the output schema, making the prose dense rather than tight.
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 and annotations covering safety, the description supplies everything else an agent needs: area-mode selection, the month/range relationship, filter cross-tab behavior, and the force-publishing caveat. Nothing material for correct invocation 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 100%, so a 3 is the floor; the description earns above that by tying parameters together (month_from pairs with month for a range, location_id comes from an earlier result, neighbourhood needs force) and clarifying how filters interact with breakdowns. The individual field semantics still live largely in 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 opening states a specific verb and resource ('Search police stop and search records') and immediately bounds scope by month/range and area mode. An agent can distinguish it from search_crimes and search_outcomes without opening any schema, since the data domain is named 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?
It explains the conditions that select each area mode ('point' with a 1-mile radius, 'polygon', 'location_id', 'neighbourhood', 'force', the last of which 'includes stops the force could not place'). It gives clear context but never names a sibling tool or says when to prefer this over ukcrime_search_crimes/search_outcomes, so it stops short of explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
ukcrime_find_neighbourhoodukcrime_get_crime_outcomesukcrime_list_referenceukcrime_search_crimesukcrime_search_outcomesukcrime_search_stopsAccess street-level crime reports, stop and search data, and outcomes across UK police forces
UK Police MCP — wraps the UK Police Data API (free, no auth)
Search UK planning applications, entities, datasets, and conservation areas
Search UK companies, land registry prices, charities, OS locations, and traffic data
Add one secure layer between your agents and this server.