Skip to main content
Glama
postcodes-io-mcp

postcodes-io-mcp

by Ankur1911

lookup_postcodes

Read-onlyIdempotent

Look up 1–100 UK postcodes in one call and return geographic, administrative, and ONS/GSS details, while sorting terminated, unknown, and invalid postcodes into separate results.

Instructions

Look up 1 to 100 UK postcodes in one call (any spacing or case). Each match returns country, region, local authority (admin_district), county, ward, parish, parliamentary constituency (2024 boundaries), Senedd constituency for Wales, latitude/longitude, OS eastings/northings, LSOA/MSOA, NUTS, police force area, ICB, urban/rural class, deprivation rank and the matching ONS/GSS codes. Postcodes that are no longer live come back under 'terminated' with the year and month; unknown ones under 'not_found'; badly formatted ones under 'invalid_format' without spending an API call. Use detail='full' for every field.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "postcodes": "<postcodes>"
    },
    "name": "lookup_postcodes"
  }
}

Input Schema

NameRequiredDescriptionDefault
detailNo'summary' (default) is trimmed; 'full' returns every field Postcodes.io has.summary
postcodesYesPostcodes such as ['SW1A 2AA', 'ec1a1bb'].

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds real behavior beyond them: batching ceiling, three distinct outcome buckets (terminated with year/month, not_found, invalid_format), and the useful quota detail that malformed input does not spend an API call. It stops short of stating rate limits or whether result order matches input order.

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

Conciseness4/5

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

Front-loaded with what the tool does and its batch limit, then the response payload, then failure modes — a sensible order. The long enumeration of returned fields is dense and borders on a data dump, but with no output schema it is doing necessary work.

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

Completeness4/5

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

With no output schema, the description carries the burden of describing returns and does so thoroughly, including the error buckets an agent must handle. Missing only narrower details such as ordering guarantees and whether error entries are top-level keys; adequate for a two-parameter lookup tool.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: input is tolerant of 'any spacing or case' and detail='full' is recommended to avoid missing fields. The detail enum itself is already documented in the schema, so the gain is modest.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Look up ... UK postcodes') plus the batch scope (1 to 100) and the full return payload. An agent can tell this is a bulk exact-postcode lookup, but the description never names a sibling (find_postcodes, nearest_postcodes) to contrast against, so differentiation is inferred rather than stated.

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

Usage Guidelines3/5

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

Usage is implied rather than spelled out: it's for resolving specific known postcodes in bulk, and 'Use detail='full' for every field' guides the parameter choice. There is no explicit when-not or pointer to find_postcodes/nearest_postcodes for partial or proximity searches, leaving the agent to infer the boundary.

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