analytics-entity

Important: Please read auron-docs and api skills before running entity analytics. You need an organizationId, an entityRecordId, a valid API key, and a valid session token.

Entity Analytics

Entity analytics are scoped to a single entity record. Every skill in this file requires an organizationId and an entityRecordId to operate. These skills answer questions like "how healthy is this account?", "what signals are we missing?", and "is engagement trending up or down?"

All entity analytics work by querying the Explore API with the appropriate context. The Explore API internally selects the right pre-built aggregation tools for each question.

---

Required Inputs

Every entity analytics skill requires the following inputs. You must collect all required inputs before making any query. Never guess or assume values.

Input	Required	Description	How to obtain
organizationId	Yes	The organization scope for all data	Ask the user to select their organization. Use the api skill to list organizations if needed.
entityRecordId	Yes	The specific account or record to analyze	Ask the user which account or entity record they are asking about. If ambiguous, list entity records and ask them to pick one.
fromDate	No	Start of time window (ISO 8601)	Ask the user if they want to scope the analysis to a specific time range. Default: all time.
toDate	No	End of time window (ISO 8601)	Same as above. Default: now.

Input Collection Rules

1. If the user says "this account" or "this entity" but no entityRecordId is in context, ask them to specify which account.
2. If the user gives a name instead of an ID, search entity records by name and confirm the match before proceeding.
3. Never proceed with a query if organizationId or entityRecordId is missing.
4. If the user has previously selected an organization in the conversation, reuse it — do not ask again.

---

Account Health Pulse

What It Does

Produces a composite health score for an entity record by assessing seven dimensions of intelligence quality. Returns a health tier classification with a per-dimension breakdown and plain-language recommendations.

When to Use

Trigger this skill when the user asks questions like:

• "How healthy is this account?"
• "Is this account at risk?"
• "Give me a health check on [entity]"
• "What's the status of this record?"
• "Run an account overview for me"
• "Should I be worried about this account?"

Health Dimensions

The health score is assembled from seven dimensions. Each dimension is scored independently and contributes to the overall tier.

#	Dimension	What It Measures	Explore Tool
1	Signal Coverage	% of expected signal categories that have been detected	entity_context_coverage
2	Signal Confidence	Average confidence score across all detected signals	entity_signal_profile
3	Engagement Velocity	Current vs prior period interaction rate with trend direction	entity_velocity_score
4	Interaction Cadence	Regularity of engagement and presence of dangerous silence gaps	entity_cadence_and_gaps
5	Agent Rotation	Number of agents covering the account and single-agent risk	entity_agent_rotation
6	Session Quality	Feedback scores, starred messages, engagement depth	entity_engagement_quality
7	Signal Freshness	How many signals are stale (not refreshed in 21+ days)	entity_stale_signals

Scoring Rubric

Each dimension receives a score from 0 to 100 based on the data returned by its explore tool.

Signal Coverage

• 80–100: 80%+ of expected categories detected
• 50–79: 50–79% of categories detected
• 20–49: 20–49% of categories detected
• 0–19: Less than 20% of categories detected

Signal Confidence

• 80–100: Average confidence ≥ 0.8
• 50–79: Average confidence 0.5–0.79
• 20–49: Average confidence 0.3–0.49
• 0–19: Average confidence < 0.3 or no signals

Engagement Velocity

• 80–100: Accelerating (current period > prior period by 20%+)
• 50–79: Stable (within ±20% of prior period)
• 20–49: Declining (current period < prior period by 20–50%)
• 0–19: Stalled (current period < prior period by 50%+ or zero activity)

Interaction Cadence

• 80–100: Regular cadence, no gaps > 14 days
• 50–79: Mostly regular, occasional gaps of 14–30 days
• 20–49: Irregular, gaps of 30–60 days present
• 0–19: Highly irregular or gaps > 60 days

Agent Rotation

• 80–100: 3+ agents with balanced session distribution
• 50–79: 2 agents or 3+ with unbalanced distribution
• 20–49: Single agent with moderate session count
• 0–19: Single agent with few sessions (single-thread risk)

Session Quality

• 80–100: Consistently high feedback scores, frequent starred messages
• 50–79: Mixed feedback, some starred messages
• 20–49: Low feedback scores, few starred messages
• 0–19: No feedback data or consistently poor quality

