ai.serff/ca-rate-filings

**Use this to see the REGULATORY POSITION history of a filing — the whole CDI ↔ carrier dialogue plus filer contact info — in order. NOT for the filing's content, rates, or forms.** Content questions live in `get_filing_summary` (actuarial narrative), `get_filing_source_file_link` (raw PDFs for human download), and `search_filing_embeds` (paragraph-level body search). Right questions this answers: - "Show me the full objection thread on FARM-134879410" — every letter, in order - "Who filed this and who reviewed it at CDI" - "What did the carrier say in response to CDI's second objection" - "Give me the paper trail so I can audit how this filing progressed" Fetches every chunk in `correspondence_embeds` for the given SERFF, grouped by `source_file` (one entry per attachment) and ordered by `chunk_index` within each file. Covers three attachment types: - **correspondence_attachment_*.pdf** — the objection thread (CDI questions + carrier responses + follow-ups) - **supporting_document_attachment_*.pdf** — actuarial memos, exhibits, transmittal letters (filer contact / authorship signals) - **<SERFF>.pdf** — SERFF's top-level cover page with filing-person contact block Everything comes back as readable text so the caller can quote it verbatim to the user. Group by `source_file` prefix client-side if you only want, e.g., the objection thread (`correspondence_attachment_*`). For a one-call summary that ALSO includes filing metadata, extracted summary, references, and lineage alongside the correspondence, use `get_filing_dossier`. **Right surface for**: - "Show me the objection thread on this filing" — after a search or when the user hands you a SERFF id and asks what CDI said. - "Pull the carrier's full response to CDI's second-round questions" — you get everything, in order; extract the passage you need. - Auditing/review workflows where a regulator wants the full paper trail on one filing. **Right combination**: pair with `search_correspondence_embeds` — t…

**Use this to see the full REGULATORY POSITION of a filing in one call — current CDI status, who is reviewing it, the entire objection history, filer contacts, and lineage to predecessor filings. NOT the tool if the question is about rating mechanics, base rates, factor tables, or actuarial numerics.** For those, chain into `get_filing_summary` (actuarial narrative), `search_actuarial_embeds` (numerics), or `search_filing_embeds` (paragraph-level body). Right questions this answers in one shot: - "Where does FARM-134879410 stand at CDI right now?" — status, pending/closed, live objections, who's on it - "Give me the full paper trail on this filing so I can audit how it progressed" - "Was this objected to? Approved? Withdrawn? Who reviewed it?" — the `derived` block answers at-a-glance - "Show me the objection thread + carrier lineage + references for this SERFF" — all sections inline Composes `get_filing_summary`, `get_filing_correspondence`, `get_filing_references`, and `get_filing_lineage` in parallel for one SERFF id and returns the union along with a derived at-a-glance block. Each sub-fetch is independent — a missing summary or errored lineage still leaves the rest intact (each section carries a per-section `error` field on failure). Wrong surface for: - Search — start with `search_filings` / `search_summary_embeds` / `search_correspondence_embeds` to find the SERFF, then dossier from there - Caseload / aggregate views — use `list_email_workload` for "which reviewer is on the most Pending filings" Returns `{ serff, meta, derived, summary, correspondence, references, lineage }`. The `derived` block carries `{has_summary, correspondence_file_count, correspondence_chunk_count, has_objections, cdi_reviewer_emails, reference_count, lineage_depth}` — enough for a client to render a status card without walking every sub-payload.

Returns the **reconciled lineage chain** for a SERFF id — leaf filing plus ordered predecessors back to the bureau root. Each chain entry includes the SERFF id, position (0 = leaf), role (`leaf` / `predecessor`), and a lite filing record (state, year, carrier name, product name, filing type, filing date). Distinct from `get_filing_references`, which returns what the filing itself claims inside the PDF. Use this when you want the canonical chain (e.g. "what's the bureau root and prior versions for this Progressive auto programme?"); use `get_filing_references` when you want the carrier-stated lineage. Walks back from any SERFF in a programme's chain — pass either the leaf or any predecessor and you get the same chain back. Returns `{ error: ... }` if the SERFF id has not been resolved into any programme chain (the filing may be a non-rate-affecting type — Withdrawal / Correspondence — or simply not yet ingested). Pair with `search_filings` using `predecessor_prefix`: search returns "filings that some programme adopted from bureau X"; lineage tells you, for any of those filings, the full chain it sits in.

