Explanation Agent¶

The Explanation Agent is an AI-powered feature that explains insurance premium calculations in plain, conversational language. It helps users understand how their premium was calculated by breaking down complex rating logic into easy-to-understand explanations.

Overview ¶

What is the Explanation Agent?¶

Explanation Agent Interface — *Screenshot Placeholder: Chat modal showing conversation with agent explaining a $2,340 BOP premium with breakdown of factors and coverages*¶

The Explanation Agent is a conversational AI assistant that:

Explains why your premium is a specific amount
Breaks down calculations step-by-step
Answers questions about rating factors
Compares “what-if” scenarios
Translates insurance jargon into plain language

Key Features ¶

Explanation Agent Features¶
Feature	Description
Automatic Explanation	Provides initial summary when you open the chat
Interactive Q&A	Ask follow-up questions in natural language
Factor Analysis	Explains how each factor affected the premium
Coverage Breakdown	Details each coverage’s premium calculation
Formula Details	Shows how formulas were applied
Scenario Comparison	Answers “what-if” questions

When to Use ¶

Use the Explanation Agent when you need to:

Understand why a premium is higher or lower than expected
Explain pricing to a client or colleague
Identify which factors have the biggest impact
Learn how a specific product’s rating works
Troubleshoot unexpected results
Prepare for client presentations

Getting Started ¶

Accessing the Agent ¶

To access the Explanation Agent:

Complete a rating calculation
Navigate to the Rating History page
Click on a completed rating to view details
Click the Explain This Quote button

Note

The “Explain This Quote” button only appears for ratings with status “success” or “warning”. Failed ratings cannot be explained.

Opening the Chat ¶

Explanation Modal Opening — *Screenshot Placeholder: Modal sliding in from right showing “Connecting…” then “Connected” status*¶

When you click “Explain This Quote”:

Modal window slides in from the right
Connection status shows “Connecting…”
Agent automatically analyzes the rating
Initial explanation appears (typically 5-10 seconds)
Input field becomes active for your questions

Understanding the Interface ¶

Chat Window Components ¶

Explanation Interface Anatomy — *Screenshot Placeholder: Annotated chat interface showing header with close button, scrollable message area, typing indicator, and input field with send button*¶

The chat interface includes:

Header Bar: * Title: “Premium Explanation” * Close button (×) * Rating run reference
Message Area: * Auto-scrolls to latest message * Agent messages on left (blue) * User messages on right (gray) * Markdown formatting support * Timestamps on hover
Status Indicators: * Connection status alerts * Typing indicator when agent is thinking * Error messages if connection fails
Input Area: * Text input field * Send button * Enter key to send * Shift+Enter for new line

Message Formatting ¶

Agent messages support rich formatting:

Bold text for emphasis
Italic text for terms
Bullet lists for factors
Numbered lists for steps
Code blocks for formulas
Tables for comparisons

Using the Explanation Agent ¶

Initial Explanation ¶

When you open the chat, the agent automatically provides:

Total Premium: The final calculated amount
Coverage Summary: List of coverages with individual premiums
Key Factors: Most impactful rating factors
Calculation Overview: High-level explanation
Invitation: Prompt to ask questions

Example initial explanation:

Your total premium is $2,340.00. This includes two coverages:

• General Liability: $1,140.00
• Property: $1,200.00

The calculation started with base premiums based on your business
type and location. Then we applied adjustments for:

• Your building's construction type (brick - lower fire risk)
• Territory rating (urban area)
• Coverage limits you selected
• Your chosen deductibles

What would you like to know more about?

Asking Questions ¶

Best practices for asking questions:

Good Questions:

✓ "Why is my premium higher than last year?"
✓ "How did the territory factor affect the price?"
✓ "What's included in the General Liability premium?"
✓ "Can you explain the building class rating?"

Less Effective:

✗ "Why?" (too vague)
✗ "Tell me everything" (too broad)
✗ "Is this a good price?" (subjective)

Question Types ¶

Factor Questions ¶

Ask about specific rating factors:

Example 1: Territory

User: "Why did my territory affect the premium?"

Agent: "Your territory (14 - Downtown Metro) affects your premium
because it's in an urban area with higher exposure to certain risks.

Here's how it impacted your calculation:
• Territory factor: 1.15 (15% increase)
• This increased your base premium from $2,035 to $2,340
• Urban territories have higher rates due to:
  - More traffic (liability exposure)
  - Higher replacement costs
  - Greater crime risk

Suburban territories (like 02 or 03) would have factors around
0.85-0.95, which could save approximately $230-$350 annually."

