Case Study · PROJECT_01
Turning fragmented geographic data access into an explainable tool that an AI agent can query directly — no scraping, no manual lookup, no ambiguity about which county a ZIP code actually belongs to.
The problem
A ZIP code is a postal delivery construct, not a governmental boundary — plenty of ZIP codes cross county lines, and a naive one-to-one lookup silently produces wrong answers for anyone doing geographic analysis, service-area planning, or compliance work tied to county boundaries. Getting this right means handling overlap explicitly rather than picking whichever county happens to come back first.
The second problem was interface: this needed to be usable directly by an AI agent mid-conversation, not just as a script someone runs by hand. That meant building it as an MCP (Model Context Protocol) server — a tool an AI desktop client can call directly, with typed inputs and outputs the model can reason about.
Architecture
Geographic reference data is pulled from an external API and held in BigQuery, giving the server a queryable, versioned source of truth instead of re-fetching or re-deriving mappings on every call.
Rather than one do-everything endpoint, the server exposes distinct tools — forward lookup (ZIP → county), a batch variant for multiple ZIPs at once, and a reverse lookup (county → ZIPs) — each with a narrow, predictable contract an agent can call correctly without guessing at parameters.
Because ZIP codes can span multiple counties, the server treats overlap as a first-class case rather than an edge case — a lookup returns every county a ZIP actually intersects, with filtering logic to narrow results when a caller needs a single best match instead of the full set.
The lookup and overlap logic is covered by tests — geographic edge cases (ZIPs spanning several counties, invalid or non-existent ZIPs) are exactly the kind of thing that looks correct until a specific real input breaks it.
What it proves
This isn't really a ZIP-code project. It's a template for a broader pattern: taking a fragmented, easy-to-get-subtly-wrong data problem and turning it into a small, well-tested, explainable tool that an AI agent — or a human — can call with confidence. The same shape applies to plenty of messy organizational data problems that aren't about geography at all.
The hard part was never fetching the data. It was deciding what "correct" means when the real world doesn't map cleanly onto the data model — and building tests that hold that decision in place.
If something in your organization's data doesn't map as cleanly as everyone assumes, that's usually where the real work is.
Get in touch