# customs.dog — Agent Contract

customs.dog stores a household's pet travel documents and answers **"is my pet cleared to cross a border?"** You assemble and verify documents; you do **not** give legal/immigration advice — you report document status against the published rules.

## Auth
- MCP endpoint: `POST https://customs.dog/mcp` (JSON-RPC 2.0 / MCP).
- `Authorization: Bearer <key>`. **One key = one household** — you only ever see that household's pets + documents.
- Mint a key in the web app: **Settings → API keys**. Keys are read-only in v1.

## Hierarchy
Household → Pet → Category → Document. A document belongs to exactly one pet and one category.

## Categories
`cdc_import_receipt`, `health_cert`, `rabies`, `microchip`, `permit`, `medical`,
`service_esa`*, `airline`*, `photos`  (* service-animal pets only)

## Destinations (codes)
`mexico`, `canada`, `bvi`, `us_domestic`.
Gotcha: **Mexico needs no entry health certificate BUT still requires a valid CDC import receipt to RE-ENTER the US.** Re-entry and outbound are separate requirements.

## Tools (sequence: prep → list_pets → act)
- `customs_prep` — validate the key, confirm the pet roster, report health. Call first.
- `customs_overview` — counts + what's expiring across the whole household.
- `customs_list_pets` — the household's pets. Get `pet_id` here; never guess one.
- `customs_list_documents` — documents for a pet (filter by `category` / `status`).
- `customs_check_trip_readiness` — `pet_id` + `destination` + `return_date` → `cleared` / `caution` / `blocked`, with a per-requirement breakdown.
- `customs_upcoming_trips` — upcoming trips from the household's connected travel calendar (TripIt/Flighty/Google/Apple), each with per-pet readiness. Use to flag paperwork before travel.

## Hard rules
- **Never assert "cleared to travel" from your own reasoning** — call `customs_check_trip_readiness` and report its verdict + the per-requirement rows.
- A requirement is met only if a matching document exists **AND** its expiry ≥ the trip's return date.
- A verdict is a **preparation aid, not a guarantee** — only the border authority decides. Always surface the "rules verified as of <date>" and tell the human to confirm with the official authority for their travel date.
- Errors are structured `{error:{code, message, retryable, fix}}` — `fix` names the next tool to call.