ai.serff/ca-rate-filings MCP server

Lists **what's in** each extracted artefact for a filing — section counts, item names, and the page each item came from — without returning any of the bulky factor tables, descriptions, or rate rows themselves. **Call this FIRST**, before `get_filing_extracts`, for any "what does this filing contain" question. It costs a fraction of the tokens and tells you which file + which section you need to pull in detail. `get_filing_extracts` is then the targeted second call once you know the SERFF + file + section that actually answer the user's question. Use this when the user asks: - "What forms does this filing include?" / "List the form numbers in TSIS-134726605." - "How many exclusions does it carry? What are they called?" - "What rate tables are in this filing, and which PDF page are they on?" - "List the discounts / endorsements / coverages this filing offers." - "Where in the source PDF is the territory rate table?" - Any "how many", "what are the names of", or "which page is X on" question about a filing's extracted artefacts. Wrong surface for: - Anything that needs the actual numeric content (factor values, full rate rows, full exclusion text). Call `get_filing_extracts` instead, narrowing `files` to just the one(s) you discovered here. Whitelist (same as `get_filing_extracts`): - `calculations.json` — example rate-calculation walk-throughs. - `coverages.json` — coverage definitions (perils, limits, applicability). - `deductibles.json` — deductible options + factors. - `discounts.json` — discount / surcharge schedules. - `endorsements.json` — optional endorsements / riders. - `examples.json` — worked policyholder rating examples. - `exclusions.json` — coverage exclusions + the conditions they apply to. - `extraction_summary.json` — structured filing-overview fields. - `final_rating_calculation.json` — canonical rating expression. - `forms.json` — policy form numbers + types. - `rates_data.json` — base rates + rate-table headers. - `underwriting_guidelines.json` — eligibility / UW rules. Per item the tool returns `{ name, source_page? }`. The item name is picked from whichever identifying field exists (`name` → `form_number` → `id` → `key` → `code` → `coverage` → `label` → `title`). `source_page` is the page in the source PDF where the item was extracted from, when the pipeline recorded one. `rates_data.json` items additionally carry `source_file` — the source PDF the rate table lives in — when the filing has a single source PDF. Multi-source filings get `source_file_note` flagging the limit (per-item `source_file` on non-rate extracts needs a pipeline-side change, deferred). Args: `serff` (required), `files` (optional — pass a subset of the whitelist to narrow; omit for all 12). Returns: `{ serff, files: { "<name>": { file_name, filing_ref?, confidence?, sections: { "<key>": { count, items: [...] } }, total_items } }, count, skipped }`.

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.

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.

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, meta}`. Default `topK=10`, max 50. Excerpt is the first 800 chars of the matching summary.

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 the 2026 corpus is covered, prior years are backfilling. **How to combine**: - "Personal auto filings in California whose indicated rate exceeds selected by 5+ points" → `search_filings` (state=CA, product_type="Personal Auto", filing_type="Rate") to scope a candidate set, then this tool over the candidates' memos. - "Carriers citing severity-driven rate need in 2025" → this tool first; `get_filing_summary` on the top hits to read in full. Returns top-K hits, each with `{serff, similarity, excerpt, meta}`. Default `topK=10`, max 50. Excerpt is the first 800 chars of the matching memo.

Returns the structured-data JSON artefacts the pipeline extracted from a filing's source PDFs. Use this when the question is about **rating mechanics, data tables, risk curves, calculation steps, or coverage / form definitions** — anything where the narrative summary isn't enough and the LLM needs the actual structured rows. Whitelist (and what each contains): - `calculations.json` — step-by-step rate calculation walk-through (base rate, factor application, final premium). One entry per documented example calculation. - `coverages.json` — coverage definitions: which perils / lines / risk types the filing addresses, with limits and applicability. - `deductibles.json` — deductible options offered, dollar amounts, and any peril-specific rules. - `discounts.json` — available discounts / surcharges, eligibility criteria, and the corresponding multiplicative factors. - `endorsements.json` — optional endorsements / riders attached to the filing. - `examples.json` — worked policyholder examples (sample insureds with calculated premiums). - `exclusions.json` — coverage exclusions and conditions under which they apply. - `extraction_summary.json` — structured machine-readable form of the same content `get_filing_summary` returns as Markdown; useful when you want filing-type / what-this-filing-does fields as JSON rather than prose. - `final_rating_calculation.json` — the canonical rating expression / equation the filing prescribes (base × factor1 × factor2 …). - `forms.json` — policy form numbers, edition dates, and the form types associated with the filing. - `rates_data.json` — the rate tables themselves: rows of (segment / cell / factor) values. **The biggest file by far** — can be hundreds of thousands of rows for territory-detailed filings. See truncation below. - `underwriting_guidelines.json` — eligibility and underwriting rules (e.g. credit-tier bands, prior-loss caps). **Truncation**: any returned file whose JSON contains an array longer than 100 rows is truncated to the first 100 rows. The truncated file gets a `_truncated` envelope describing the original total. For a lighter table-of-contents view (counts, item names, source pages — no payloads) call `get_filing_extract_meta` instead; it's the right surface for "what's in this filing" questions. `rates_data.json` is the common case where truncation fires. Args: `serff` (required), `files` (optional array — narrows the response to a subset of the whitelist; pass empty / omit for everything). Returns: `{ serff, files: { "<name>": <parsed json> | { content, _truncated } }, count, skipped, truncated }`.

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.

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.

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).

**Scope warning — read before reaching for this tool.** The products corpus is a curated subset of filings, not the canonical breadth. Many filings are absent by design: bureau-only rows, withdrawals, correspondences, prior revisions (collapsed into the latest), and any filing the build pipeline hasn't classified as a substantive programme. For *"what filings exist"*, *"what carriers have filed"*, *"is carrier X in state Y"* questions — use `search_filings`. Reach for `search_products` only when the question is explicitly about programmes, lineage clusters, latest-revision picks, or adoption-source labels. Search the **products** corpus by carrier, state, LOB, year-range, pricing-lineage classification (`adoption_sources`), and chain shape. Products are programme histories — each row is one carrier programme defined by its leaf filing plus an ordered chain of predecessor SERFFs back to a root. By default, returns ONE row per (`company_name`, `state`, `lob`) lineage cluster — the latest revision by `leaf_filing_date`. Pass `all_revisions=true` to get every row including prior revisions of the same programme. Filters AND together. Defaults: `limit=25` capped at 100, ordered by `leaf_filing_date` DESC. `total` is the full predicate-matching count, independent of `limit`/`offset`. Common patterns: - "Full bureau workers-comp programmes in CA" → `state="CA"`, `lob="WORKERS COMPENSATION"`, `adoption_sources_any=["bureau"]`. - "Proprietary commercial-auto programmes 2024+" → `lob="AUTO"`, `leaf_year_from=2024`, `adoption_sources_any=["proprietary"]`. - "Me-too programmes Progressive's chain feeds" → `adoption_sources_any=["me_too","bureau_forms_only"]` (returns either), `company_name="Progressive"`. - "Substantive new-program leaves" → `leaf_likely_new=true`. These are programmes whose own filing carries the full rate manual (high-confidence price-ables). - "Strong-evidence chains" → `chain_evidence_min=0.7` (cosine of leaf vs. immediate parent chunks). `adoption_sources` valid values: `bureau` (full bureau adoption — loss costs + LCM), `me_too` (full adoption of another carrier's programme), `proprietary` (carrier owns the rates), `bureau_forms_only` (modifier — bureau forms with own/me-too rates). Use `adoption_sources_any` to match products whose array contains ANY of the listed values. Each row returns a lite shape — product identity, leaf and root SERFFs, chain depth, adoption_sources, leaf_likely_new, chain_evidence_score. For the full row (full chain expansion + related siblings) follow up with `get_product`.

Returns the full record for a single product — by `product_id` (uuid) OR `leaf_serff`. Each call expands the predecessor chain into a list of {position, serff, filing} where each filing is the slim metadata (state, year, carrier, product, filing type, status, date). Saves the round-trip you'd otherwise need (`search_products` → `get_filing_summary` × N). Returns the substantive-leaf signals (`leaf_likely_new`, `leaf_file_bytes`, `leaf_embed_bytes`), the chain evidence score (`chain_evidence_score`), the pricing-lineage label (`adoption_sources`), and the array of sibling product ids (`related_product_ids`) sharing a bureau/me-too source. Pair with `get_product_siblings` to resolve those ids into full sibling rows in one call. Pass either argument — not both. Returns `{ error: ... }` if neither provided, on malformed UUID/SERFF, or when no product matches.

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.

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 sibling products of a given product — other products whose chain shares a bureau filing (ISO / AAIS / NCCI / WCRT / WCRB / SURE) or a cross-carrier predecessor with the seed product. The shared filing is the "source" both products adopted from — multiple carriers' parallel adoptions of the same ISO programme, or multiple successors of a single me-too source. Resolves the seed's stored `related_product_ids` array into slim sibling rows (product identity, leaf, LOB, state, adoption_sources, depth, root). Cheaper than a full `search_products` predicate when you already have a known product and want its peers. Use to: - find every product riding on a specific ISO loss-cost filing (start from one bureau-adopting product, get all the others adopting the same root), - spot programmes that look proprietary but actually share a cross-carrier source, - explore me-too clusters around a single source filing. Pass `product_id` (uuid) OR `leaf_serff`. Returns `{ siblings: [], count: 0 }` when the product has no siblings — not an error.

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 prior revisions of a product — other products in the same lineage cluster (same `company_name`, `state`, `lob`) with an older `leaf_filing_date`. Distinct from `get_product_siblings`, which returns peers sharing a bureau / cross-carrier source. Use to answer "how has this programme evolved?" — walk back through each revision in chronological order. Returns slim rows (product identity, leaf, adoption_sources, depth, root) ordered oldest → newest. If the seed product is missing any of the cluster-key fields (`company_name` / `state` / `lob` / `leaf_filing_date`), returns `ancestors: []` with an explanatory `note` field — not an error. Pass `product_id` (uuid) OR `leaf_serff`. Returns `{ ancestors: [], count: 0 }` when no prior revision exists — not an error.