Skip to main content
Glama

ca-rate-filings

by ai.serff

Semantic Search — Actuarial Memos

search_actuarial_embeds
Read-onlyIdempotent

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
naicNoExact NAIC carrier identifier (5-digit string). Restricts the cosine search to that carrier.
topKNoNumber of top filings to return. Defaults to 10; capped at 50.
yearNoExact filing year. Mutually exclusive with year_from/year_to.
queryYesNatural-language query. Pass the user's actuarial question verbatim — short, specific queries (5-30 words) match best. The query is embedded and cosine-compared against per-filing actuarial-memo embeddings.
serffNoOptional SERFF id to scope the search to a single filing's actuarial memo (shape PREFIX-IDENTIFIER). Each filing has at most one memo embedding, so topK is effectively 1 when serff is set.
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.
product_typeNoWildcard match on product type ("Personal Auto", "Homeowners", "Commercial Auto", "Workers Compensation", etc.). Substring match — "Auto" matches both Personal and Commercial Auto.
predecessor_prefixNoBureau / org SERFF prefix ("ISOF", "NCCI", "AAIS", "MSO"). Restricts to filings carriers actually adopted into a programme.

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnlyHint and idempotentHint, so the bar is lower. The description still adds meaningful behavior beyond annotations: cost model, no LLM planning/composition, coverage caveats about 2026 backfill, cosine similarity semantics, and the first-800-chars excerpt limit. This is rich, non-contradictory context.

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

Conciseness5/5

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

The description is long but every section earns its place: purpose and cost are front-loaded, sibling differentiation is explicit, and the bullet lists are dense examples rather than filler. Headings make the structure scannable for an agent.

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?

With no output schema, the description supplies the return shape explicitly: top-K hits with {serff, similarity, excerpt, meta}. It also covers coverage limitations, how to combine with search_filings and get_filing_summary, and when not to use the tool. Given the 13-parameter complexity and rich sibling set, nothing essential is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3 even without extra parameter detail. The description does reinforce query behavior and topK defaults, but most of those facts are already present in the input schema (e.g., topK capped at 50, serff singleton, CA-only state). It adds routing context rather than new parameter-level meaning.

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 first sentence names the exact resource and operation: pure vector search over per-filing actuarial-memorandum embeddings. It explicitly contrasts with search_summary_embeds and search_filing_embeds, and clarifies this tool is for actuarial numerics rather than content or filtering.

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?

The description has dedicated 'right tool', 'wrong surface', and 'how to combine' sections. It lists concrete actuarial topics that should use this tool, explicitly routes content queries to search_summary_embeds and filter queries to search_filings, and gives worked combination examples. An agent can not only choose this tool but know when to route elsewhere.

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