Signal Freshness

• 80–100: Less than 10% of signals are stale
• 50–79: 10–30% of signals are stale
• 20–49: 30–60% of signals are stale
• 0–19: More than 60% of signals are stale or no signals at all

Health Tier Classification

The overall health tier is determined by the weighted average of all dimension scores:

Tier	Score Range	Meaning
Strong	75–100	Account is well-covered with fresh, high-quality intelligence
Watch	50–74	Account has some gaps or declining trends — monitor closely
At Risk	25–49	Significant intelligence gaps or staleness — intervention needed
Dark	0–24	Little to no usable intelligence on this account

Dimension weights (equal by default):

• Signal Coverage: 1x
• Signal Confidence: 1x
• Engagement Velocity: 1x
• Interaction Cadence: 1x
• Agent Rotation: 1x
• Session Quality: 1x
• Signal Freshness: 1x

Workflow

1. Collect organizationId and entityRecordId from the user (see Required Inputs above)
2. Query all seven explore tools listed in the Health Dimensions table, passing organizationId and entityRecordId as context
3. Score each dimension using the Scoring Rubric
4. Compute the weighted average to determine the overall Health Tier
5. Identify the two weakest dimensions as priority areas for improvement
6. Generate plain-language recommendations for each weak dimension
7. Present the results in the output format below

Example Output

## Account Health Pulse: Acme Corp

**Overall Health: Watch (Score: 62/100)**

| Dimension | Score | Status |
|-----------|-------|--------|
| Signal Coverage | 72 | 🟡 6 of 9 expected categories detected |
| Signal Confidence | 81 | 🟢 Average confidence: 0.83 |
| Engagement Velocity | 45 | 🟠 Declining — 32% fewer interactions vs prior period |
| Interaction Cadence | 68 | 🟡 Last interaction 18 days ago, one 25-day gap in history |
| Agent Rotation | 35 | 🟠 Single agent (Sarah K.) handles all sessions |
| Session Quality | 78 | 🟢 Strong feedback scores, 4 starred messages |
| Signal Freshness | 55 | 🟡 3 of 11 signals not refreshed in 21+ days |

### Priority Recommendations

1. **Agent Rotation (35)**: This account is covered by a single agent. If Sarah K. is
   unavailable, institutional knowledge is at risk. Assign a second agent to upcoming
   sessions to build shared context.

2. **Engagement Velocity (45)**: Interaction frequency has dropped 32% compared to the
   prior period. Consider scheduling a proactive check-in to re-establish cadence before
   the account goes dark.

### Summary

Acme Corp has strong signal confidence and session quality, but engagement is declining
and the account is dependent on a single agent. The most urgent action is diversifying
agent coverage to reduce single-thread risk. Re-establishing regular cadence should be
the secondary priority.

---

Signal Coverage Check

What It Does

Shows what percentage of expected signal categories have been detected for a specific entity record, broken down by category. Identifies which signal categories are covered, which are missing, and rates the severity of each gap.

When to Use

Trigger this skill when the user asks questions like:

• "What signals are we missing for this account?"
• "How complete is our intelligence on this entity?"
• "What percentage of signal categories are covered?"
• "Where are the gaps in what we know?"
• "Which signal types haven't fired for this record?"

Coverage Dimensions

Aspect	What It Measures	Explore Tool
Category Coverage	% of signal categories with at least one detection	entity_context_coverage
Detection Depth	Number of detections per covered category	entity_signal_profile
Confidence Profile	Average confidence per covered category	entity_signal_profile

Coverage Classification

Each signal category for the entity record is classified into one of four states:

State	Definition	Indicator
Strong	3+ detections with average confidence ≥ 0.7	Category is well-covered and reliable
Adequate	1–2 detections with average confidence ≥ 0.5	Category has been detected but needs more corroboration
Weak	1+ detections with average confidence < 0.5	Category detected but low quality — may not be actionable
Missing	Zero detections	Category has never been detected for this entity record

Gap Severity

Missing categories are rated by severity based on whether other entity records of the same type have detections in that category:

Severity	Definition
Critical	Category is detected for 70%+ of similar entity records but missing here
Moderate	Category is detected for 30–69% of similar entity records but missing here
Low	Category is detected

---

Content truncated.