ca-rate-filings

Semantic Search — Filing Summaries

search_summary_embeds

Read-onlyIdempotent

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 " — when you need to discover filings by content rather than by structured metadata.
"Filings citing trend data on " — 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.

Input Schema

TableJSON Schema

Name	Required	Description
`naic`	No	Exact NAIC carrier identifier (5-digit string). Restricts the cosine search to that carrier.
`topK`	No	Number of top filings to return. Defaults to 10; capped at 50. The result will contain at most this many rows; if filters narrow the candidate set below topK you get what's there, no silent fallback.
`year`	No	Exact filing year. Mutually exclusive with year_from/year_to.
`query`	Yes	Natural-language query. Pass the user's question verbatim when you can — short, specific queries (5-30 words) match best. The query is embedded and cosine-compared against per-filing summary embeddings.
`serff`	No	Optional SERFF id to scope the search to a single filing's summary embedding (shape PREFIX-IDENTIFIER). Each filing has at most one summary embedding, so topK is effectively 1 when serff is set.
`state`	No	Two-letter US state code, uppercase. Corpus currently covers CA only.
`date_to`	No	Upper bound on filing date (ISO YYYY-MM-DD).
`year_to`	No	Upper bound on filing year, inclusive.
`date_from`	No	Lower bound on filing date (ISO YYYY-MM-DD).
`year_from`	No	Lower bound on filing year, inclusive.
`filing_type`	No	Wildcard match on filing type ("Rate", "Rule", "Form", "Withdrawal", etc.). Substring match.
`product_type`	No	Wildcard match on product type ("Personal Auto", "Homeowners", "Commercial Auto", "Workers Compensation", etc.). Substring match — "Auto" matches both Personal and Commercial Auto.
`predecessor_prefix`	No	Bureau / org SERFF prefix ("ISOF", "NCCI", "AAIS", "MSO"). Restricts to filings carriers actually adopted into a programme.

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false. The description adds key behavioral details: it's a pure vector search with bounded cost, no LLM planning, defaults topK=10 with max 50, and clarifies behavior when filters narrow candidate set (no silent fallback). This provides substantial context beyond annotations.

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?

The description is well-structured with sections, bullet points, and clear headings, front-loading the core purpose. While it is somewhat lengthy, every sentence adds valuable information for a tool with 13 parameters and multiple use cases. Minor verbosity prevents a 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?

Given the tool's complexity (13 parameters, no output schema), the description is remarkably complete. It specifies return fields (serff, similarity, excerpt, meta), excerpt length (800 chars), filtering behavior, combination strategies, and caveats like corpus coverage. No obvious gaps remain.

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

Parameters5/5

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

All 13 parameters are fully described in the schema, but the description adds significant meaning beyond the schema. For example, it advises short specific queries for best matches, explains topK behavior with filters, notes that state corpus currently covers CA only, and includes substring match examples for product_type. This greatly aids correct parameter usage.

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 clearly states 'Pure vector search over per-filing extraction-summary embeddings' and explains the return of semantically closest filings with metadata. It explicitly distinguishes from sibling tools like search_actuarial_embeds and search_filings, making the purpose 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?

The description provides explicit when-to-use (content questions about what filing is about) and when-not-to-use (actuarial-shape, concrete filters, SERFF already in hand) guidelines. It also offers combination strategies with other tools, such as first using search_filings for candidate sets.

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 tools Inspect

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

Need Help?