Example 2: Building Value

User: "How does building value affect my premium?"

Agent: "Your building value of $750,000 is the primary driver of
your Property coverage premium. Here's the breakdown:

• Base rate: $0.45 per $100 of value
• Calculation: ($750,000 / 100) × $0.45 = $3,375
• After adjustments (construction type, protection): $1,200

If you increased the building value to $1,000,000, your Property
premium would increase to approximately $1,600 (a $400 increase)."

Coverage Questions ¶

Ask about coverage calculations:

Example 1: Coverage Breakdown

User: "Break down the General Liability coverage"

Agent: "Your General Liability coverage ($1,140) was calculated as:

Step 1: Base Premium
• Liability limit: $1,000,000
• Class code: 43211 (Retail Store)
• Base rate: $1.12 per $1,000 of payroll
• Your estimated payroll: $500,000
• Base: ($500,000 / 1,000) × $1.12 = $560

Step 2: Modifications
• Territory modifier: 1.15 (urban area)
• Experience modifier: 1.05 (claims history)
• Subtotal: $560 × 1.15 × 1.05 = $677

Step 3: Additional Coverages
• Products/Completed Operations: $463

Total GL Premium: $677 + $463 = $1,140"

Example 2: Coverage Limits

User: "Why do I need $1 million liability coverage?"

Agent: "The $1,000,000 General Liability limit you selected is
the standard coverage amount for businesses in your industry.

This limit provides:
• Per occurrence protection up to $1M
• Aggregate coverage (total for all claims)
• Defense costs in addition to the limit

You could select a $2,000,000 limit for approximately $350 more
annually, or reduce to $500,000 to save about $280. However,
$1M is recommended for retail businesses due to customer
exposure and product liability risks."

Formula Questions ¶

Ask about how formulas work:

Example: Formula Explanation

User: "How was the base premium calculated?"

Agent: "The base premium uses the 'CALC_BASE_PROPERTY' formula:

Formula: (building_value / 100) × base_rate × construction_factor

Your values:
• building_value: $750,000
• base_rate: $0.45 (from territory/class lookup table)
• construction_factor: 0.85 (brick construction discount)

Calculation:
($750,000 / 100) × $0.45 × 0.85 = $2,868.75

The construction_factor of 0.85 represents a 15% discount
because brick construction has lower fire risk than wood frame."

What-If Scenarios ¶

Ask comparative questions:

Example 1: Deductible Change

User: "What if I increased my deductible to $5,000?"

Agent: "Increasing your deductible from $1,000 to $5,000 would
typically reduce your premium by approximately 12-15%.

For your current premium of $2,340:
• Estimated savings: $280-$350 annually
• New premium: ~$1,990-$2,060

Trade-off:
• Save: $280-$350 per year
• Risk: Pay $4,000 more out-of-pocket per claim

Break-even: If you have a claim every 11-14 years, the higher
deductible saves money. If claims are more frequent, the lower
deductible may be better."

Example 2: Coverage Change

User: "What if I dropped the Business Income coverage?"

Agent: "Business Income coverage is optional and adds $385 to
your premium. Removing it would reduce your total to $1,955.

However, Business Income coverage protects you if:
• Your business must close due to covered damage
• You lose revenue during repairs
• You have ongoing expenses (rent, payroll)

For a retail business with $50,000/month revenue, even a
1-month closure could cost $50,000 in lost income. The $385
premium provides up to $100,000 in coverage.

Consider: Can your business survive without revenue for
several months during repairs?"

Advanced Usage ¶

Multi-Step Conversations ¶

The agent maintains context across multiple questions:

User: "Why is my premium higher than my friend's?"
Agent: "Premiums vary based on many factors. Which specific
factors differ between your businesses?"

User: "We both have retail stores in the same area"
Agent: "Territory is the same, so let's look at other factors.
What are the differences in building values, construction types,
or business classifications?"

User: "My building is wood frame, theirs is brick"
Agent: "That's a significant factor! Wood frame construction
typically increases property premiums by 20-30% compared to
brick. For your $750,000 building value:
• Wood frame (you): $1,200 property premium
• Brick (your friend): ~$840-$920 property premium
• Difference: $280-$360

This accounts for most of the premium difference."

Comparing Multiple Ratings ¶

The agent can only access one rating at a time, but you can ask comparative questions:

User: "How does this compare to my quote from last month?"

Agent: "I can see this current rating's details but don't have
access to your previous quotes. However, I can explain what
factors might cause differences:

