io.github.jdw2111/propraven

Composite hazard score for a parcel: flood (FEMA NFIP zone), wildfire (USFS WUI), seismic (USGS ASCE7), windstorm, air quality (EPA AQS), and crime (composite tier). Each sub-score includes source citations. 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 with a hazard criterion). Backed by /api/v1/parcels/{id}/risks. Coverage varies by hazard: flood and crime are widely available; wildfire is strongest in CA/OR/WA/ID/MT/CO; seismic strongest on the West Coast.

Resolve an owner name or entity to its full property portfolio. Pierces LLC/Trust veils where PropRaven has linked the entity to its parent (via SEC Ex 21, sponsor parent-rollup, and county-level filings). Returns: canonical owner name, entity type, portfolio summary (count, total value, geographic distribution), and a list of parcels owned. Use when the user names a person, LLC, trust, or public company and wants to see what they own. Do NOT use when starting from a parcel (use parcel.lookup, which returns owner inline). If `ticker` is provided, the tool searches owner records for the company name first (best-effort). Tier-1 portfolios (SEC-tracked public companies — DHI, INVH, AMH, PHM, etc.) have higher confidence on cross-state attribution.

Fetch reports for 2–25 parcels so they can be ranked against criteria. Returns each parcel's full report (identity, owner, valuation, risks, permits, deeds) in a single payload — the calling agent does the per-criterion scoring and final ranking. This is the underwriting / shortlist loop. 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). The `criteria` argument is returned verbatim in the response so the agent can pin its scoring to the user's intent.

Resolve a single US parcel by identifier (composite county_fips:parcel_id, street address, or APN). Returns the canonical PropRaven record: identity, current owner, valuation, geography, and source provenance. 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: "37183:0012345" })` or `parcel.lookup({ query: "420 S Tryon St, Charlotte NC" })`.

Filter US parcels by geography + attributes. Returns a ranked list (default 50, max 200) of matches with summary fields (id, address, owner, assessed value, last sale). Use when the user wants properties matching criteria ("absentee-owned SFR in Mecklenburg County over $400k", "flipped properties in Phoenix since 2024"). Do NOT use when looking up a single known property (use parcel.lookup) or ranking a known set (use parcel.compare). Backed by the /api/v1/search/full text+attribute index; pass `q` as either a city, owner name, or address fragment.

Timeline of building / construction / demolition permits filed against a parcel. Each permit includes type, status, declared value, issued date, completion date, contractor (where disclosed), and the originating jurisdiction's permit ID. 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 (use parcel.search). Coverage varies by county: top-100 metros have near-complete permit feeds; smaller jurisdictions may be empty.

Deed / transaction timeline for a parcel: every recorded sale, transfer, refinance. Each event includes date, sale price (where disclosed; flagged when withheld by state), buyer, seller, and deed type. 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 (use parcel.search with `sold_since`) or to estimate current market value (use valuation.estimate, which incorporates this data plus comps). Note: 13 states do not disclose sale prices on deeds (KS, MS, TX, UT, WY, etc.); PropRaven flags these explicitly. If `include_liens=true`, the tool ALSO fetches UCC liens via the parcel report — two API calls.

Estimated market value for a parcel: market estimate, assessed value, last sale price, and the underlying assessment + improvement breakdown. 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 — PropRaven AVM has ±10–15% MAE in normal markets, wider in tail. Historical AVM (as_of) is not yet supported in v1; tool returns the current snapshot.