Returns the predecessor, superseded, and companion filings that **this filing itself** cites in its supporting documentation. Carrier-claimed lineage extracted from inside the PDF (e.g. "supersedes XXXX-NNNN", "loss costs adopted from NCCI-NNNN"). Distinct from `get_filing_lineage`, which returns the reconciled chain across the corpus. The two often agree but can diverge — `get_filing_references` is the carrier's stated lineage; `get_filing_lineage` is what was actually wired together across filings. When they disagree, that is itself a signal worth surfacing. Each entry typically carries a SERFF id, NAIC, group code, filing type, and a relationship label (predecessor / superseded / loss-cost-source). Use to answer "what does this filing claim to replace?" or "which bureau filing did this carrier adopt?". Returns `{ error: ... }` if no references record exists for the SERFF id (the filing has not yet been classified).

Returns a short-lived **V4-signed GCS URL** for a single SOURCE file (PDF / XLSM / XLSX / DOC / ZIP) the carrier submitted for a SERFF filing. The link is intended for **display to the end user** — they click it in their browser to download the file. **CRITICAL: DO NOT fetch this URL yourself.** Surface it to the user verbatim and stop. The URL is a signed link for the human's browser, not for the model. Fetching it pulls the entire source file (often tens of MB of PDF / XLSM) into your context window and serves no purpose the user did not already get from seeing the link. Pair with `list_filing_source_files` to discover the file names first, then call this to mint a link. When you respond to the user, include the URL **and the `expires_at` timestamp** so they know how long they have to click — after that the link returns 403 and they'll need to ask for a fresh one. Link properties: direct V4-signed GCS URL, expires after `ttl_seconds` (default 900 = 15 min, capped at 3600). Bypasses Cloud Run entirely. Intended for human clicks, NOT for the model to fetch. Whitelist is dynamic, keyed off the actual contents of the filing's source-files directory — same set `list_filing_source_files` advertises. `file_name` must be a basename (no slashes, no `..`) AND must appear in the listing. Returns `{ serff, file_name, url, expires_at, ttl_seconds, notice }`. The `notice` repeats the don't-fetch directive — include it in your response to the user too.

Returns an actuarial narrative summary for a single SERFF id — the **Filing Type** header, the **"What This Filing Does"** section (concrete bullet-pointed change list with page citations for Rate / Rule / Form / New Programme / Withdrawal filings), the structured **Description**, and the key references the summary cites. This is the fastest route from "I have a SERFF id" to "I understand what this filing changes" — typically a few KB rather than the hundreds of KB of raw source. Page citations of the form `(p. N)` let a reviewer verify each claim against the source PDF. Returns `{ error: ... }` if no summary exists for the SERFF id (the filing has not yet been classified). Use `list_filing_source_files` and `mcp_health` to triage; do not retry.

**Use this to size up a person's REGULATORY caseload — how many filings a reviewer, actuary, or contact appears on, split by filing status. NOT for content or rating questions about the filings themselves.** Wrong tool for reading filing content, answering "what does this filing do", or seeing the objection text itself. For those, chain from a caseload result: this tool gives you the emails and volumes; `search_correspondence_embeds({email})` or `get_filing_correspondence({serff})` returns the actual paperwork. Right questions this answers directly: - "Which CDI reviewer has the heaviest live caseload?" → `email_domain='insurance.ca.gov'` + `year=2026` — top rows show pending vs closed split - "How many filings has actuary jane@wps-inc.com been on this year, and how many are still Pending?" → `email='jane@wps-inc.com', year=2026` - "Top carrier-side filers across the whole corpus" → no filter, `topK=50` - "Which of Pan Wong's recent Farmers filings are still under CDI review" → `email='pan.wong@farmersinsurance.com'`, then `search_correspondence_embeds({email, filing_status:'Pending'})` for the specific filings Cost: one indexed aggregate + one join against `filings`. No LLM. Each row: `{email, filings_total, filings_closed, filings_pending, filings_other, earliest_filing, latest_filing}`. `filings_closed` matches `serff_filing_status ILIKE 'Closed%'` (Approved, Withdrawn, Disapproved, Acknowledged); `filings_pending` matches `ILIKE 'Pending%'`; `filings_other` catches everything else (Filed, Draft, N/A, etc.). Sorted by `filings_total` descending, top `topK` returned.

Lists the **source files** (PDFs, XLS spreadsheets, DOC manuals, ZIP archives) ingested for a SERFF id. Returns metadata only — name, size in bytes, MIME-class type (`pdf` / `spreadsheet` / `document` / `csv` / `archive` / `other`), file extension, modified timestamp. Pair with `get_filing_source_file_link` to mint a signed download link the user can click — list names here, mint a link there. Use this to: - triage a filing whose summary looks thin ("did we even ingest the right files?"), - discover the XLSM rater / rate manual PDF / rating-samples spreadsheet for a filing, - confirm which artefacts a filing actually shipped (e.g. is there a separate rate manual XLS, or just the PDF?). Returns `{ error: ... }` if no source files exist for the SERFF id.

