# AI Context

Teach Amplitude's agents your metrics, terminology, and business preferences for better answers.

Source: https://amplitude.com/docs/amplitude-ai/ai-context

---

On this page

- [Getting started](#getting-started)
- [Find AI Context](#find-ai-context)
- [What to gather before you start](#what-to-gather-before-you-start)
- [Understanding AI context](#understanding-ai-context)
- [Two levels of context](#two-levels-of-context)
- [What to write](#what-to-write)
- [Write good context](#write-good-context)
- [Industry templates](#industry-templates)
- [Examples](#examples)
- [Be specific](#be-specific)
- [Be concise](#be-concise)
- [Include business context](#include-business-context)
- [Use explicit do/don't rules](#use-explicit-dodont-rules)
- [Define your terminology](#define-your-terminology)
- [Best practices](#best-practices)
- [Maintain context over time](#maintain-context-over-time)
- [Frequently asked questions](#frequently-asked-questions)

# AI Context

Teach Agents how your business works. Define your metrics, terminology, and preferences to tailor every answer to your organization.

## Getting started

Before you add your context, gather the necessary information and navigate to the right place.

### Find AI Context

Agents, including Global and Specialized Agents, use two layers of context: Organization and Project.

Access both from *Project Settings > AI Controls*.

### What to gather before you start

Business basics

Your business model, such as B2B, B2C, or marketplace.

Your North Star metric and how you define it.

Your fiscal year start date, if it isn't January.

Your key customer segments and how to identify them.

Technical details

Event names for key actions, such as signup and purchase.

Property names that define segments, such as plan type and ARR.

Test or internal user identifiers to exclude.

Any deprecated events to avoid.

## Understanding AI context

Context changes how Agents answer questions.

A user asks:

> Show me our activation rate

Without context

Agents guess. Use wrong events, wrong timeframe, include test users.

I'll create a chart showing user activation. I'll define activated users as those who completed any event after signing up...

With context

Agents know your exact definition, timeframe, and filters.

I'll show activation rate using your definition: users who triggered `first_project_created` within 7 days of signup, excluding @test.com emails...

### Two levels of context

Organization context

Limit: 10,000 characters

Applies to all projects. Use for company-wide standards.

Business model and KPI definitions.

Standard terminology.

Global filters, such as excluding test users.

Fiscal calendar rules.

Project context

Applies to one project. Use for product-specific details.

Product-specific events and funnels.

Metrics unique to this product.

Product-specific segments.

Overrides for org defaults when needed.

At runtime, Agents combine both context sources. Project context overrides organization context when they conflict.

### What to write

Write this

Amplitude can't infer the following:

**Business model**: "B2B SaaS, annual subscriptions"

**Key segments**: "Enterprise = ARR > $50K"

**Metric definitions**: "Activation = first project within 7 days"

**Date rules**: "Fiscal year starts April 1"

**Exclusions**: "Filter out @test.com emails"

Skip this

Amplitude understands the following:

Your event catalog and properties.

Top events by volume.

Official dashboards.

Saved cohort definitions.

Existing chart configurations.

Reference your existing cohorts and dashboards by name in any context you provide. For example:

> Use the 'Power Users' cohort when asked about engaged users.

Amplitude includes their definitions by default.

## Write good context

Structure your context with markdown so it's easy for Agents to parse.

Formatting

`##` Use headings to separate sections.

`-` Use bullets for lists of items.

`` `backticks` `` Wrap event and property names.

`**bold**` Highlight key terms.

Common sections

**Business Overview**: Your model and North Star metric.

**Key Metrics**: Activation, engagement, and retention definitions.

**Segments**: Customer tiers mapped to properties.

**Do/Don't Rules**: Defaults, filters, and things to avoid.

**Date Rules**: Fiscal year, week start, and default ranges.

Keep it under 10,000 characters. That's the limit for both org and project context. Focus on the 20% of information that covers 80% of questions your team asks.

## Industry templates

Start with a template for your industry and customize it. These are complete examples you can copy and adapt.

Copy this template, replace the event and property names with your own, and adjust the definitions to match your business.

text

```
## Business Overview
B2B SaaS platform with annual subscriptions.
North Star: Monthly Active Workspaces (MAW)

## Key Metrics
- **Activation**: User triggers `workspace_created` within 7 days of `signup_completed`
- **Engaged**: 3+ sessions in last 7 days with at least one `feature_used` event
- **Expansion-ready**: `seat_utilization` > 80%

## Segments
- Enterprise: `plan_tier` = "enterprise" OR `arr` > 50000
- Mid-Market: `arr` between 10000 and 50000
- SMB: `plan_tier` in ("starter", "growth")
- Trial: `subscription_status` = "trial"

## Rules
DO:
- Default to last 30 days for time ranges
- Exclude `email` contains "@test.com" or `is_internal` = true
- Use `mrr_change` event for revenue analysis

DON'T:
- Include `environment` = "staging" or "development"
- Use deprecated: `old_signup`, `legacy_workspace_created`

## Date Rules
- Fiscal year starts February 1
- "This quarter" = current fiscal quarter
- Week starts Monday

## Examples

See what makes AI Context effective and what pitfalls to avoid.

### Be specific

Good

Defines exact events, timeframes, and thresholds that Agents can use directly.

- **Activation**: User triggers `project_created` event
  within 7 days of `signup_completed`
- **Engaged User**: 3+ sessions in the last 7 days
- **Churned**: No activity for 30+ days

Bad

No concrete definitions. Agents must guess what 'activation' means and what time ranges are 'appropriate.'

Help users understand activation and engagement.
Show relevant metrics when asked about user behavior.
Make sure to use appropriate time ranges.

### Be concise

Dense, scannable format. Each line is actionable with exact property names.

- Enterprise: `plan_tier` = "enterprise"
- SMB: `plan_tier` = "starter" OR "growth"

## Filters
- Exclude: `email` contains "@test.com"
- Exclude: `is_internal` = true

Same information buried in prose. Wastes tokens and is harder to parse.

When analyzing our customer base, it's important to
understand that we have several different types of
customers. Enterprise customers are our largest accounts
- they typically have the enterprise plan tier. Small
and medium businesses (SMBs) are customers who use our
starter or growth plans. We also have trial users who
are evaluating the product.

### Include business context

Establishes context Amplitude can't infer, like fiscal calendar and business model.

## Business Model
B2B SaaS, annual subscriptions.

## Fiscal Calendar
- FY starts April 1

Generic statements that don't help Agents understand your specific business.

We are a software company that sells to businesses.
Our product helps teams collaborate better.
We care about growth and revenue.

### Use explicit do/don't rules

Clear instructions with exact property values. Agents know what to do and avoid.

- Group by `platform` when comparing mobile vs web
- Use `Total Revenue` event for revenue metrics

- Include events where `environment` = "staging"
- Use deprecated events: `old_signup`, `legacy_purchase`

Vague guidance that doesn't tell Agents what specific actions to take.

Be helpful and show relevant data.
Use appropriate filters when needed.
Be careful with sensitive information.

### Define your terminology

Maps business terms to exact event names. Documents naming conventions.

## Terminology
- "Conversion" = `checkout_completed` event
- "Signup" = `account_created` (not `user_registered`)
- "Active" = user with 1+ events in last 7 days

## Naming Conventions
Events: snake_case (`button_clicked`)
Properties: camelCase (`userId`, `planType`)

Doesn't specify what the correct terms or conventions actually are.

Use the correct terminology for our company.
Use exact event names and correct casing.
Properties follow our naming conventions.

## Best practices

Do

Use exact event and property names with correct casing.

Be specific: "exclude `email` contains @test.com".

Put universal rules at the org level, and put overrides at the project level.

Test changes by asking questions before saving.

Keep a backup in your wiki or version control.

Don't

List events or properties. Amplitude already knows these.

Write vague instructions like "be helpful" or "use appropriate filters".

Create conflicting rules between org and project context.

Add edge-case rules that apply only to rare situations.

Make large changes without testing first.

### Maintain context over time

Keep the following in mind to help maintain context.

- **Assign owners**: Analytics lead for org context. PM or analyst for each project context.

- **Review regularly**: Quarterly, after major launches, or when Agents give unexpected answers.

- **Change carefully**: One change at a time. Test with real questions. Keep backups.

## Frequently asked questions

Was this helpful?

<!--$-->

<!--/$-->