Automated KPI Commentary: Teaching an AI Agent to Write the 'So What'

Every metrics review has the same pattern: someone pulls up the dashboard, sees that revenue is up 8% week-over-week, and then spends 20 minutes writing a sentence explaining why. Then they do it again for conversion rate. Then for churn. Then for CAC.

The numbers are already in your warehouse. The context — seasonality, campaigns, product launches, prior period comparisons — is also already in your warehouse. The gap is the synthesis, and that's exactly what a KPI commentary agent closes.

The Problem with Static Dashboards

Dashboards show what happened. They rarely explain why, and they never surface so what should we do. Analysts fill this gap manually, which means:

• Commentary is inconsistent across teams and time periods
• It's produced after the fact, not in real time when the metric moves
• The same contextual queries get run over and over by different people

A KPI commentary agent watches your metrics continuously, detects meaningful movements, pulls the supporting context automatically, and writes the narrative the moment the movement is confirmed — not the next morning after someone checks the dashboard.

What "Significant Movement" Means

The agent uses a tiered detection system rather than simple percentage thresholds, which produce too many false positives in volatile metrics:

Signal	Trigger
Statistical	Z-score > 2.0 vs. 30-day rolling baseline
Business rule	Crosses a predefined threshold (e.g., churn rate > 3%)
Trend break	3 consecutive days moving in the same direction after a flat period
Comparison	>10% variance vs. same period last year (seasonality-adjusted)

Only when one of these signals fires does the agent engage the narrative generation phase. This prevents alert fatigue.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    KPI COMMENTARY AGENT                         │
│                   (runs every 4 hours)                          │
│                                                                 │
│  1. Poll metrics store → check each KPI against triggers        │
│  2. On signal: fetch supporting context from warehouse          │
│  3. Generate narrative with LLM                                 │
│  4. Append to living commentary document                        │
│  5. Notify channel with summary + link                          │
└───────┬──────────────┬──────────────────────┬───────────────────┘
        │              │                      │
  ┌─────▼─────┐  ┌─────▼──────────┐  ┌───────▼───────┐
  │ Warehouse │  │ Context Store  │  │ Notification  │
  │ MCP       │  │ MCP            │  │ MCP           │
  │ (metrics) │  │ (campaigns,    │  │ (Slack)       │
  │           │  │  launches,     │  │               │
  │           │  │  seasonality)  │  │               │
  └───────────┘  └────────────────┘  └───────────────┘

The Context Store — the Secret Ingredient

Most KPI commentary agents fail because they explain the number without the business context. An 8% revenue spike means nothing without knowing that a promotional campaign ran last week, or that a large enterprise deal closed on Friday.

We maintain a lightweight context store — a simple Postgres table or even a markdown file — that the agent queries alongside the metrics:

-- context_events table
CREATE TABLE context_events (
  event_date     DATE,
  event_type     VARCHAR(50),  -- 'campaign', 'product_launch', 'pricing_change', 'incident'
  event_name     VARCHAR(200),
  affected_kpis  TEXT[],       -- ['revenue', 'conversion_rate']
  expected_impact VARCHAR(20), -- 'positive', 'negative', 'neutral'
  description    TEXT
);

The agent queries this table whenever a metric moves, joining business events to metric shifts. This is what turns raw numbers into analyst-grade commentary.

The Commentary Prompt

You are a business analytics agent writing KPI commentary for a weekly metrics review.

A significant movement has been detected:
- Metric: {metric_name}
- Current value: {current_value}
- Baseline (30d avg): {baseline}
- Movement: {delta_pct}% ({direction})
- Signal type: {signal_type}

Context events in the past 14 days affecting this metric:
{context_events_json}

Supporting data from warehouse:
{supporting_query_results}

Write commentary following these rules:
1. Lead with the metric movement in one sentence (number, direction, magnitude)
2. Attribute the movement to 1-2 specific causes — use the context events and
   supporting data, do not speculate
3. If the data does not support a clear cause, say so explicitly
4. Add one forward-looking sentence only if the data supports it
5. Max 4 sentences total. No bullet points. Plain prose.
6. Do not use hedging language ("appears to", "may have", "could be")

Format: plain text paragraph, no headers.

Sample Agent Output

Input: Revenue up 11.3% week-over-week, context shows email campaign ran Monday–Wednesday.

Agent output:

Revenue reached $4.2M this week, up 11.3% from the prior week's $3.8M. The increase is primarily attributable to the "Q4 Early Access" email campaign (Oct 28–30), which drove a 23% lift in returning customer purchases. New customer revenue was flat at $1.1M, consistent with the 4-week trend. Campaign-attributed revenue is expected to normalize next week as the promotion period ends.

That took the agent 8 seconds to produce. It would take an analyst 25 minutes to pull the supporting data and write it.

Living Commentary Document

Rather than sending individual alerts, the agent maintains a running markdown document that accumulates all commentary for the current reporting period. At week-end, the document is complete and ready for the weekly business review — no additional writing required.

# Weekly KPI Commentary — Week of Nov 3, 2025

## Revenue
[auto-generated commentary, Nov 4]

## Conversion Rate
[auto-generated commentary, Nov 5]

## Churn Rate
No significant movement detected this week. 30d avg: 1.8%.

## CAC
[auto-generated commentary, Nov 6]

The "no significant movement detected" line is also agent-generated — it confirms the metric was checked, not just skipped.

What Analysts Get Back

Analysts stop writing the same contextual queries and commentary drafts every week. They spend their time on the metrics that genuinely need human judgment: the ones the agent flagged as ambiguous, the ones with conflicting signals, and the strategic questions that require institutional knowledge no data source captures.

The agent handles the 80% that is repeatable. The analyst handles the 20% that matters most.

Book a strategy session to build your KPI commentary agent.