Skip to main content
Glama

ca-rate-filings

by ai.serff

Semantic Search — Filing Body

search_filing_embeds
Read-onlyIdempotent

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
naicNoExact NAIC carrier identifier (5-digit string).
topKNoNumber of top hits to return. Defaults to 10; capped at 50. If filters narrow the candidate set below topK you get what's there, no silent fallback to cross-filing matches.
yearNoExact filing year. Mutually exclusive with year_from/year_to.
queryYesNatural-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-chunk body embeddings.
serffNoOptional SERFF id to scope the chunk search to a single filing (shape PREFIX-IDENTIFIER, e.g. "REGU-134742228"). Use this when you already know which filing you want to read semantically — e.g. "find the territory factor table in REGU-134742228".
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.
aggregateNoWhen true (default), collapse to top-K filings by best-chunk similarity. When false, return top-K raw chunks (may include multiple chunks from the same filing). Ignored (forced to false) when `serff` is set — scoping to one filing always returns raw chunks.
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", etc.). Substring match.
product_typeNoWildcard match on product type. Substring match — "Auto" matches Personal Auto and Commercial Auto.
predecessor_prefixNoBureau / org SERFF prefix ("ISOF", "NCCI", "AAIS", "MSO").

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already indicate readOnly and idempotent hints. The description adds valuable behavioral context (e.g., cost breakdown, aggregate behavior when serff is set, no LLM involvement) beyond the 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 lengthy but well-structured with sections and bullet points. It front-loads core concepts and every sentence adds value, though slight brevity could improve conciseness.

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?

Completely covers use cases, alternatives, and behavioral traits. Includes corpus statistics, explains return format, and addresses edge cases like scoping with serff. No output schema but description compensates adequately.

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 parameters are well-documented. The description adds extra context for key parameters like aggregate and serff, enhancing understanding beyond the schema.

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 it is a 'pure vector search over per-chunk full-document embeddings' for granular semantic search, and explicitly distinguishes it from sibling tools like search_summary_embeds and search_filings.

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?

Provides explicit 'Right surface for' and 'Wrong surface for' sections, detailing when to use this tool vs. alternatives, and includes guidance on aggregate and serff parameters.

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