Common changes that affect premiums:
• Effective date (rates may have changed)
• Building value updates
• Coverage limit changes
• Claims history updates
• Territory or classification changes

What changed between the quotes?"

Explanation for Clients ¶

Client Explanation — *Screenshot Placeholder: Agent providing client-friendly explanation without technical jargon*¶

Request client-friendly explanations:

User: "Explain this in simple terms for my client"

Agent: "Here's a client-friendly explanation:

'Your annual insurance premium is $2,340, which covers your
business for property damage and liability claims.

This includes:
• Building and contents protection: $1,200
• Liability coverage (if someone gets hurt): $1,140

The price is based on:
• Your business location (downtown metro area)
• Type of business (retail store)
• Building size and construction
• Coverage amounts you selected

This is a competitive rate for your business type and location.
You can reduce the premium by increasing deductibles, but that
means you'd pay more out-of-pocket if you have a claim.'"

Technical Details ¶

How It Works ¶

Explanation Agent Architecture — *Screenshot Placeholder: Technical diagram showing WebSocket connection, AI processing, and data access flow*¶

The Explanation Agent:

Retrieves Data: Loads complete rating run data including: * Input factors * Calculation steps * Formula executions * Table lookups * Final results
Analyzes: Uses AI (Claude 3.5 Sonnet) to: * Understand the calculation flow * Identify key factors * Determine impact of each component
Explains: Generates responses that: * Use plain language * Provide relevant details * Include examples * Answer the specific question
Maintains Context: Remembers the conversation to: * Reference previous answers * Follow up on topics * Avoid repetition

Available Tools ¶

The agent has access to these data retrieval tools:

Agent Tools¶
Tool	Purpose
get_calculation_overview	High-level summary of the entire calculation
get_coverage_breakdown	Detailed breakdown for specific coverage
get_factor_explanation	How a specific factor affected the premium
get_formula_details	Details about formulas used in calculations

Example tool usage:

User: "Explain the property coverage"

[Agent calls: get_coverage_breakdown(coverage_code="PROPERTY")]

Agent receives:
{
  "coverage_code": "PROPERTY",
  "coverage_name": "Building & Contents",
  "base_premium": 2868.75,
  "modified_premium": 1200.00,
  "calculation_breakdown": [
    {
      "step": 1,
      "description": "Calculate base property premium",
      "formula": "CALC_BASE_PROPERTY",
      "result": 2868.75
    },
    ...
  ]
}

Agent uses this data to explain to you.

Security and Privacy ¶

Access Control ¶

The Explanation Agent enforces strict access control:

Authentication Required: Must be logged in
Authorization Check: Can only explain ratings you created or have permission to view
Session Isolation: Each chat is independent
No Data Sharing: Your conversations are not shared with other users

Warning

If you try to access a rating you don’t own, the connection will be rejected with an “Access Denied” error.

Data Retention ¶

Conversation data handling:

Data Retention Policy¶
Data Type	Retention
Messages	Not stored (ephemeral session only)
Rating Data	Stored as part of rating run (permanent)
Usage Metrics	Aggregated metrics only (no message content)

Best Practices ¶

Getting Better Explanations ¶

Be Specific: Instead of “Why?”, ask “Why did the territory factor increase my premium?”
Provide Context: “I’m presenting this to a client” helps the agent adjust language
Ask Follow-ups: If unclear, ask for clarification or examples
Request Comparisons: “What if I changed X?” helps understand impact
Focus on One Topic: Address one question at a time for clearer answers

Example Progression ¶

❌ Vague: "Is this right?"
✓ Better: "Why is the General Liability premium $1,140?"
✓✓ Best: "Break down how the General Liability premium of $1,140
          was calculated, and explain which factors had the
          biggest impact."

When to Use vs. Not Use ¶

Good Use Cases:

Understanding unexpected premium changes
Preparing client presentations
Training new underwriters
Troubleshooting calculations
Learning product rating logic

Not Recommended For:

Changing the calculation (agent explains only, doesn’t modify)
Getting underwriting advice (agent explains data, not policy)
Comparing to competitors (no external data)
Historical trend analysis (one rating at a time)

Troubleshooting ¶

Connection Issues ¶

Connection Error — *Screenshot Placeholder: Error alert showing “Connection failed. Please check your internet connection and try again.”*¶

If the chat won’t connect:

Check Internet: Ensure stable connection
Refresh Page: Reload the rating run detail page
Try Again: Click “Explain This Quote” again
Check Browser: Ensure JavaScript and WebSockets enabled
Contact Support: If problem persists

Agent Not Responding ¶

If the agent doesn’t respond:

Wait: Initial analysis can take 10-15 seconds
Check Typing Indicator: Shows agent is processing
Review Message: Ensure question was sent (look for your message in chat)
Refresh: Close and reopen the chat
Report Issue: If agent consistently fails to respond

Unclear Explanations ¶

If an explanation doesn’t make sense:

User: "Can you explain that in simpler terms?"
User: "Can you give me an example?"
User: "What does [term] mean?"
User: "Can you break that down step-by-step?"

Error Messages ¶

Common error messages:

Error Resolution¶
Error Message	Solution
“Connection failed”	Check internet, refresh page, try again
“Access denied”	You don’t own this rating, check permissions
“Rating not found”	Rating may have been deleted, go back
“Service unavailable”	AI service temporarily down, try later

Examples and Use Cases ¶

Example 1: Understanding Territory Impact ¶

Context: Underwriter notices higher premium for urban location

User: "Why is territory 14 more expensive than territory 01?"

Agent: "Great question! Territory 14 (Downtown Metro) has
a higher rating factor than Territory 01 (Rural Area) due to
several risk factors:

Territory 14 Characteristics:
• Higher traffic density (increased liability exposure)
• Greater property values (higher replacement costs)
• More crime incidents (theft, vandalism risk)
• Higher claims frequency historically
• Factor: 1.15 (15% increase)

Territory 01 Characteristics:
• Lower traffic (reduced accident risk)
• Lower property values
• Less crime
• Lower claims frequency
• Factor: 0.85 (15% decrease)

Impact on Your Premium:
• Base premium: $2,035
• Territory 14: $2,035 × 1.15 = $2,340
• Territory 01 would be: $2,035 × 0.85 = $1,730
• Difference: $610 annually

This reflects actuarial data showing Territory 14 has
approximately 35% higher claims costs than Territory 01."

Example 2: Client Presentation ¶

Context: Underwriter needs to explain pricing to client

User: "Give me a simple explanation for my client about why
their premium is $2,340"

Agent: "Here's a client-friendly explanation:

'Your business insurance premium is $2,340 per year. This
covers you for:

1. Property Protection ($1,200/year)
   - Covers your building and contents up to $750,000
   - Protects against fire, theft, weather damage
   - $1,000 deductible means you pay first $1,000 of any claim

2. Liability Protection ($1,140/year)
   - Covers if someone gets injured on your property
   - Protects against lawsuits up to $1,000,000
   - Includes legal defense costs

Why This Amount?
• Your business is in downtown (higher risk area)
• Retail stores have more customer exposure
• Your building size and construction type
• Amount of coverage you selected

This rate is competitive for your business type and location.
You have options to adjust the cost:
• Higher deductible = lower premium (but more out-of-pocket)
• Lower coverage limits = lower premium (but less protection)
• Security improvements might qualify for discounts

Would you like me to show you how different deductibles would
affect your price?'"

Example 3: Troubleshooting Unexpected Results ¶

Context: Premium is higher than expected

User: "The premium is $800 higher than I estimated. Why?"

Agent: "Let's identify what's causing the difference. Your
actual premium is $2,340. Can you tell me what you estimated?"

User: "I estimated $1,540 based on the territory and building value"

Agent: "I see the discrepancy. Here are the factors that
added to the base calculation:

Base Calculation:
• Building value premium: ~$900
• Base liability: ~$640
• Estimated total: $1,540 ✓ (matches your estimate)

Additional Factors Applied:
• Territory modifier: +15% ($231)
• Protection class: +8% ($123)
• Claims history experience mod: +5% ($77)
• Business income coverage: $385 (optional coverage included)
• Deductible credit: -$16 (selected $1,000 deductible)

Total Additions: $800

The main difference is:
1. Territory modifier (15% increase): $231
2. Optional Business Income coverage: $385
3. Protection class (no sprinklers): $123
4. Experience modifier: $77

To get closer to your estimate:
• Remove Business Income coverage: -$385
• Installing sprinklers could reduce protection class: ~-$120

These changes would bring the premium to approximately
$1,835, much closer to your $1,540 estimate."

Next Steps ¶

Try It: Open a rating and click “Explain This Quote”
Learn More: See AI Agents Overview for AI features overview
Get Training: Contact your administrator for explanation agent training
API Access: See API Integration for API-based explanations

Tip

Practice with the Explanation Agent on familiar ratings first. This helps you understand how it works before using it with clients.

Note

The Explanation Agent uses the exact same data and formulas as the rating engine. If an explanation seems incorrect, it may indicate a configuration issue that should be reviewed.