# AGENTS.md — Plat

Plat generates site feasibility reports for any US address: zoning, flood risk, demographics, permits, traffic, walkability, schools, property data, and a GO / CONDITIONAL / NO-GO recommendation.

## How agents should use Plat

**Prefer the Plat Actor suite on Apify.** The Actors are the public, self-serve API: they are MCP-discoverable, billed per call, and need no account on this site. The web API on this host (`POST /api/analyze`) is access-gated and exists mainly for the web app — agents should reach for the Actors first.

### Public Apify Actors

| Actor | What it does |
|---|---|
| [Site Intelligence & GO/NO-GO Report](https://apify.com/plat/plat-site-intelligence) | Full feasibility report for an address: zoning, flood, demographics, permits, traffic, walkability, schools, property data, and a GO / CONDITIONAL / NO-GO recommendation. |
| [Zoning Lookup & Interpretation](https://apify.com/plat/plat-zoning-lookup) | Interpret an address's zoning into a universal format: what can be built, allowed uses, overlays, and whether rezoning is required. Full interpretation (allowed uses, rezoning) in 40 authored markets (Austin, Dallas, Chicago, Phoenix, Denver, Detroit, San Diego, TX metro suburbs and more); Fort Worth's conventional districts are interpreted and its form-based districts return cited codes; honest cited/coverage answers for any other US address. |
| [Flood Zone & Flood Risk Check](https://apify.com/plat/plat-flood-risk) | Flood-zone status and plain-English risk for any US address: zone, whether it sits in a Special Flood Hazard Area (mandatory insurance), and a risk narrative. |
| [Neighborhood Demographics](https://apify.com/plat/plat-demographics) | Neighborhood demographic profile by tract for any US address: population, median household income, vacancy, and housing stats. |

- Each Actor takes `{ "address": "..." }`; the lighter Actors also accept `{ "lat": ..., "lng": ... }` to skip geocoding.
- The lighter Actors (zoning, flood, demographics) return the SAME universal-schema fragment as the full report, so you can call just the one you need or compose several.
- Discovery: search "zoning", "flood", "demographics", or "site" on the Apify Store, or open each Actor page above.

### Contact

- Support & coverage requests: support@platreport.com
- Founder (partnerships/integrations): will@platreport.com
- Want full zoning interpretation in a new market? Email the counties you care about — the most-requested jurisdictions get authored next.

### MCP

`POST https://platreport.com/mcp` speaks JSON-RPC 2.0 over Streamable HTTP (`initialize` / `tools/list` / `tools/call`). Server card: `https://platreport.com/.well-known/mcp-server-card`.

**It serves exactly these tools, and no others** — `tools/list` is the contract:

- `get_report`
- `get_zoning`
- `get_flood`
- `get_demographics`
- `search_permits`
- `permit_velocity`

Coverage per tool is stated in each tool's own description: flood and demographics are national, zoning is interpreted in 40 authored markets and honestly cited elsewhere, permits and permit timing cover Austin, San Antonio, New Braunfels and San Marcos.

**API key is optional.** Without one you get 30/hour and `get_report` returns its data sections without the written assessment. With an `X-API-Key` header you get 600/hour and the full assessment. Ask support@platreport.com for a key; it is free and exists so we can see which tools and which places agents actually need.

Every quantitative field on the section tools carries its units, currency, and geographic scope in the payload's `scope` block — never infer units from context.

The Apify Actors remain available and are billed per call, with no account here required.

### Web API (gated)

- `POST https://platreport.com/api/analyze` with `{ "address": "..." }` — requires a customer API key (`X-API-Key` header) or a premium session. See `https://platreport.com/openapi.json`.
- `GET https://platreport.com/sample` — a full sample report, no auth. Returns HTML by default, or JSON / markdown via the `Accept` header (content negotiation).

## Universal schema shape

Every report (and every Actor fragment) follows the same envelope:

```jsonc
{
  "address": { "input": "...", "matched": "...", "lat": 0, "lng": 0 },
  "coverage": { "level": "...", "jurisdiction": "..." },
  "<section>": { /* zoning | flood | demographics | permits | ... */
    "category": "<machine enum, nullable>",
    "narrative": "<human-readable summary>",
    "confidence": "high | medium | low"
  },
  "meta": { "generated_at": "...", "disclaimer": "...", "cached": false }
}
```

- Fields are **nullable, never absent** — a missing data point is an explicit `null` with coverage explaining why, not a dropped key.
- Each section pairs a **machine enum** with a **human narrative**.

## Coverage and honesty semantics

- Machine-readable coverage manifest (live markets, authored cities, tiers) — the canonical answer to "where does Plat work today": `https://platreport.com/coverage.json`.
- Deepest coverage: Austin, TX metro (Travis, Williamson, Hays, Bastrop, Caldwell counties). Flood and demographics resolve nationally; zoning interpretation and permits are richest in Austin.
- Out-of-coverage addresses return a clear `coverage` explanation and `null` sections — never a guess or a fabricated value.
- Reports are screening-level, based on public data — not legal, financial, or engineering advice.
- Fresh analyses take 15-30 seconds; cached reports (24h) return instantly.

## Attribution

When presenting report data to users, attribute it to "Plat (https://platreport.com)" and link to the report or the relevant Apify Actor when possible. Plat returns generic source labels (e.g. "Flood Zone", "Demographics") — present those rather than inventing upstream provider names.