io.github.jdw2111/propraven

Hazard profile for a parcel (GET /api/v1/parcels/{id}/risks): flood (FEMA zone + SFHA flag), wildfire, seismic, windstorm, air quality and crime blocks, plus withhold_gate / identity_gate provenance. Use when the user asks about a property's risk profile — insurance pricing, underwriting, or due diligence. Do NOT use to compare multiple parcels (use parcel_compare, which includes each parcel's hazards). Every requested key is present: the value, or null when PropRaven does not hold it. Coverage varies by hazard. Free read — never purchases anything (this is not the paid risk-score product).

List the parcels titled under an owner-of-record name (GET /api/v1/owners/{name}/portfolio). Returns the matched owner name, a portfolio `summary` (count, total_value, total_acreage, by_state, truncated) and the `properties` list (parcel_id, county_fips, state_fips, address, assessed values, last sale, match_basis, match_confidence). This matches owner-name SPELLINGS — it is NOT a verified corporate, parent-subsidiary or beneficial-ownership link. Use when the user names a person, LLC, trust, or company and wants to see what is titled under that name. Do NOT use when starting from a parcel (use parcel_lookup, which returns owner inline). `ticker` is best-effort: it runs an owner-name search (GET /api/v1/owners/search) for the ticker text and uses the top match, returning the candidates under `resolution` — verify them, or call again with `name`. `state` filters the returned properties client-side (the summary stays portfolio-wide). Free read — never purchases anything.

Fetch 2–25 parcels side by side so they can be ranked against criteria. For each parcel it reads the free parcel card (GET /api/v1/parcels/{id}: identity, owner, valuation, building, lot) and, unless include_risks=false, the hazard block (GET /api/v1/parcels/{id}/risks), and returns a normalized `summary` plus the raw `card` / `risks`. The calling agent does the per-criterion scoring and final ranking. NEVER buys the paid parcel report or any other paid product. Use when the user has identified candidate properties (often from parcel_search) and wants them ranked. Do NOT use to discover new candidates (use parcel_search) or for a single property (use parcel_lookup + hazard_score). For deed or permit timelines call sales_history / permits_history per parcel. The `criteria` argument is returned verbatim so the agent can pin its scoring to the user's intent.

Resolve a single US parcel by identifier (canonical state_fips:county_fips:parcel_id, PropRaven UUID, street address, or APN). An ID returns the canonical PropRaven parcel card (GET /api/v1/parcels/{id}): identity, current owner, valuation, geography and source provenance. An address or APN runs the text search and returns up to 5 candidates — re-call with the chosen candidate's `lookup_id` to get the card. Use when the user names one specific property. Do NOT use when ranking multiple parcels (use parcel_compare) or when filtering by criteria (use parcel_search). Example: `parcel_lookup({ query: "37:119:12104406" })` or `parcel_lookup({ query: "2232 Wilmore Dr, Charlotte, NC 28203" })`. Free read — never purchases anything.

Text search over US parcels (GET /api/v1/search/full): pass `q` as a city, owner name, address fragment or APN, optionally narrowed by `field`, `state` and `city`. Returns `{ results, total, totalCapped, page, pages, hasMore, nextCursor }` (default 50 per page, max 200); each result carries parcel_id, apn, county_fips, state_fips, site_address, city, zip5, owner_name, total_value, latitude, longitude (in search rows `parcel_id` is the PropRaven UUID and `county_fips` is 5-digit), plus `lookup_id`, added by this server — pass it to parcel_lookup / parcel_compare. Page with `cursor` (the previous response's `nextCursor`) rather than `page`; `total` is a floor when `totalCapped` is true. Use when the user wants properties matching a name, place or address fragment. Do NOT use when looking up a single known property (use parcel_lookup) or ranking a known set (use parcel_compare). Free read — never purchases anything.

Timeline of building / construction / demolition permits filed against a parcel (GET /api/v1/parcels/{id}/permits). Each permit includes permit_number, permit_type, permit_status, description, work_class, issued_date, completed_date, estimated_cost, contractor_name (where disclosed). Use when the user asks about construction activity, recent renovations, planned work, or wants to detect a property that's actively changing. Do NOT use to find properties WITH recent permits across a market. At most 100 permits are returned (newest first). `permit_count` is the parcel's TRUE count when `permit_count_basis` is "exact"; "capped" means it is the size of the 100-row window (a floor); `truncated: true` means the parcel has more permits than returned. `since` / `types` filter the returned window only (`returned_count` is after filtering). Coverage varies by county. Free read — never purchases anything.

Deed / transaction timeline for a parcel (GET /api/v1/parcels/{id}/deeds): recorded sales and transfers with recording and sale dates, sale price (where disclosed), grantor (seller), grantee (buyer), deed/document type and book/page. Use when the user asks about a property's transaction history, flip activity, or holding period. Do NOT use to find properties with recent sales market-wide, or to estimate current market value (use valuation_estimate). Note: 13 states do not disclose sale prices on deeds (KS, MS, TX, UT, WY, etc.). `event_count` is the number of events returned. `status` says where they came from: per_deed (deed rows), rollup_events (dated rollup entries), summary_only (no events served, but `known_deed_count` deeds are known — see known_deed_count_basis), or none. UCC liens are NOT available here (they are only in the paid parcel report, which this server never buys). Free read — never purchases anything.

Value fields for a parcel from its free card (GET /api/v1/parcels/{id}): market_value, avm_value with avm_confidence / avm_method, total / land / improvement assessed value, tax, last sale price and date, price_per_sqft. Numbers are normalized to JSON numbers (null = not held). Use when the user asks for a property's value, market estimate, AVM, or wants to compare assessed vs market. Do NOT use as a substitute for an appraisal — this is a modeled estimate. Historical AVM (as_of) is not supported; the tool returns the current snapshot. Free read — never purchases anything.