Returns the resolved identity behind the current MCP bearer — email, company_name, account_type (free vs production), and company_reference. Quota-exempt: this is an identity probe, not a value-bearing call. Returns nulls for fields mono has no value for. Useful for an MCP client to confirm "who am I talking to mono as" without burning the user's monthly quota.

Onboarding + connection guide. Returns plain-text instructions: sign up for a free account at statefilings.ai, use the client_id / client_secret shown at signup when the MCP client prompts for auth, and per-client walkthrough URLs (Claude, ChatGPT). Quota-exempt — call this whenever a user asks how to use this MCP, get set up, or connect a new client.

Diagnostic snapshot of the deployed MCP server: build identifier, server_version (1.0.<PR> tag), boot time, advertised tool names, a hash of the tool surface, and corpus_updated_at (freshest watermark across the filings pipeline). Call this first when you suspect the connector is showing a stale tool list or you want to detect whether code or data has changed since your last call — compare tools_advertised against what your client lists, server_version for code, corpus_updated_at for data.

Pure vector search over per-filing actuarial-memorandum embeddings (`extract_embeds` where `kind='actuarial_memo'`). Each hit is a filing whose memo is semantically closest to your query, with the matching excerpt and lite filing metadata. **Cost**: one query-embedding call + one indexed Postgres lookup. Bounded, cheap, fast. No LLM planning, no LLM composition. **This is the right tool any time the question is *actuarial-shape*.** Reach for it — not `search_summary_embeds` and not `search_filing_embeds` — when the user is asking about: - Rate adequacy: headline rate change, indicated vs selected, off-balance, capping. - Loss trends: severity trend, frequency trend, pure-premium trend, projected ultimates, LDFs, IBNR development. - Credibility / experience: experience period, weight assigned to own experience vs class-plan / bureau, credibility tables. - Expense / profit provisions: permissible loss ratio, target combined ratio, profit & contingency loading, expense ratio, investment-income offset. - Reason codes / drivers: reinsurance cost, weather/cat load, severity-driven rate need, mix shift, frequency reductions from telematics. - Anything where the answer would be a *number from the actuarial memo* rather than a description of what the filing does. The memo is where actuaries put the numerics; the extraction summary is where the pipeline puts the prose. If the question reaches for numbers, hit this surface first. **Wrong surface for**: - *Content* questions ("filings discussing wildfire scoring", "telematics programmes", "parametric triggers") — those discuss what the filing is *about*, not actuarial numerics. Use `search_summary_embeds` (broader coverage). - Concrete-filter questions ("Filings from carrier NAIC 12345 in 2024") — use `search_filings`. - Filings with no actuarial memo. Memos are typically attached to Rate filings; Form, Rule, and Withdrawal filings often have none. Coverage is narrower than `search_summary_embeds` for that reason — most of…

