Skip to main content
Glama

ca-rate-filings

by ai.serff

Semantic Search — Regulatory Position (Objections + Filer Contacts)

search_correspondence_embeds
Read-onlyIdempotent

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)

  • .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 for resolved)

  • year / year_from / year_to / date_from / date_to — filing-year and filing-date windows

  • state, naic, product_type, filing_type, predecessor_prefix — carrier + programme scope

For "which filings did jane.reviewer@insurance.ca.gov touch this quarter", use list_email_workload instead — it aggregates and is designed for caseload views.

Cost: one query-embedding call + one indexed Postgres lookup. Bounded, cheap, fast.

Right surface for:

  • "What did CDI push back on in this filing?" — pass serff to scope; get the reviewer's own words.

  • "Show me carrier responses to territory-factor objections" — semantic search, no scope; excerpts read as regulator-carrier dialogue.

  • "Find filings where CDI questioned reinsurance costs" — use the semantic query alone.

  • "Every objection where jane.reviewer@insurance.ca.gov was on the exchange" — pass email, optionally combined with the semantic query.

  • "All filings whose objection thread involves anyone at Farmers" — pass email_domain=farmersinsurance.com.

Right combination with other tools: pair with get_filing_correspondence to pull the full ordered thread for one filing once search surfaces a hit worth reading end-to-end.

Wrong surface for:

  • Filing-content questions (rate manuals, forms, actuarial memos) — use search_summary_embeds or search_filing_embeds.

  • "Which filings had ANY objections at all" — for presence-only, prefer get_filing_correspondence with a file_count > 0 check per SERFF.

Facet coverage (as of 2026): most objection letters do not embed email addresses in the body — CDI reviewers sign off with a name + division, not a mailbox. So email / email_domain scopes will match a minority of chunks even for filings that had a full objection round. Semantic search is the dominant surface here; the email facets are a bonus filter, not the primary shape.

Returns top-K chunks with {serff, source_file, chunk_index, similarity, excerpt, emails, email_domains, page_date, meta}. Default topK=10, max 50. Excerpt is the first 1200 chars of the matching chunk.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
naicNoExact NAIC carrier identifier (5-digit string). Restricts to that carrier.
topKNoNumber of top hits to return. Defaults to 10; capped at 50.
yearNoExact filing year. Mutually exclusive with year_from/year_to.
emailNoOptional exact-match email filter. Only chunks mentioning this address are searched. Case-insensitive (lowercased on match). Sparse coverage — most objection letters do not embed email addresses in the body.
queryYesNatural-language query. Pass the user's question verbatim — short, specific (5-30 words) matches best. Embedded and cosine-compared against per-chunk correspondence embeddings.
serffNoOptional SERFF id to scope the semantic search to a single filing's correspondence thread (shape PREFIX-IDENTIFIER). Useful for "what did CDI push back on in this filing?" questions.
stateNoTwo-letter US state code, uppercase. Corpus currently covers CA only.
date_toNoUpper bound on filing date (ISO YYYY-MM-DD).
year_toNoUpper bound on filing year, inclusive.
date_fromNoLower bound on filing date (ISO YYYY-MM-DD).
year_fromNoLower bound on filing year, inclusive.
filing_typeNoWildcard match on filing type ("Rate", "Rule", "Form", "Withdrawal", etc.). Substring match.
email_domainNoOptional exact-match email-domain filter (e.g. "insurance.ca.gov", "farmersinsurance.com"). Only chunks mentioning any address on that domain are searched. Case-insensitive.
product_typeNoWildcard match on product type ("Personal Auto", "Homeowners", "Commercial Auto", "Workers Compensation", etc.). Substring match.
filing_statusNoWildcard match on filing status ("Pending", "Closed - Approved", "Closed - Withdrawn", etc.). Substring match — use to distinguish live vs closed objections.
predecessor_prefixNoBureau / org SERFF prefix ("ISOF", "NCCI", "AAIS", "MSO").

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, idempotentHint=true, and the description adds substantial context beyond them: the pure vector-search mechanics, that excerpts ARE quotable source text, cost characteristics ('one query-embedding call + one indexed Postgres lookup'), the topK cap, and the critical sparse-coverage caveat that email/email_domain facets match only a minority of chunks. This materially shapes how an agent uses the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and usage, and well-organized with bold headers and distinct Right/Wrong tool sections. It is long, but every section carries decision-relevant information — routing, facet semantics, coverage caveats, and concrete example queries — so the length is earned rather than padded. Slightly over-built for a search tool, hence 4 not 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description correctly carries the burden of explaining return values: 'Returns top-K chunks with {serff, source_file, chunk_index, similarity, excerpt, emails, email_domains, page_date, meta}. Default topK=10, max 50. Excerpt is the first 1200 chars.' For a 16-param tool with heavy sibling differentiation needs, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains how facets combine ('all combine with AND on top of the semantic ranking'), gives the sparse-coverage caveat for email filters, and specifies query semantics ('Pass the user's question verbatim — short, specific 5-30 words matches best'). Does not fully restate every parameter, but adds meaning the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise statement of what the tool does — understand the REGULATORY POSITION of a filing — and immediately distinguishes it from siblings by naming exactly what it is not ('NOT to understand what the filing does or how it rates'). The verb+resource pair ('semantic search over correspondence_embeds') is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('Right tool for questions about the state's dialogue'), when-not-to-use ('Wrong tool for content questions'), and concrete alternatives — search_summary_embeds, search_actuarial_embeds, search_filing_embeds, list_email_workload, get_filing_correspondence — each with the condition that selects it. Even provides combination guidance for pairing with get_filing_correspondence for end-to-end thread reads.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ca-rate-filings toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.5/5.0
Disambiguation4/5

The get_filing_* family has distinct purposes, though get_filing_lineage and get_filing_references could be confused without the detailed descriptions. The search_* tools are clearly separated by embedding surface, and dossier/composite vs single-filing retrievals are explicitly differentiated.

Naming Consistency5/5

All tools follow a consistent verb_noun snake_case pattern with clear prefixes: get_filing_*, search_*, list_*, and mcp_*. No style mixing or vague generic verbs.

Tool Count4/5

At 16 tools, this sits at the upper edge of the ideal range. Each tool earns its place, though get_filing_dossier could have been a client-side composition of the other get_filing_* calls rather than a separate tool.

Completeness5/5

The domain (retrieving CA rate filings) is covered end to end: structured and semantic search across multiple granularities, filing summaries, correspondence threads, actuarial numerics, lineage, source file listing/download, and reviewer caseload. The read-only nature of the domain means no create/update operations are needed, and every retrieval path leads to a terminal artifact.

Resources