ca-rate-filings
Server Details
Natural-language search over California's public insurance rate, rule & form filings.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.7/5 across 16 of 16 tools scored.
Each tool has a clearly distinct purpose: meta vs full extracts, different search modalities (by content, by actuarial numerics, by structured filters), lineage vs references, etc. Overlap is minimal and well-documented, making it easy for an agent to select the right tool.
All tools follow a consistent verb_noun pattern (e.g., get_filing_summary, search_filings, list_filing_source_files) using snake_case. The naming is predictable and unambiguous, with no mixing of conventions.
With 16 tools, the server strikes an excellent balance between comprehensiveness and manageability. Each tool earns its place, covering metadata retrieval, full extracts, search (structured and semantic), product lineage, and source file access without unnecessary redundancy.
The tool set provides end-to-end coverage for rate filing analysis: discovery (search), overview (summary, meta), detailed data (extracts), lineage (references, product ancestors/siblings), and source access. No obvious gaps are apparent for the server's stated purpose.
Available Tools
16 toolsget_filing_extract_metaGet Filing Extract Meta (Pro)ARead-onlyIdempotentInspect
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_extractsinstead, narrowingfilesto 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 }.
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Optional subset of whitelist file names to summarise. Omit or pass empty for all 12. | |
| serff | Yes | Canonical SERFF id, shape PREFIX-IDENTIFIER (e.g. "AAIC-134567890"). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint=true and idempotentHint=true; description confirms it's a low-cost meta call. Adds behavioral details: return format per item (name, source_page), special handling for rates_data.json (source_file or source_file_note), and item name selection logic. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with bolded key points, bullet lists, and sections. Although lengthy, every sentence adds value (whitelist, return format, usage guidance). Slightly verbose in examples but efficient overall. Front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully details the return structure (serff, files dict with sections, items, counts). Covers edge cases (single vs multi-source PDF for rates, item naming fallback fields). Compensates for missing output schema completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters described). Description adds value beyond schema: explains serff shape 'PREFIX-IDENTIFIER' and gives example, clarifies files is a whitelist subset with enumeration of all 12 file types, and notes omitting files returns all. This justifies above baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'what's in each extracted artefact' (sections, items, pages) without returning bulky data. It distinguishes from the sibling get_filing_extracts, which is for pulling actual content. Specific verb 'list' and resource 'extracted artefact' with scope 'meta' make purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call this FIRST before get_filing_extracts, provides concrete user query examples (e.g., 'What forms does this filing include?'), and states when NOT to use it (when actual numeric content is needed). Also mentions cost advantage, giving clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_filing_extractsGet Filing Extracts (Pro)ARead-onlyIdempotentInspect
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 contentget_filing_summaryreturns 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 }.
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Optional subset of whitelist file names to return (e.g. ["rates_data.json", "calculations.json"]). Omit or pass empty for the full whitelist. | |
| serff | Yes | Canonical SERFF id, shape PREFIX-IDENTIFIER (e.g. "AAIC-134567890"). Validated against /^[A-Z]{3,5}-[A-Z0-9]{7,15}$/. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide read-only and idempotent hints. Description adds crucial truncation behavior (100-row limit, `_truncated` envelope) and notes `rates_data.json` as common truncation case, without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purposeful sections: purpose, whitelist with descriptions, truncation note, and usage guidance. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity of 14 whitelist files, truncation, and optional parameter, description covers return format, truncation details, and points to sibling for lighter needs. No output schema exists, so return value explanation is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description adds significant value by listing valid file names for the `files` parameter and explaining behavior when omitted, going beyond basic schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'Returns the structured-data JSON artefacts' and provides a detailed whitelist, distinguishing from sibling `get_filing_extract_meta` by noting it returns full data vs. table-of-contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly states when to use (questions about rating mechanics, data tables, etc.) and when not to use (for lighter view, use `get_filing_extract_meta`), providing explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_filing_lineageGet Filing Lineage (Pro)ARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| serff | Yes | Canonical SERFF id, shape PREFIX-IDENTIFIER (e.g. "AAIC-134567890"). Either the leaf or a predecessor — the chain is returned regardless. Validated against /^[A-Z]{3,5}-[A-Z0-9]{7,15}$/; invalid values return an error envelope. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds further behavioral context: the chain includes ordered predecessors, position, role, and lite filing record; it walks back from any SERFF in the chain; and returns error for unresolved ids. While not covering all edge cases (e.g., rate limits), it provides significant value 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured into four paragraphs, each serving a distinct purpose: output description, sibling differentiation, behavior/error handling, and pairing suggestion. No unnecessary sentences, but could be slightly more compact without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single parameter, no output schema, and annotations are present, the description is comprehensive. It explains inputs, outputs, behavior, error cases, and usage context. It pairs well with sibling tools and context signals, leaving no significant gaps for an AI agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the single parameter `serff` with description and validation regex (100% coverage). The description reinforces that either leaf or predecessor works and mentions the regex pattern, adding context beyond the schema. This justifies a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state the tool returns a reconciled lineage chain for a SERFF id, including leaf filing and predecessors. It explicitly distinguishes itself from the sibling tool `get_filing_references` by contrasting canonical vs carrier-stated lineage, meeting the criteria of specific verb+resource and sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs `get_filing_references`, includes error handling for unresolved SERFF ids, and suggests pairing with `search_filings` using `predecessor_prefix`. This covers when, when-not, and alternatives comprehensively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_filing_referencesGet Filing ReferencesARead-onlyIdempotentInspect
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).
| Name | Required | Description | Default |
|---|---|---|---|
| serff | Yes | Canonical SERFF id, shape PREFIX-IDENTIFIER (e.g. "AAIC-134567890"). Validated against /^[A-Z]{3,5}-[A-Z0-9]{7,15}$/; invalid values return an error envelope. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnly and idempotent. Description adds that references are extracted from inside the PDF and that missing records return an error envelope. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three well-organized paragraphs: definition, differentiation from sibling, and usage/error info. Every sentence adds value; front-loaded with core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with full schema coverage, the description explains return fields (SERFF id, NAIC, etc.) and error case, making it fully self-contained without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds validation pattern and error behavior for the serff parameter. This exceeds baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns predecessor, superseded, and companion filings cited by the filing itself. It distinguishes from the sibling get_filing_lineage by explaining the difference in scope (carrier-stated vs. reconciled chain).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly contrasts with get_filing_lineage, noting when they may diverge and that divergence is a signal. Provides specific use cases: 'what does this filing claim to replace?' and 'which bureau filing did this carrier adopt?'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_filing_source_file_linkGet Filing Source File Link (Pro)ARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| serff | Yes | Canonical SERFF id, shape PREFIX-IDENTIFIER (e.g. "REGU-134742228"). | |
| file_name | Yes | Basename of a file present in this SERFF's source-files directory (the exact set returned by `list_filing_source_files`). No slashes, no path traversal — pure basename. | |
| ttl_seconds | No | Signed-URL lifetime in seconds. Default 900 (15 minutes). Capped at 3600 (1 hour). Shorter is preferred — the link is for the human to click immediately, not for long-term storage. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: short-lived URL, bypasses Cloud Run, dynamic whitelist, and intended for human clicks. Annotations confirm read-only nature, no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with early key information, but contains redundant warnings about not fetching the URL. Slightly verbose but still clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully specifies return fields (serff, file_name, url, expires_at, ttl_seconds, notice) and their intended use, making the tool's behavior complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by explaining serff shape, file_name basename constraint, and ttl_seconds default/cap, exceeding schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a short-lived V4-signed GCS URL for a single source file, distinguishes from siblings like list_filing_source_files, and specifies the supported file types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to pair with list_filing_source_files, warns not to fetch the URL oneself, and advises including expires_at timestamp for the user. Provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_filing_summaryGet Filing SummaryARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| serff | Yes | Canonical SERFF id, shape PREFIX-IDENTIFIER (e.g. "AAIC-134567890"). Validated against /^[A-Z]{3,5}-[A-Z0-9]{7,15}$/; invalid values return an error envelope. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, idempotentHint, and openWorldHint; the description aligns by describing a read-only retrieval. It adds behavioral details: returns error if filing not classified, page citation format, and typical size (few KB vs raw source). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (multiple sentences but no fluff), front-loads the core purpose, and uses formatting (bold, parentheses) to structure key details. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one param, no output schema) but the description covers return content, error handling, and size context. With annotations covering safety and idempotency, the agent has sufficient information to use the tool correctly. A minor gap is the lack of explicit return type structure, but the narrative description compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'serff' is fully described in the input schema with format validation and error envelope. The description reiterates some of this but adds no significant new meaning; with 100% schema coverage, baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'returns an actuarial narrative summary' for a single SERFF id, listing specific sections returned (Filing Type, 'What This Filing Does', Description, references). It distinguishes from siblings by positioning as the 'fastest route' and referencing alternative tools for troubleshooting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (having a SERFF id, wanting to understand changes) and when not to (if error, do not retry; instead use list_filing_source_files and mcp_health). It provides concrete triage instructions, making the decision clear for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_productGet Product Detail (Pro)ARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| leaf_serff | No | Leaf-filing SERFF id, shape PREFIX-IDENTIFIER. Mutually exclusive with `product_id`. | |
| product_id | No | Canonical product UUID (e.g. "00006cf7-ae2b-4eb4-b774-2fe66debd40d"). Mutually exclusive with `leaf_serff` — pass one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds behavioral details: expands predecessor chain, returns specific fields (leaf signals, chain evidence score, adoption_sources, etc.), and error responses. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is front-loaded with the main purpose. Sentences are well-structured and each adds value (e.g., round-trip savings, specific fields). Slightly verbose but still efficient. Could be trimmed slightly, but overall good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description fully explains return values (leaf signals, chain evidence score, adoption_sources, related_product_ids). Also covers error handling and pairing suggestion. Comprehensive for a read-only product detail tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). Description adds value by explaining the shape of leaf_serff ('PREFIX-IDENTIFIER'), giving an example UUID for product_id, and emphasizing mutual exclusivity. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Returns'), the resource ('full record for a single product'), and the two identifiers (product_id or leaf_serff). It differentiates from siblings by mentioning the expanded predecessor chain and specific output fields (leaf signals, chain evidence score).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to pass either argument but not both and notes error conditions. Mentions avoiding a round-trip (search_products -> get_filing_summary X N) which gives usage context. Lacks explicit 'when not to use' but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_product_ancestorsGet Product Ancestors (Pro)ARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| leaf_serff | No | Leaf-filing SERFF id. Mutually exclusive with `product_id`. | |
| product_id | No | Canonical product UUID. Mutually exclusive with `leaf_serff` — pass one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds detail: ordering oldest→newest, empty array with note for missing cluster fields, empty result for no prior revision. Annotations already cover read-only and idempotency, making this strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose, use case, return format, edge cases, parameter instructions. No redundant sentences, front-loaded with key info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: input parameters, return format, ordering, edge cases, error handling. Adequate even without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds explanation of each parameter (UUID leaf SERFF) and reinforces mutual exclusivity, providing additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns prior revisions of a product in a lineage cluster, defines cluster fields, and explicitly distinguishes from sibling tool get_product_siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a use case ('how has this programme evolved?') and contrasts with get_product_siblings, but lacks explicit when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_product_siblingsGet Product Siblings (Pro)ARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| leaf_serff | No | Leaf-filing SERFF id. Mutually exclusive with `product_id`. | |
| product_id | No | Canonical product UUID. Mutually exclusive with `leaf_serff` — pass one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds behavioral context beyond annotations: it explains the resolution of stored related_product_ids, lists output fields, notes cheaper than search_products, and specifies return format { siblings: [], count: 0 } for no-sibling case. Consistent with read-only and idempotent annotations, no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured and front-loaded with purpose. Each paragraph serves a clear role. A bit lengthy due to conceptual explanation, but appropriate for the tool's complexity. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters, no output schema, and presence of annotations, the description covers return shape, non-error condition, and resolution logic. Adequate for the complexity. Could optionally mention pagination, but not necessary for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds meaningful mutual exclusivity explanation and reinforces that only one of product_id or leaf_serff should be passed. Provides slightly improved clarity over schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Returns the sibling products of a given product' and explains the concept of siblings via shared bureau filing or cross-carrier predecessor. It distinguishes itself from the sibling tool 'search_products' by noting it is cheaper when a known product is available.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases with 'Use to:' bullet points, specifies parameter mutual exclusivity ('Pass product_id OR leaf_serff'), and explains that returning empty is not an error. Provides clear guidance on when to use this tool vs alternatives like search_products.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_filing_source_filesList Filing Source Files (Pro)ARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| serff | Yes | Canonical SERFF id, shape PREFIX-IDENTIFIER (e.g. "AAIC-134567890"). Validated against /^[A-Z]{3,5}-[A-Z0-9]{7,15}$/; invalid values return an error envelope. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's mention of 'Returns metadata only' and error handling adds useful behavioral detail without contradiction. It does not discuss authorization or rate limits, but the annotations cover the safety profile sufficiently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear first sentence and bullet points for usage. It is efficient without being overly terse. Minor improvement could be reducing redundancy, but it remains well-organized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one parameter and no output schema, the description covers the return type (metadata) and error case. It lacks mention of pagination or ordering, but given the low complexity, it is mostly complete. The pairing suggestion adds context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the serff parameter well (shape, validation). The tool description does not add extra parameter-level information beyond what is in the schema. With 100% schema coverage, a baseline of 3 is appropriate; the description does not degrade but also does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists source files (PDFs, XLS, DOC, ZIP) for a SERFF id, using specific verbs and nouns. It distinguishes itself from sibling tool get_filing_source_file_link by noting the pairing: 'list names here, mint a link there.' The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides three explicit use cases ('triage a filing', 'discover the XLSM rater / rate manual PDF', 'confirm which artefacts a filing actually shipped') and suggests pairing with get_filing_source_file_link. It gives clear context for when to use this tool ator alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mcp_healthMCP Server HealthARead-onlyIdempotentInspect
Diagnostic snapshot of the deployed MCP server: build identifier, server_version (1.0. 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint, so safe behavior is clear. Description adds context about return fields and their meanings, which goes beyond annotations. Could mention if there are any rate limits or costs, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and fields, then usage scenarios. It could be slightly shorter, but every sentence adds value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description compensates by detailing the return fields (build identifier, server_version, boot time, advertised tool names, hash, corpus_updated_at) and their purpose. This is comprehensive for a health endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are needed; the description handles this naturally by not mentioning any. The tool has zero parameters, so the description adds no confusion and is consistent with the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a diagnostic snapshot of the deployed MCP server and lists specific fields like build identifier, server_version, boot time, advertised tool names, hash, and corpus_updated_at. It distinguishes itself from sibling tools which focus on filings and products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends calling this tool first when suspecting stale tool lists or detecting code/data changes. Provides concrete comparisons: tools_advertised vs client list, server_version for code, corpus_updated_at for data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_actuarial_embedsSemantic Search — Actuarial MemosARead-onlyIdempotentInspect
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_embedsfor 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_summaryon 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.
| Name | Required | Description | Default |
|---|---|---|---|
| topK | No | Number of top filings to return. Defaults to 10; capped at 50. | |
| query | Yes | Natural-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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint; description adds cost characteristics (one query-embedding call + indexed Postgres lookup, bounded cheap fast), return format (top-K hits with similarity, excerpt, meta), excerpt length (800 chars), and coverage limitations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Relatively lengthy but well-structured with sections (cost, when to use, wrong surfaces, how to combine, returns). Front-loaded with key purpose. Every section adds value, but could be slightly more concise overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive description covering embedding source, search mechanism, coverage notes, return fields, and integration with other tools. No output schema but description explains return structure sufficiently. Handles all relevant context for this complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both query and topK described). Description adds valuable context: for query, recommends short specific queries (5-30 words) and pass verbatim; for topK, states default 10, max 50. Enhances usability beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly identify it as a semantic search over actuarial memos. It distinguishes itself from sibling tools like search_summary_embeds and search_filing_embeds by specifying the kind of content (actuarial numerics vs content description vs filing metadata).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool (questions about actuarial numerics like rate adequacy, loss trends, etc.) and when not to use it (content questions, concrete filters, filings without actuarial memos). Provides specific alternatives and examples of combining tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_filing_embedsSemantic Search — Filing Body (Pro)ARead-onlyIdempotentInspect
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
serffto 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.
| Name | Required | Description | Default |
|---|---|---|---|
| naic | No | Exact NAIC carrier identifier (5-digit string). | |
| topK | No | Number 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. | |
| 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-chunk body embeddings. | |
| serff | No | Optional 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". | |
| 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. | |
| aggregate | No | When 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_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", etc.). Substring match. | |
| product_type | No | Wildcard match on product type. Substring match — "Auto" matches Personal Auto and Commercial Auto. | |
| predecessor_prefix | No | Bureau / org SERFF prefix ("ISOF", "NCCI", "AAIS", "MSO"). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds cost details (one query-embedding call + indexed Postgres lookup), explains aggregate behavior, and describes what happens when filters narrow results below topK. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, bullet points, and code blocks for clarity. While a bit long, each sentence adds essential information or guidance, making it efficient for its complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters, no output schema, and high parameter count, the description fully explains return format (fields like serff, chunk_index, similarity, excerpt, meta), default and max topK, and behavior under various filters and aggregate settings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value beyond schema: e.g., query recommendation ('short, specific queries (5-30 words) match best'), year/year_from/year_to mutual exclusivity, and state coverage limit ('Corpus currently covers CA only').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs 'pure vector search over per-chunk full-document embeddings' and distinguishes itself from siblings by naming search_summary_embeds and search_filings, explaining their different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists when to use (e.g., 'find the exact passage discussing X') and when not to (e.g., filing-level questions, concrete-filter questions), with named alternatives such as search_summary_embeds and search_filings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_filingsSearch FilingsARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| naic | No | Exact match on the NAIC carrier identifier (5-digit string). Use when you know the specific carrier (e.g. "24260" = Progressive Direct). One filing always belongs to exactly one NAIC. | |
| year | No | Exact filing year (e.g. 2024). The corpus covers filings from 2005 onward; earlier years return no rows. Mutually exclusive with `year_from`/`year_to` — pick one form. | |
| limit | No | Max rows returned in this call. Defaults to 25; capped at 100. Pair with `offset` to page. Always check `total` in the response to decide whether you need more pages. | |
| state | No | Two-letter US state code, uppercase. The corpus currently covers California (`CA`) only — other state codes will return no rows until additional states are onboarded. One filing always belongs to exactly one state. | |
| offset | No | Row offset for pagination. Defaults to 0. Combined with the descending filing-date ordering, `offset=N` skips the most recent N filings matching the predicate. | |
| search | No | Free-text wildcard match across SERFF id, carrier name, and product name. Useful for "anything mentioning Progressive" or "filings whose product name contains 'condo'". Prefer the structured fields below — `naic`, `state`, `filing_type`, `product_type` — when you can; they are more precise and do not false-match on substrings. | |
| date_to | No | Upper bound on filing date as ISO date (YYYY-MM-DD). | |
| year_to | No | Upper bound on filing year, inclusive. | |
| date_from | No | Lower bound on filing date as ISO date (YYYY-MM-DD). Use for finer-grained windows than `year_from` allows. Compares against the date the carrier submitted the filing, not the rate effective date. | |
| year_from | No | Lower bound on filing year, inclusive. The corpus covers filings from 2005 onward. Pair with `year_to` for a range, or use alone for "everything since". | |
| filing_type | No | Wildcard match on filing type. Common values: "Rate", "Rule", "Rate/Rule", "Loss Cost / Rule", "Form", "Rate/Rule/Form", "Withdrawal", "Correspondence", "Adoption". Substring matches: `filing_type="Rule"` returns Rule, Rate/Rule, and Loss Cost / Rule. Substantive (rate-affecting) filings are typically Rate, Rule, Rate/Rule, Loss Cost / Rule, or Form combinations. | |
| product_type | No | Wildcard match on product type. Common values include "Personal Auto", "Homeowners", "Commercial Auto", "Workers Compensation", "Property", "Liability". Substring matches: `product_type="Auto"` returns Personal Auto and Commercial Auto. | |
| predecessor_prefix | No | Bureau or organisation SERFF prefix — common values: "ISOF" (ISO Services), "NCCI" (workers comp loss costs), "AAIS" (American Association of Insurance Services), "MSO" (Mutual Service Organisation). Returns filings carriers actually adopted into a programme — orphan bureau filings nobody picked up are excluded. Validated against /^[A-Z][A-Z0-9]{1,7}-?$/ (1-8 alphanumeric chars, trailing dash optional). Invalid input returns `{ error: ... }`. Case-insensitive on the way in. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent. Description adds: only fully read/classified filings returned, pagination with offset and total count, AND-filtering, predecessor_prefix validation with error, state limitation to CA. Rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose, return shape, behavior, examples, special cases. Somewhat lengthy but every sentence adds value. Front-loaded with key info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 optional params and no output schema, description covers all aspects: pagination, ordering, filtering, validation, data quality. Return shape described textually. Complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description adds value with examples (e.g., predecessor_prefix prefix patterns, wildcard behavior for filing_type and product_type, date vs year differentiation). Not redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it searches the SERFF filings corpus by multiple criteria and mentions return shape. Distinguishes from sibling get_filing_summary for follow-up details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context: use for initial search, follow with get_filing_summary for substance. Includes common examples and patterns. No explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_productsSearch Products (Pro)ARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| lob | No | Substring match on product LOB family (state_product_type → falls back to serff_product_type). Common values: "AUTO LIAB/PHYS DAMAGE", "WORKERS COMPENSATION", "OTHER LIABILITY", "MULTI-PERIL", "HOMEOWNERS MULTI-PERIL", "FIRE", "INLAND MARINE". `lob="AUTO"` returns all auto variants. | |
| depth | No | Exact chain depth (number of predecessors). depth=0 means a standalone leaf with no chain. | |
| limit | No | Max rows returned. Defaults to 25, capped at 100. Pair with `offset` to page. | |
| state | No | Two-letter US state code, uppercase. The corpus currently covers California (`CA`) only — other state codes will return no rows. | |
| offset | No | Row offset for pagination. Defaults to 0. | |
| depth_to | No | Upper bound on chain depth, inclusive. | |
| leaf_year | No | Exact leaf year (e.g. 2026). The leaf is the most recent filing in the chain — this is the programme's most recent revision. Mutually exclusive with `leaf_year_from`/`leaf_year_to`. | |
| root_type | No | Substring match on the root filing's type. Common values: "New Program", "Transferred Program", "Auto Class Plan", "Class Plan", "Manual", "Rate". `root_type="New Program"` returns programmes that trace back to a clean launch. | |
| depth_from | No | Lower bound on chain depth, inclusive. Use for "programmes with at least N predecessors". | |
| leaf_serff | No | Direct lookup by leaf SERFF id. Exact match. Same as filtering all products that this filing is the leaf of (max one row per leaf). | |
| root_serff | No | Filter to products rooted at this SERFF id. Returns all programmes whose chain terminates at the given root (typically many products share a bureau root). | |
| company_name | No | Substring (ILIKE) match on the leaf-filing carrier name. Use for "Progressive programmes" type queries. | |
| leaf_year_to | No | Upper bound on leaf year, inclusive. | |
| all_revisions | No | When true, returns every product including prior revisions of the same lineage cluster. Default false — only the latest revision per (company_name, state, lob) is returned. Use for time-series queries (e.g. "how has Acme's CA auto rate manual evolved?") or chain audits. | |
| leaf_year_from | No | Lower bound on leaf year, inclusive. Use for "programmes whose most recent revision is on or after Y". | |
| leaf_likely_new | No | True when the leaf itself is a substantive programme launch — its own filing carries the rate manual (root-type label AND ≥3MB files or ≥200KB embeds). High-confidence buildables. | |
| chain_evidence_max | No | Upper bound on `chain_evidence_score`. Use for "low-evidence" diagnostic queries. | |
| chain_evidence_min | No | Lower bound on `chain_evidence_score` (cosine similarity of leaf-filing chunks vs immediate-parent chunks, 0-1). Use to find products with strong content-overlap chains (e.g. `chain_evidence_min=0.7`). NULL scores are excluded by any min filter. | |
| adoption_sources_any | No | Match products whose `adoption_sources` array contains ANY of the listed labels (PostgreSQL `&&` overlap). E.g. `["bureau"]` returns full-bureau-adoption products; `["me_too","bureau_forms_only"]` returns products that are me-too OR carry bureau forms. Valid labels: `bureau` (full bureau — loss costs + LCM), `me_too` (full adoption of another carrier), `proprietary` (carrier owns rates), `bureau_forms_only` (modifier — bureau forms with own/me-too rates). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), the description details default behavior (one row per lineage cluster), all_revisions flag, filter conjunction, limit/cap, ordering, and total count behavior. It explains adoption_sources values and effect. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with sections, bullet points, and front-loaded warning. While somewhat verbose, the complexity of 19 parameters justifies the length. Every sentence adds necessary context, so it's appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high complexity (19 parameters, no required, no output schema, many siblings), the description is remarkably complete. It covers scope, usage, parameters, behavior, and output shape (lite shape), and even suggests follow-up with 'get_product' for full data. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds substantial value: explains common patterns, parameter interactions (e.g., leaf_year mutual exclusivity), and valid values for adoption_sources with richer context than the schema enums. This exceeds the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches the 'products' corpus by specific criteria and explicitly distinguishes it from 'search_filings', warning against misuse for non-programme queries. This is a specific verb+resource with sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description begins with a 'Scope warning' that tells when NOT to use the tool (e.g., for general filings) and directs to 'search_filings' as the alternative. It provides multiple common patterns with example parameters, giving clear when/when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_summary_embedsSemantic Search — Filing SummariesARead-onlyIdempotentInspect
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_filingswith 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_summaryon 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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds significant behavioral context: cost (one embedding call + indexed lookup), no LLM planning/composition, bounded and fast. It also explains query embedding and cosine comparison. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet lists and clear sections, but it is somewhat lengthy. Every sentence adds value, though some repetition could be trimmed. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters, 1 required, no output schema, the description covers return format (top-K hits with fields), default/max topK, excerpt length, behavior when filters narrow candidate set, and cost. It also explains query interpretation and combination with other tools. Very complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 13 parameters. The description adds extra meaning: typ for naic (5-digit string), default/cap for topK, verbatim query advice, mutual exclusivity of year and year_from/to, wildcard behavior for filing_type and product_type, and serff scoping. This greatly aids correct parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a pure vector search over per-filing summary embeddings. It distinguishes from siblings like search_actuarial_embeds and search_filing_embeds by specifying the embedding type and use cases. The scope (one embedding per filing, ~59K rows) and exact matching excerpt/metadata are well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists right surfaces (content questions, topic discovery) and wrong surfaces (actuarial-shape questions, concrete filters, SERFF id). It also provides combination strategies with other tools like search_filings and get_filing_summary, guiding the agent on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!