**Use this to understand the REGULATORY POSITION of a filing — what the state regulator questioned, how the carrier answered, who was on the exchange. NOT to understand what the filing does or how it rates.** Wrong tool for content questions ("what does this filing change", "what's the base rate", "which forms did it introduce", "what's the indicated vs selected rate"). Reach for `search_summary_embeds` (filing content), `search_actuarial_embeds` (rate/trend/credibility numerics), or `search_filing_embeds` (paragraph-level filing body) instead. Right tool for questions about the state's dialogue with the carrier: "what did CDI push back on", "who is the reviewer on this filing", "which of my Pending Rate filings still have unresolved objections", "every filing involving actuary X". Pure vector search over `correspondence_embeds` — the per-chunk embed table populated from three attachment types in a filing's source folder: - **correspondence_attachment_*.pdf** — CDI objection letters + carrier response letters (the dialogue itself) - **supporting_document_attachment_*.pdf** — actuarial memos, exhibits, transmittal letters (highest volume of filer contact info) - **<SERFF>.pdf** (top-level cover page) — SERFF's official filing-person contact block (highest per-page email density) Every hit is a passage from one of those, ranked by cosine similarity. The excerpt IS the source text — you can quote it back to the user to replay the exchange or identify who filed the paper without a separate PDF fetch. Use `source_file` on each hit to see which attachment type the excerpt came from. **Facet filters** (all optional, all combine with AND on top of the semantic ranking): - `email` — chunks mentioning this exact address (case-insensitive) - `email_domain` — chunks mentioning any address on this domain (e.g. `insurance.ca.gov` for CDI reviewers) - `serff` — scope to one filing's thread - `filing_status` — substring match (use `Pending` for live objections, `Closed…

Pure vector search over per-chunk full-document embeddings (`filing_embeds`, ~12.4M rows across ~65K filings — each filing sliced into ~190 paragraph-sized chunks). The most granular semantic surface in the corpus. **Cost**: one query-embedding call + one indexed Postgres lookup. No LLM planning, no LLM composition. **Right surface for**: - "Find the exact passage discussing X" — granular text-search where you need the paragraph not just the filing. - "Find filings whose body text mentions X" when the summary-level surface (`search_summary_embeds`) might miss a topic buried in a long PDF. - **"Drill into this specific filing semantically"** — pass `serff` to restrict the cosine search to a single filing. Without scoping, commodity-vocabulary chunks from other filings can out-rank your target filing; scoping eliminates that. **Wrong surface for**: - Filing-level questions where multiple hits per filing are noise — use `search_summary_embeds` (one match per filing). - Concrete-filter questions like "Filings from carrier NAIC 12345 in 2024" — use `search_filings`. `aggregate: true` (default) collapses to top-K *filings* by best-chunk similarity (one row per filing, the best matching paragraph as excerpt). `aggregate: false` returns top-K raw chunks (may include several from the same filing) — use when the user asked to see the actual paragraphs. When `serff` is set, aggregate is forced to false (every hit is the same filing already). Returns top-K hits, each with `{serff, chunk_index, similarity, excerpt, meta}`. Default `topK=10`, max 50. Excerpt is the first 800 chars of the matching chunk.

Search the SERFF filings corpus by carrier, NAIC, product line, state, year-range, filing type, or bureau lineage. Returns a lite row shape per match (SERFF id, state, year, NAIC, group code, carrier name, product name, filing type / status / date). For the substance of a filing, follow up with `get_filing_summary` once you have a SERFF id. All filters AND together. Defaults: `limit=25`, capped at 100; ordered by filing date descending. Pagination via `offset`. The full count matching the predicate is returned in `total` (independent of `limit`/`offset`) so you can decide whether to paginate or narrow the predicate. Common patterns: - "All California auto filings from 2024" → `state="CA"`, `product_type="Auto"`, `year=2024`. - "Recent rule changes in workers comp" → `product_type="Workers"`, `filing_type="Rule"`, `year_from=2023`. - "Which Progressive filings adopted ISO?" → `search="PRGS"`, `predecessor_prefix="ISOF"`. - "Anything mentioning telematics in the product name" → `search="telematics"`. `predecessor_prefix` answers "filings adopted from a bureau" questions — it restricts to filings that appear in some programme's adopted-from chain, so orphan bureau filings no carrier ever pulled in are excluded. Validated against `/^[A-Z][A-Z0-9]{1,7}-?$/`; trailing dash optional. Invalid values return `{ error: ... }` rather than a row set. Only filings that have been fully read and classified are returned — partial / pre-classification rows are hidden so every result is a filing you can actually reason about.

Pure vector search over per-filing extraction-summary embeddings (one embedding per filing, ~59K rows total). Each hit is a filing whose extraction summary is semantically closest to your query, with the matching excerpt and lite filing metadata (state, year, company, product type, filing type, filing date). **Cost**: one query-embedding call + one indexed Postgres lookup. Bounded, cheap, fast. No LLM planning, no LLM composition. Always reach for this before any LLM-driven alternative. **Right surface for *what is this filing about* questions**: - "Show me filings discussing X" — content questions where X is not a concrete filter (wildfire scoring, telematics programmes, autonomous-vehicle exposure, ESG factors, parametric triggers, etc.). - "Find filings that mention <topic>" — when you need to discover filings by content rather than by structured metadata. - "Filings citing trend data on <thing>" — when the question is content-shaped, not numerics-shaped. **Wrong surface for**: - *Actuarial-shape* questions like "filings with credibility under 50%", "filings whose indicated and selected rate diverge sharply", "rate filings where frequency trend is negative". Use `search_actuarial_embeds` — those numerics live in the actuarial memo, not the summary. - Concrete-filter questions like "Filings from carrier NAIC 12345 in 2024" or "ISOF-rooted filings carriers adopted". Use `search_filings` with the typed filters — much faster, no embedding cost at all. - Anything with a SERFF id already in hand — use the `get_filing_*` tools. **How to combine**: - For "recent auto programmes in California with novel rating factors": first `search_filings` (state=CA, product_type="Auto", year_from=…) to get a candidate set, then call this tool over those candidates' descriptions implied by the question. - For "filings whose summary mentions X": this tool alone, then `get_filing_summary` on the top hits to read in full. Returns top-K hits, each with `{serff, similarity, excerpt, m…