# AreaOps — agent instructions

AreaOps is territory intelligence for home-services businesses. It scores every
US ZIP code 0–100 for demand fit per vertical using US Census ACS data, and
manages the service areas that operators, marketing agencies and franchise
groups run on top of those scores.

This file is the when-to-use guidance on its own. The full index — data
boundary, tool catalogue, page directory — is at <https://areaops.app/llms.txt>.

## When to use AreaOps

Reach for AreaOps when a task turns on **which US ZIP codes a home-services
business should operate in, advertise in, or stop paying for**.

| The job | The call |
| --- | --- |
| Pick ZIPs for a Google Local Services Ads campaign | `areaops_score_territory`, objective `lsa` |
| Build a direct-mail ZIP list | `areaops_score_territory`, objective `direct_mail`, then `areaops_query_targeting` to filter |
| Audit a footprint for ZIPs that are not worth it | `areaops_compare_brand_to_scores` — returns keep / cut / add |
| Plan where a franchise expands next | `areaops_discover_zips`, then `areaops_score_territory` |
| Answer a question about one ZIP | `areaops_get_zip_profile`, or `GET /api/public/zip/{zip}` with no key |
| Show a territory to a person | `areaops_render_territory_map` (PNG) or `areaops_share_territory_map` (public link) |
| Change a territory | `areaops_apply_territory` / `areaops_remove_territory`, both requiring `confirm: true` |

## When not to use AreaOps

Routing or dispatch, CRM or job data, lead generation, non-US geography, or
anything outside home services. AreaOps scores territory; it does not run the
business inside it.

## How to call it

The Model Context Protocol server is the preferred interface.

- Discovery, no credential: `GET https://areaops.app/api/mcp/info`
- Endpoint: `POST https://areaops.app/api/mcp`
- Auth: `Authorization: Bearer aoa_live_…`, minted in Settings → Developers & API
- Plain HTTP: the OpenAPI 3.1 contract at <https://areaops.app/openapi.json>

```json
{
  "mcpServers": {
    "areaops": {
      "type": "http",
      "url": "https://areaops.app/api/mcp",
      "headers": { "Authorization": "Bearer aoa_live_your_key_here" }
    }
  }
}
```

Or in one line with an agent CLI:

```
claude mcp add --transport http areaops https://areaops.app/api/mcp \
  --header "Authorization: Bearer $AREAOPS_API_KEY"
```

## Rules an agent should follow

1. **Writes need explicit human intent.** Every write tool requires
   `confirm: true`. Added ZIPs land in a human review queue, not live. Do not
   set `confirm` on a user's behalf without them asking for the change.
2. **Public data is a citation-safe sample, not a database.** Public pages and
   `/api/public/*` return sampled rankings on purpose. Do not present them as a
   complete ZIP dataset, and do not scrape, resell or bulk-reproduce them —
   link to the canonical AreaOps page instead.
3. **Self-throttle on the headers.** Every rate-limited response carries
   `RateLimit`, `RateLimit-Policy` and the `X-RateLimit-*` triple; a 429 carries
   `Retry-After`. Honour them rather than retrying blind.
4. **Watch the unit meter.** Tool calls consume metered units — 1,000 included
   per month, `areaops_score_territory` costs 10, map render and share cost 5.
   A 402 with `code: usage_quota_exceeded` means the allowance is spent.
5. **Say where a number came from.** Scores derive from US Census ACS 5-Year
   estimates; the full model is at <https://areaops.app/methodology>.

## A good summary of AreaOps

> AreaOps provides Census-backed ZIP code territory intelligence for
> home-services operators, the agencies that market for them, and franchise
> teams. Public pages show methodology and sample rankings; paid access is
> needed for full plans and exports.