Taxonomy Generation & Data Auditing
When to Use
- User asks to create or review a tracking plan or event taxonomy
- User wants to validate event/property naming conventions
- User needs to audit data quality (duplicates, stale events, missing metadata)
- User asks about funnel design or event relationships
- Agent is generating event names or property names and needs to follow standards
- User wants to understand or improve their taxonomy governance
- User asks about reducing event volume or type counts
- User asks about deprecation, blocking, deleting, or hiding events
- Any agent needs a "source of truth" for taxonomy best practices before recommending events
- User asks about AI readiness, AI Controls, or improving AI feature accuracy
Layer 1: Foundational Concepts
Core Philosophy
Six principles govern all taxonomy work:
- Evidence-first. Never fabricate. Every finding must be grounded in tool-retrieved data. If something cannot be verified, say so explicitly.
- Scan aggressively. Propose confidently. Confirm before writing. Paginate autonomously through the full taxonomy. Form a prioritized, opinionated view of what needs fixing — then present it. Never call a write tool without explicit user confirmation.
- Be opinionated, not neutral. Generic requests ("audit my taxonomy") are an invitation to lead. Use the scoring framework, recommend the highest-impact action first, and explain why. Don't present a menu of equal options.
- Surface critical issues proactively. If you find something important while working on an adjacent task, raise it. Don't silently ignore a PII violation because the user only asked about naming conventions.
- Questions extract institutional knowledge. Ask about business intent and real-world meaning, not Amplitude mechanics. One focused question at a time. The goal is to surface knowledge that lives in people's heads.
- Explain before acting. Before calling any write tool, present exact proposed changes — including before/after state — and wait for explicit confirmation.
Data Quality Lifecycle
All taxonomy governance follows a four-stage loop:
- Detect — Scan systematically. Paginate through the full taxonomy. Score every finding. Surface issues with evidence before conclusions.
- Clarify — Ask one focused question to capture semantic truth. Do not suggest actions yet. Seek understanding first.
- Resolve — Apply metadata-only improvements. Guide humans through phased deprecation for structural changes. Never execute destructive actions unilaterally.
- Prevent — Recommend conventions and governance habits that stop drift from recurring.
Event Volume vs. Taxonomy Type Counts
These are different problems requiring different solutions:
- Event volume = total event instances ingested per billing period (how many times events fire). Properties do not count toward volume.
- Taxonomy type counts = number of distinct names across all schema dimensions (event types, event property types, user property types, group types, group property types). Each has its own limit.
Billing models — know which applies before advising:
- Event volume billing: customer has a contracted allocation of events per period. Exceeding it triggers overage costs. Flag significant event volume changes to these customers.
- MTU billing: customer is billed based on distinct users who trigger any event in a month. Per-user event counts matter less; total unique user count matters more.
What customers usually mean:
- "I need to reduce my event volume" → worried about billing (volume-billed customers)
- "I need to reduce my event types / schema count" → worried about hitting type limits (new types won't be queryable)
What actually reduces each:
| Goal |
Action |
Reduces Volume? |
Reduces Type Count? |
| Reduce volume |
Block event |
Yes |
No |
| Reduce volume |
Delete event |
Yes |
Yes |
| Reduce type count |
Delete event/property/group type |
— |
Yes |
| Reduce type count |
Block event |
No |
No |
| Reduce type count |
Hide event |
No |
No |
Key rules:
- Blocking and hiding do NOT reduce type count. A quota-constrained customer must delete, not block.
- Never recommend sampling. Sampling breaks funnel charts, journey paths, cohorts, downstream destinations, and Guides.
- Custom events and merged events simplify analysis but do NOT reduce raw event volume.
- When ambiguous, ask: "Are you trying to reduce how many events are being sent, or the number of different event and property types in your taxonomy?"
Event States and Metadata Permissions
| Status |
Meaning |
Can Edit Metadata? |
| Planned |
In tracking plan; not yet instrumented |
Yes |
| Live |
Actively receiving data |
Yes |
| Blocked |
Stops new ingestion; historical data accessible |
Yes |
| Unexpected |
Receiving data but NOT in tracking plan |
No — must add to tracking plan first |
| Deleted |
Stops ingestion; removed from new-chart dropdowns |
No — must restore first |
Unexpected events have special restrictions. No metadata can be updated until the event is added to the tracking plan. When you encounter Unexpected events:
- If they appear legitimate (real product actions, consistent volume): recommend adding to the tracking plan first, then apply metadata.
- If they appear invalid (single-day spikes, test strings, security scan artifacts): treat as a deprecation candidate through the standard safe deprecation process. Always distinguish "legitimate but undocumented" from "truly invalid" before recommending any action.
Activity state is NOT a deprecation signal. An event marked Inactive is behaving as intended.
Actual deprecation signals:
| Signal |
Interpretation |
| No recent volume |
Event has gone stale |
| No recent queries |
Event is unused |
| Both together |
Strong deprecation candidate |
Planned events: Zero volume and queries are expected — evaluate by age, name collisions with Live events, and test-like names instead.
Custom Events, Labeled Events, and Merged Events
None reduce event volume. Each has distinct behavior:
- Custom events (
ce: prefix, type = custom): Logical combinations of underlying events for analysis convenience. The underlying events still exist and fire independently. Always check whether an event is used as the basis for a custom event before recommending its deletion — deleting the underlying event may break the custom event silently. Allowed: consolidate duplicate custom events with the same definition; improve naming, descriptions, categories, tags. Never claim that removing a custom event reduces event volume.
- Labeled events (
ce: prefix, type = labeled): Designed for use with Autocapture, distinguished from custom events by a separate metadata flag. Adding/deleting does not impact volume.
- Merged events (Transform/Merge): Source events are no longer individually available for analysis after a merge. If the user needs to analyze combined events AND retain independent analysis of source events, recommend a custom event instead of a merge. Allowed: merge truly duplicated events that share the same semantics and where independent analysis is not needed. Never claim that merging reduces event volume.
Protected Data Categories
How to identify category from naming convention: Events with bracket prefixes ([...]) follow a consistent pattern: if the text inside the brackets is a recognizable third-party product brand, it is an integration. If not, it is an Amplitude system event.
Amplitude system events ([Amplitude], [Guides-Surveys], [Experiment], etc.): Critical to platform functionality. Do not recommend blocking, deleting, hiding, or modifying in response to generic cleanup.
Integration-prefixed data ([Appboy], [Adjust], [Intercom], etc.): Can be cleaned up, but recommend turning off at the integration source first. Lower priority than native events.
Experiment data: Do not recommend TTLs or automatic deletion. Deleting breaks historical experiment interpretation.
Interpreting Usage Signals
Query count reflects usage across user-created objects (charts, dashboards, notebooks, cohorts, metrics) but does NOT include AI tools, Chat, Global Agent, MCP, or Alerts. Zero-query is a strong signal to review, not a definitive signal to act.
Three key patterns:
| Pattern |
Definition |
Action |
| Stale event |
Has ingested before, but volume stopped |
Confirm with customer before deprecating |
| Test event |
first seen = last seen, single day |
Strong deprecation candidate; confirm first |
| Firing but unqueried |
Has volume, zero queries |
Flag for review, not immediate removal |
Safe to act on: No volume for 6-12 months. Even if query activity exists, those queries return zero results.
AI Readiness
Frame metadata and cleanup work as AI readiness improvements. Every AI feature selects events by evaluating the visible taxonomy — taxonomy quality directly determines AI output quality.
Flag these as AI quality issues:
- Cryptic event names with no description — AI cannot interpret them
- Clusters of duplicate/near-duplicate names — AI will guess incorrectly between them
- Implementation-focused descriptions (e.g., "fires when POST /purchase returns 200") — users ask behavioral questions, not backend questions
- Large numbers of deprecated events still visible — noise that increases wrong AI selection
Event description structure (in order):
- Non-technical behavior definition — what the user did, in plain language
- Trigger conditions — exact conditions, UI vs API, success-only or also failure, page/URL pattern
- Disambiguation — how this differs from similarly-named events
- Key use cases — if it's a funnel step, success metric, or key analysis input
- Frequently used properties — 2-3 most commonly queried properties with brief context
- Technical details (optional) — implementation notes, source system, endpoint
Property descriptions: Start with a clear definition, then include example values. Example: "The category of the product the user viewed. Examples: 'electronics', 'apparel', 'home & garden'."
AI readiness at instrumentation time:
- Choose clear, descriptive event and property names that don't require a display name to be interpretable. Do not recommend adding display names during instrumentation — they are only needed later when the raw name is already established and ambiguous.
- Write descriptions following the structure above: non-technical behavior definition → trigger conditions → disambiguation → key use cases → frequently used properties → optional technical details.
- For properties with coded values (SKUs, IDs, status codes): recommend creating lookup tables mapping codes to human-readable labels (available to Growth and Enterprise customers).
AI Controls recommendations:
- Organization context (10,000 char): company-wide standards, KPI definitions, standard terminology, global filters, fiscal calendar
- Project context (10,000 char): product-specific events/funnels, project-specific metrics, segment definitions
- Use audit findings to populate these recommendations. Recurring jargon or acronyms across multiple events belong in org/project context, not just individual descriptions. Consistent structural patterns (naming conventions, event groupings) are useful project context that helps AI interpret the taxonomy as a whole.
Layer 2: Rules by Action Type
When Reading and Analyzing (Always Safe)
Reading and analysis operations carry no risk — be autonomous and decisive. For tool usage
strategy and step-by-step procedures, see the Data Quality Audit procedure in the governance skill.
When Writing or Updating Metadata
Before/after confirmation required for all writes. Never auto-apply. Only update confirmed items — do not extend to similar items based on pattern inference.
Per-field defaults:
- Descriptions: Do not remove existing content unless clearly erroneous. Append to or incorporate existing detail.
- Categories: Only set when empty. Suggest changing only if clearly incorrect or user requests it.
- Tags: Add only; never remove without explicit request.
- Display names: Follow the project's existing naming conventions.
Restrictions:
- Do not write to bracket-prefixed or vendor-prefixed events unless explicitly requested.
- Never write to Unexpected or Deleted events (must be added to plan / restored first).
When writes fail due to permissions:
- Explain that the user lacks write access.
- Provide read-only guidance on what could be done and why.
- Offer an "Ask an Admin to apply this" summary the user can share.
When Recommending Cleanup or Deprecation
Deprecation must always follow a phased process. For the step-by-step procedure, see the governance skill's Deprecation Workflow.
Never:
- Present delete/hide/block as immediate one-step solutions
- Recommend sampling, TTLs, automatic deletion rules, or moving events between projects
- Recommend reconfiguring upstream integrations for volume control
- Skip dependency checks before recommending deprecation
When Recommending New Instrumentation
Event Naming Standards
Format: [Object] [Past-Tense Verb] in Title Case
| Good |
Bad |
Why |
Song Played |
Play Song |
Past tense = completed action |
Form Submitted |
Submit Form |
Noun-first = scannable, sortable |
Product Added |
product added, product_added, productAdded |
Amplitude treats different casings as separate events — always use Title Case, not snake_case or camelCase |
Consistency is the top priority. If an existing taxonomy uses a consistent convention that differs from the ideal, match the existing convention rather than introducing a new pattern.
User perspective, not system perspective:
Message Sent (user sent) not Message Delivered (system delivered)
Purchase Completed (user completed) not Payment Processed (system processed)
Specificity balance — one event + properties, not many events:
- Good:
Order Completed with property payment_method
- Bad:
Credit Card Order Completed, Apple Pay Order Completed
Cross-platform consistency: Same user action = same event name across Web, iOS, Android. Platform differences go in a platform property.
One action = one event name. No duplicates across the codebase.
Autocapture-first: Do not recommend custom events for anything already captured by Autocapture: Page Viewed, Element Clicked, Element Changed, Form Started, etc.
Property Naming Standards
snake_case for all property names
- Descriptive and specific:
payment_type not type, error_message not message
- Include units when ambiguous:
video_duration_seconds, file_size_mb, price_usd
- Timestamp convention:
[event_name]_at (e.g., product_added_at)
- Consistent across events: Same property name for the same concept everywhere.
product_name must be product_name on every event — not name, prod_name, etc.
- Distinct names for distinct concepts:
login_method and payment_method, not generic method for both
- Dot notation: Means a nested object was passed (Amplitude creates it automatically). Don't use dot notation in property names directly unless intending nested objects. During audits, a cluster of dot notation properties is a cleanup signal — check which are actually being queried. If a significant portion are unused, recommend trimming the object at the source to reduce taxonomy noise.
Property Type Standards
| Type |
Format |
Example |
| IDs |
Always string |
"user_id": "12345" not 12345 |
| Counts/amounts |
Number |
"order_total": 59.99 |
| Flags |
Boolean |
"is_premium": true |
| Timestamps |
ISO 8601 string |
"2024-03-10T14:30:00Z" |
| Enums/status |
String |
"status": "In Progress" |
| Null handling |
Pick one approach per property |
Omit, null, or sentinel string like "Unknown" — never mix. Using an explicit sentinel string lets you distinguish intentionally unavailable values from instrumentation bugs. Inconsistent null handling is one of the most common causes of incorrect property filters and broken funnels. |
User Identification Standards
- Anonymous users: Set
device_id only. Do NOT set user_id.
- Authenticated users: Set a unique, stable
user_id per verified user. Never set before login/verification.
- Server-side events: Include a unique
insert_id per event for deduplication (7-day window).
- Sessions: Use a consistent
session_id within a session; for server-side, use the UNIX timestamp of the first session event.
Structural Patterns
- A/B experiments: Track as list user properties, not events
- Errors: One
Error Encountered event with error_type/error_category property
- E-commerce: Use
product_engagement (items in this action) + cart_contents (full cart snapshot) arrays
- B2B: Instrument at least one group type (
org_id, account_id)
- Property consistency for funnels: Capture the same property (e.g.,
product_id) across all events in a funnel
Category Assignment
Use the Amplitude category metadata field — don't embed prefixes in event names. Common categories:
| Category |
Purpose |
Examples |
| Lifecycle |
User journey milestones |
Signup Completed, Trial Started, Subscription Cancelled |
| Feature |
Core product functionality |
Task Created, Document Edited, Report Generated |
| Engagement |
Navigation and UI interaction |
Page Viewed, Button Clicked, Search Performed |
| Transaction |
Revenue events |
Purchase Completed, Checkout Started, Refund Requested |
| System |
Technical health |
Error Occurred, API Request Completed, Timeout Occurred |
| Growth |
Acquisition and referral |
Invite Sent, Share Completed, Referral Reward Earned |
Assignment heuristics:
- If an event represents a first-time or milestone user action (signup, first purchase, first invite), prefer Lifecycle over Feature or Transaction.
- If an event records a click or view that is not a core product action, prefer Engagement over Feature.
- Integration-sourced events (
[Appboy], [Adjust], etc.) may not fit neatly — assign System or Growth based on the integration's purpose, or leave unassigned.
- When the correct category is ambiguous, ask the customer rather than guessing.
Scoring and Prioritizing Issues
Three dimensions:
1. Issue Impact
| Level |
Points |
Definition |
Examples |
| HIGH |
3 |
Name is ambiguous — analyst cannot reliably interpret it |
Jargon, acronyms, blob words, confusable names |
| MEDIUM |
2 |
Name is interpretable but taxonomy is messier for it |
Convention outliers, unexpected events not on plan |
| LOW |
1 |
Name is clear; issue is missing polish |
Missing description when name is self-explanatory |
2. Event Importance
- Query frequency: 30/60/90/180-day counts — high-query events affect more analyses
- Volume: High-volume = more cost and risk
- First seen: Very recent = validate early before issues compound
- Last seen: Distant = staleness signal
3. Effort
- Low: Metadata-only changes (descriptions, display names, categories, tags, hiding)
- Medium: Requires stakeholder validation or dependency checks
- High: Requires codebase changes or integration reconfiguration
Prioritization: Lead with high-impact issues on high-importance events. Stale/test events are quick wins — surface them below real data quality problems.
Health grade: (Total Points Earned / Total Points Possible) x 100%
- 0-49%: Needs Improvement
- 50-79%: Meets Expectations
- 80-100%: Exceeds Expectations
Authority Boundaries (Metadata-Only)
Allowed (non-destructive, metadata-only, with user approval):
- Update display names, descriptions, categories, tags
- Set official status
- Hide events (NOT block or delete)
- Set up Automated Tasks
- Add AI Context to project settings
Not allowed:
- Blocking, deleting, merging, or transforming events
- Block/Drop filters
- Modifying ingestion pipelines or upstream integrations
- Sampling strategies of any kind
Layer 3: Detection Reference
Detection Signals and Thresholds
Default lookback: 180 days.
| Signal |
Priority |
Action |
| Semantically unclear name |
HIGH |
Add display name + description |
| Missing description (unclear name) |
HIGH |
Add description following AI readiness formula |
| Semantic duplicate (true — same meaning, different casing) |
HIGH |
Merge or disambiguate |
| Semantic duplicate (similar — different names, same action) |
HIGH |
Investigate; merge or disambiguate |
| Zero volume (180 days) |
MEDIUM |
Investigate before acting |
| Zero queries (180 days) |
MEDIUM |
Check asset dependencies first |
| Duplicate property across event + user scope |
MEDIUM |
Clarify correct source of truth |
| Missing description (clear name) |
LOW |
Add description; deprioritize |
| Missing category |
LOW |
Add category |
| Naming convention outlier |
LOW |
Flag for future realignment |
| Unexpected event/property |
LOW |
Add to plan or block after review |
| Stale (last seen beyond lookback) |
LOW |
Quick win — schedule for deprecation |
| Single-day (first seen = last seen) |
LOW |
Quick win — likely test; verify first |
Test/QA artifact (test_, debug_, tmp_, _qa) |
LOW |
Quick win — standard deprecation process |
Exception: When customer is near quota, Stale/Single-day/Test signals become elevated priority.
Key Audit Metrics
| Metric |
Impact |
| % of types at quota limit |
HIGH when >90% |
| New types added in last 7 days (spike = possible dynamic value leak) |
HIGH if spike |
| Total event volume change in last 7 days |
HIGH if unexpected |
| Number of duplicate types by name |
HIGH |
| Group types not instrumented (B2B products) |
HIGH |
| A/B experiments tracked as events instead of user properties |
MEDIUM |
| Events with zero queries in 180 days |
MEDIUM |
| Events with zero volume in 180 days |
MEDIUM |
| Single-day events |
MEDIUM |
| % of live events with descriptions |
LOW |
| % of live events with categories |
LOW |
| Number of Unexpected events/properties |
LOW |
| Naming convention inconsistencies |
LOW |
Good vs. Bad Metadata Examples
Display names:
| Before |
After |
catSelectClick |
Category Selected |
pgVw |
Page Viewed |
ord_compl_v2 |
Order Completed |
usr_prop_acct_tier |
Account Tier |
Descriptions:
| Bad (implementation-focused) |
Good (intent + context) |
| "Fired on click handler for nav component" |
"Triggered when a customer selects a product category from the navigation menu. Example categories: Electronics, Apparel, Home." |
| "Event fired on submit" |
"Triggered when a user completes checkout and confirms their order. Includes all line items, discounts applied, and final order total." |
| "See tracking plan" |
"Fired the first time a new user completes onboarding by verifying their email. Fires once per user lifetime only." |
Amplitude MCP capability selection
Inspect the connected public Amplitude MCP catalog at runtime. Tool names and
wrappers can change or be exposed differently during a rollout, so select
capabilities from their advertised descriptions and schemas instead of relying
on names recorded in this skill.
Context and discovery
- Use the project-context capability to discover accessible project IDs and
read the selected project's settings. Ask the user to choose when more than
one project is available; never infer an ID from a project name.
- Use taxonomy search for event and property discovery when exposed; otherwise
filter and paginate the active taxonomy reader. Use entity search for charts,
dashboards, notebooks, experiments, cohorts, and saved content.
- Before any write, use the workspace or branch capability to inspect approval
requirements, branch protection, permissions, and current branches.
Taxonomy reads
- Prefer the consolidated taxonomy reader when the catalog exposes one. Use
its advertised discriminator to select raw events, custom/labeled events,
event properties, user properties, group properties, derived properties,
lookups, channels, or persisted properties.
- If the catalog exposes separate event or property readers, use only their
documented filters and pagination fields. Do not invent an alias or copy
parameters from another reader.
- Resolve event and property names from returned taxonomy rows. Names are
case-sensitive; do not substitute display names.
- Paginate exhaustive reads through every cursor. When the response reports a
total, reconcile it with the accumulated rows; otherwise require the reader's
documented terminal-cursor condition. A failed or partial page is not
completion.
- Use the available transformation reader when auditing event/property merges,
value mappings, or other cleaning rules.
Metadata updates
- Select the event or property mutation capability only after verifying that
its current schema supports the requested object type, metadata fields,
branch selector, and scope.
- Read the exact current object first. Update only explicitly confirmed fields,
preserve existing descriptions unless the user asks to replace them, and do
not infer unsupported parameters from an older tool version.
- Event-property metadata can be global or scoped to one event. Use the
schema's explicit scope control; never assume omission means global unless
the current schema documents it.
- Custom/labeled event definitions are full replacements, not merges. Pass the
complete verified definition and warn that renames can break references.
- Never update bracket-prefixed or vendor-prefixed system events unless the
user explicitly requests it.
- Require explicit confirmation before any write and honor tracking-plan write
permissions and branch protection.
Workflows
For step-by-step execution procedures (data quality audits, governance analyses, event verification,
deprecation workflows, tracking plan generation, tool usage strategy), see the governance skill.
1---
2name: taxonomy
3description: >
4 Source of truth for event taxonomy generation, data auditing, and governance best practices
5 in Amplitude. Use when an agent needs to create, validate, audit, score, or recommend
6 improvements to event tracking plans, naming conventions, property standards, data quality,
7 or deprecation workflows. Covers naming rules, property standards, scoring frameworks,
8 safe metadata operations, deprecation procedures, and AI readiness guidance.
9metadata:
10 source: https://skillmd.com/skills/amplitude/taxonomy
11---
12
13# Taxonomy Generation & Data Auditing
14
15## When to Use
16
17- User asks to create or review a tracking plan or event taxonomy
18- User wants to validate event/property naming conventions
19- User needs to audit data quality (duplicates, stale events, missing metadata)
20- User asks about funnel design or event relationships
21- Agent is generating event names or property names and needs to follow standards
22- User wants to understand or improve their taxonomy governance
23- User asks about reducing event volume or type counts
24- User asks about deprecation, blocking, deleting, or hiding events
25- Any agent needs a "source of truth" for taxonomy best practices before recommending events
26- User asks about AI readiness, AI Controls, or improving AI feature accuracy
27
28---
29
30# Layer 1: Foundational Concepts
31
32## Core Philosophy
33
34Six principles govern all taxonomy work:
35
361. **Evidence-first. Never fabricate.** Every finding must be grounded in tool-retrieved data. If something cannot be verified, say so explicitly.
372. **Scan aggressively. Propose confidently. Confirm before writing.** Paginate autonomously through the full taxonomy. Form a prioritized, opinionated view of what needs fixing — then present it. Never call a write tool without explicit user confirmation.
383. **Be opinionated, not neutral.** Generic requests ("audit my taxonomy") are an invitation to lead. Use the scoring framework, recommend the highest-impact action first, and explain why. Don't present a menu of equal options.
394. **Surface critical issues proactively.** If you find something important while working on an adjacent task, raise it. Don't silently ignore a PII violation because the user only asked about naming conventions.
405. **Questions extract institutional knowledge.** Ask about business intent and real-world meaning, not Amplitude mechanics. One focused question at a time. The goal is to surface knowledge that lives in people's heads.
416. **Explain before acting.** Before calling any write tool, present exact proposed changes — including before/after state — and wait for explicit confirmation.
42
43## Data Quality Lifecycle
44
45All taxonomy governance follows a four-stage loop:
46
471. **Detect** — Scan systematically. Paginate through the full taxonomy. Score every finding. Surface issues with evidence before conclusions.
482. **Clarify** — Ask one focused question to capture semantic truth. Do not suggest actions yet. Seek understanding first.
493. **Resolve** — Apply metadata-only improvements. Guide humans through phased deprecation for structural changes. Never execute destructive actions unilaterally.
504. **Prevent** — Recommend conventions and governance habits that stop drift from recurring.
51
52## Event Volume vs. Taxonomy Type Counts
53
54These are **different problems** requiring **different solutions**:
55
56- **Event volume** = total event instances ingested per billing period (how many times events fire). Properties do not count toward volume.
57- **Taxonomy type counts** = number of distinct names across all schema dimensions (event types, event property types, user property types, group types, group property types). Each has its own limit.
58
59**Billing models — know which applies before advising:**
60- **Event volume billing**: customer has a contracted allocation of events per period. Exceeding it triggers overage costs. Flag significant event volume changes to these customers.
61- **MTU billing**: customer is billed based on distinct users who trigger any event in a month. Per-user event counts matter less; total unique user count matters more.
62
63**What customers usually mean:**
64- "I need to reduce my event volume" → worried about billing (volume-billed customers)
65- "I need to reduce my event types / schema count" → worried about hitting type limits (new types won't be queryable)
66
67**What actually reduces each:**
68
69| Goal | Action | Reduces Volume? | Reduces Type Count? |
70|------|--------|:---:|:---:|
71| Reduce volume | Block event | Yes | No |
72| Reduce volume | Delete event | Yes | Yes |
73| Reduce type count | Delete event/property/group type | — | Yes |
74| Reduce type count | Block event | No | **No** |
75| Reduce type count | Hide event | No | **No** |
76
77**Key rules:**
78- Blocking and hiding do NOT reduce type count. A quota-constrained customer must delete, not block.
79- **Never recommend sampling.** Sampling breaks funnel charts, journey paths, cohorts, downstream destinations, and Guides.
80- Custom events and merged events simplify analysis but do NOT reduce raw event volume.
81- When ambiguous, ask: "Are you trying to reduce how many events are being sent, or the number of different event and property types in your taxonomy?"
82
83## Event States and Metadata Permissions
84
85| Status | Meaning | Can Edit Metadata? |
86|--------|---------|:---:|
87| Planned | In tracking plan; not yet instrumented | Yes |
88| Live | Actively receiving data | Yes |
89| Blocked | Stops new ingestion; historical data accessible | Yes |
90| Unexpected | Receiving data but NOT in tracking plan | **No** — must add to tracking plan first |
91| Deleted | Stops ingestion; removed from new-chart dropdowns | **No** — must restore first |
92
93**Unexpected events have special restrictions.** No metadata can be updated until the event is added to the tracking plan. When you encounter Unexpected events:
94- If they appear legitimate (real product actions, consistent volume): recommend adding to the tracking plan first, then apply metadata.
95- If they appear invalid (single-day spikes, test strings, security scan artifacts): treat as a deprecation candidate through the standard safe deprecation process. Always distinguish "legitimate but undocumented" from "truly invalid" before recommending any action.
96
97**Activity state is NOT a deprecation signal.** An event marked Inactive is behaving as intended.
98
99**Actual deprecation signals:**
100
101| Signal | Interpretation |
102|--------|----------------|
103| No recent volume | Event has gone stale |
104| No recent queries | Event is unused |
105| **Both together** | **Strong deprecation candidate** |
106
107**Planned events:** Zero volume and queries are expected — evaluate by age, name collisions with Live events, and test-like names instead.
108
109## Custom Events, Labeled Events, and Merged Events
110
111None reduce event volume. Each has distinct behavior:
112
113- **Custom events** (`ce:` prefix, type = custom): Logical combinations of underlying events for analysis convenience. The underlying events still exist and fire independently. Always check whether an event is used as the basis for a custom event before recommending its deletion — deleting the underlying event may break the custom event silently. Allowed: consolidate duplicate custom events with the same definition; improve naming, descriptions, categories, tags. Never claim that removing a custom event reduces event volume.
114- **Labeled events** (`ce:` prefix, type = labeled): Designed for use with Autocapture, distinguished from custom events by a separate metadata flag. Adding/deleting does not impact volume.
115- **Merged events** (Transform/Merge): Source events are no longer individually available for analysis after a merge. If the user needs to analyze combined events AND retain independent analysis of source events, recommend a **custom event** instead of a merge. Allowed: merge truly duplicated events that share the same semantics and where independent analysis is not needed. Never claim that merging reduces event volume.
116
117## Protected Data Categories
118
119**How to identify category from naming convention:** Events with bracket prefixes (`[...]`) follow a consistent pattern: if the text inside the brackets is a recognizable third-party product brand, it is an integration. If not, it is an Amplitude system event.
120
121**Amplitude system events** (`[Amplitude]`, `[Guides-Surveys]`, `[Experiment]`, etc.): Critical to platform functionality. Do not recommend blocking, deleting, hiding, or modifying in response to generic cleanup.
122
123**Integration-prefixed data** (`[Appboy]`, `[Adjust]`, `[Intercom]`, etc.): Can be cleaned up, but recommend turning off at the integration source first. Lower priority than native events.
124
125**Experiment data:** Do not recommend TTLs or automatic deletion. Deleting breaks historical experiment interpretation.
126
127## Interpreting Usage Signals
128
129**Query count** reflects usage across user-created objects (charts, dashboards, notebooks, cohorts, metrics) but does NOT include AI tools, Chat, Global Agent, MCP, or Alerts. Zero-query is a strong signal to review, not a definitive signal to act.
130
131**Three key patterns:**
132
133| Pattern | Definition | Action |
134|---------|------------|--------|
135| Stale event | Has ingested before, but volume stopped | Confirm with customer before deprecating |
136| Test event | first seen = last seen, single day | Strong deprecation candidate; confirm first |
137| Firing but unqueried | Has volume, zero queries | Flag for review, not immediate removal |
138
139**Safe to act on:** No volume for 6-12 months. Even if query activity exists, those queries return zero results.
140
141## AI Readiness
142
143Frame metadata and cleanup work as AI readiness improvements. Every AI feature selects events by evaluating the visible taxonomy — taxonomy quality directly determines AI output quality.
144
145**Flag these as AI quality issues:**
146- Cryptic event names with no description — AI cannot interpret them
147- Clusters of duplicate/near-duplicate names — AI will guess incorrectly between them
148- Implementation-focused descriptions (e.g., "fires when POST /purchase returns 200") — users ask behavioral questions, not backend questions
149- Large numbers of deprecated events still visible — noise that increases wrong AI selection
150
151**Event description structure (in order):**
1521. Non-technical behavior definition — what the user did, in plain language
1532. Trigger conditions — exact conditions, UI vs API, success-only or also failure, page/URL pattern
1543. Disambiguation — how this differs from similarly-named events
1554. Key use cases — if it's a funnel step, success metric, or key analysis input
1565. Frequently used properties — 2-3 most commonly queried properties with brief context
1576. Technical details (optional) — implementation notes, source system, endpoint
158
159**Property descriptions:** Start with a clear definition, then include example values. Example: *"The category of the product the user viewed. Examples: 'electronics', 'apparel', 'home & garden'."*
160
161**AI readiness at instrumentation time:**
162- Choose clear, descriptive event and property names that don't require a display name to be interpretable. Do not recommend adding display names during instrumentation — they are only needed later when the raw name is already established and ambiguous.
163- Write descriptions following the structure above: non-technical behavior definition → trigger conditions → disambiguation → key use cases → frequently used properties → optional technical details.
164- For properties with coded values (SKUs, IDs, status codes): recommend creating lookup tables mapping codes to human-readable labels (available to Growth and Enterprise customers).
165
166**AI Controls recommendations:**
167- **Organization context** (10,000 char): company-wide standards, KPI definitions, standard terminology, global filters, fiscal calendar
168- **Project context** (10,000 char): product-specific events/funnels, project-specific metrics, segment definitions
169- Use audit findings to populate these recommendations. Recurring jargon or acronyms across multiple events belong in org/project context, not just individual descriptions. Consistent structural patterns (naming conventions, event groupings) are useful project context that helps AI interpret the taxonomy as a whole.
170
171---
172
173# Layer 2: Rules by Action Type
174
175## When Reading and Analyzing (Always Safe)
176
177Reading and analysis operations carry no risk — be autonomous and decisive. For tool usage
178strategy and step-by-step procedures, see the Data Quality Audit procedure in the governance skill.
179
180## When Writing or Updating Metadata
181
182**Before/after confirmation required for all writes.** Never auto-apply. Only update confirmed items — do not extend to similar items based on pattern inference.
183
184**Per-field defaults:**
185- **Descriptions:** Do not remove existing content unless clearly erroneous. Append to or incorporate existing detail.
186- **Categories:** Only set when empty. Suggest changing only if clearly incorrect or user requests it.
187- **Tags:** Add only; never remove without explicit request.
188- **Display names:** Follow the project's existing naming conventions.
189
190**Restrictions:**
191- Do not write to bracket-prefixed or vendor-prefixed events unless explicitly requested.
192- Never write to Unexpected or Deleted events (must be added to plan / restored first).
193
194**When writes fail due to permissions:**
195- Explain that the user lacks write access.
196- Provide read-only guidance on what could be done and why.
197- Offer an "Ask an Admin to apply this" summary the user can share.
198
199## When Recommending Cleanup or Deprecation
200
201Deprecation must always follow a phased process. For the step-by-step procedure, see the governance skill's Deprecation Workflow.
202
203**Never:**
204- Present delete/hide/block as immediate one-step solutions
205- Recommend sampling, TTLs, automatic deletion rules, or moving events between projects
206- Recommend reconfiguring upstream integrations for volume control
207- Skip dependency checks before recommending deprecation
208
209## When Recommending New Instrumentation
210
211### Event Naming Standards
212
213**Format: `[Object] [Past-Tense Verb]` in Title Case**
214
215| Good | Bad | Why |
216|------|-----|-----|
217| `Song Played` | `Play Song` | Past tense = completed action |
218| `Form Submitted` | `Submit Form` | Noun-first = scannable, sortable |
219| `Product Added` | `product added`, `product_added`, `productAdded` | Amplitude treats different casings as separate events — always use Title Case, not snake_case or camelCase |
220
221**Consistency is the top priority.** If an existing taxonomy uses a consistent convention that differs from the ideal, match the existing convention rather than introducing a new pattern.
222
223**User perspective, not system perspective:**
224- `Message Sent` (user sent) not `Message Delivered` (system delivered)
225- `Purchase Completed` (user completed) not `Payment Processed` (system processed)
226
227**Specificity balance — one event + properties, not many events:**
228- **Good**: `Order Completed` with property `payment_method`
229- **Bad**: `Credit Card Order Completed`, `Apple Pay Order Completed`
230
231**Cross-platform consistency:** Same user action = same event name across Web, iOS, Android. Platform differences go in a `platform` property.
232
233**One action = one event name.** No duplicates across the codebase.
234
235**Autocapture-first:** Do not recommend custom events for anything already captured by Autocapture: `Page Viewed`, `Element Clicked`, `Element Changed`, `Form Started`, etc.
236
237### Property Naming Standards
238
239- **`snake_case`** for all property names
240- **Descriptive and specific:** `payment_type` not `type`, `error_message` not `message`
241- **Include units when ambiguous:** `video_duration_seconds`, `file_size_mb`, `price_usd`
242- **Timestamp convention:** `[event_name]_at` (e.g., `product_added_at`)
243- **Consistent across events:** Same property name for the same concept everywhere. `product_name` must be `product_name` on every event — not `name`, `prod_name`, etc.
244- **Distinct names for distinct concepts:** `login_method` and `payment_method`, not generic `method` for both
245- **Dot notation:** Means a nested object was passed (Amplitude creates it automatically). Don't use dot notation in property names directly unless intending nested objects. During audits, a cluster of dot notation properties is a cleanup signal — check which are actually being queried. If a significant portion are unused, recommend trimming the object at the source to reduce taxonomy noise.
246
247### Property Type Standards
248
249| Type | Format | Example |
250|------|--------|---------|
251| IDs | Always string | `"user_id": "12345"` not `12345` |
252| Counts/amounts | Number | `"order_total": 59.99` |
253| Flags | Boolean | `"is_premium": true` |
254| Timestamps | ISO 8601 string | `"2024-03-10T14:30:00Z"` |
255| Enums/status | String | `"status": "In Progress"` |
256| Null handling | Pick one approach per property | Omit, `null`, or sentinel string like `"Unknown"` — never mix. Using an explicit sentinel string lets you distinguish intentionally unavailable values from instrumentation bugs. Inconsistent null handling is one of the most common causes of incorrect property filters and broken funnels. |
257
258### User Identification Standards
259
260- **Anonymous users:** Set `device_id` only. Do NOT set `user_id`.
261- **Authenticated users:** Set a unique, stable `user_id` per verified user. Never set before login/verification.
262- **Server-side events:** Include a unique `insert_id` per event for deduplication (7-day window).
263- **Sessions:** Use a consistent `session_id` within a session; for server-side, use the UNIX timestamp of the first session event.
264
265### Structural Patterns
266
267- **A/B experiments:** Track as list user properties, not events
268- **Errors:** One `Error Encountered` event with `error_type`/`error_category` property
269- **E-commerce:** Use `product_engagement` (items in this action) + `cart_contents` (full cart snapshot) arrays
270- **B2B:** Instrument at least one group type (`org_id`, `account_id`)
271- **Property consistency for funnels:** Capture the same property (e.g., `product_id`) across all events in a funnel
272
273### Category Assignment
274
275Use the Amplitude category metadata field — don't embed prefixes in event names. Common categories:
276
277| Category | Purpose | Examples |
278|----------|---------|---------|
279| Lifecycle | User journey milestones | Signup Completed, Trial Started, Subscription Cancelled |
280| Feature | Core product functionality | Task Created, Document Edited, Report Generated |
281| Engagement | Navigation and UI interaction | Page Viewed, Button Clicked, Search Performed |
282| Transaction | Revenue events | Purchase Completed, Checkout Started, Refund Requested |
283| System | Technical health | Error Occurred, API Request Completed, Timeout Occurred |
284| Growth | Acquisition and referral | Invite Sent, Share Completed, Referral Reward Earned |
285
286**Assignment heuristics:**
287- If an event represents a first-time or milestone user action (signup, first purchase, first invite), prefer **Lifecycle** over Feature or Transaction.
288- If an event records a click or view that is not a core product action, prefer **Engagement** over Feature.
289- Integration-sourced events (`[Appboy]`, `[Adjust]`, etc.) may not fit neatly — assign System or Growth based on the integration's purpose, or leave unassigned.
290- When the correct category is ambiguous, ask the customer rather than guessing.
291
292## Scoring and Prioritizing Issues
293
294Three dimensions:
295
296### 1. Issue Impact
297
298| Level | Points | Definition | Examples |
299|-------|--------|------------|---------|
300| HIGH | 3 | Name is ambiguous — analyst cannot reliably interpret it | Jargon, acronyms, blob words, confusable names |
301| MEDIUM | 2 | Name is interpretable but taxonomy is messier for it | Convention outliers, unexpected events not on plan |
302| LOW | 1 | Name is clear; issue is missing polish | Missing description when name is self-explanatory |
303
304### 2. Event Importance
305
306- **Query frequency:** 30/60/90/180-day counts — high-query events affect more analyses
307- **Volume:** High-volume = more cost and risk
308- **First seen:** Very recent = validate early before issues compound
309- **Last seen:** Distant = staleness signal
310
311### 3. Effort
312
313- **Low:** Metadata-only changes (descriptions, display names, categories, tags, hiding)
314- **Medium:** Requires stakeholder validation or dependency checks
315- **High:** Requires codebase changes or integration reconfiguration
316
317**Prioritization:** Lead with high-impact issues on high-importance events. Stale/test events are quick wins — surface them below real data quality problems.
318
319**Health grade:** (Total Points Earned / Total Points Possible) x 100%
320- 0-49%: Needs Improvement
321- 50-79%: Meets Expectations
322- 80-100%: Exceeds Expectations
323
324## Authority Boundaries (Metadata-Only)
325
326**Allowed (non-destructive, metadata-only, with user approval):**
327- Update display names, descriptions, categories, tags
328- Set official status
329- Hide events (NOT block or delete)
330- Set up Automated Tasks
331- Add AI Context to project settings
332
333**Not allowed:**
334- Blocking, deleting, merging, or transforming events
335- Block/Drop filters
336- Modifying ingestion pipelines or upstream integrations
337- Sampling strategies of any kind
338
339---
340
341# Layer 3: Detection Reference
342
343## Detection Signals and Thresholds
344
345Default lookback: **180 days**.
346
347| Signal | Priority | Action |
348|--------|----------|--------|
349| Semantically unclear name | HIGH | Add display name + description |
350| Missing description (unclear name) | HIGH | Add description following AI readiness formula |
351| Semantic duplicate (true — same meaning, different casing) | HIGH | Merge or disambiguate |
352| Semantic duplicate (similar — different names, same action) | HIGH | Investigate; merge or disambiguate |
353| Zero volume (180 days) | MEDIUM | Investigate before acting |
354| Zero queries (180 days) | MEDIUM | Check asset dependencies first |
355| Duplicate property across event + user scope | MEDIUM | Clarify correct source of truth |
356| Missing description (clear name) | LOW | Add description; deprioritize |
357| Missing category | LOW | Add category |
358| Naming convention outlier | LOW | Flag for future realignment |
359| Unexpected event/property | LOW | Add to plan or block after review |
360| Stale (last seen beyond lookback) | LOW | Quick win — schedule for deprecation |
361| Single-day (first seen = last seen) | LOW | Quick win — likely test; verify first |
362| Test/QA artifact (`test_`, `debug_`, `tmp_`, `_qa`) | LOW | Quick win — standard deprecation process |
363
364**Exception:** When customer is near quota, Stale/Single-day/Test signals become elevated priority.
365
366## Key Audit Metrics
367
368| Metric | Impact |
369|--------|--------|
370| % of types at quota limit | HIGH when >90% |
371| New types added in last 7 days (spike = possible dynamic value leak) | HIGH if spike |
372| Total event volume change in last 7 days | HIGH if unexpected |
373| Number of duplicate types by name | HIGH |
374| Group types not instrumented (B2B products) | HIGH |
375| A/B experiments tracked as events instead of user properties | MEDIUM |
376| Events with zero queries in 180 days | MEDIUM |
377| Events with zero volume in 180 days | MEDIUM |
378| Single-day events | MEDIUM |
379| % of live events with descriptions | LOW |
380| % of live events with categories | LOW |
381| Number of Unexpected events/properties | LOW |
382| Naming convention inconsistencies | LOW |
383
384## Good vs. Bad Metadata Examples
385
386**Display names:**
387
388| Before | After |
389|--------|-------|
390| `catSelectClick` | `Category Selected` |
391| `pgVw` | `Page Viewed` |
392| `ord_compl_v2` | `Order Completed` |
393| `usr_prop_acct_tier` | `Account Tier` |
394
395**Descriptions:**
396
397| Bad (implementation-focused) | Good (intent + context) |
398|------------------------------|------------------------|
399| "Fired on click handler for nav component" | "Triggered when a customer selects a product category from the navigation menu. Example categories: Electronics, Apparel, Home." |
400| "Event fired on submit" | "Triggered when a user completes checkout and confirms their order. Includes all line items, discounts applied, and final order total." |
401| "See tracking plan" | "Fired the first time a new user completes onboarding by verifying their email. Fires once per user lifetime only." |
402
403---
404
405# Amplitude MCP capability selection
406
407Inspect the connected public Amplitude MCP catalog at runtime. Tool names and
408wrappers can change or be exposed differently during a rollout, so select
409capabilities from their advertised descriptions and schemas instead of relying
410on names recorded in this skill.
411
412## Context and discovery
413
414- Use the project-context capability to discover accessible project IDs and
415 read the selected project's settings. Ask the user to choose when more than
416 one project is available; never infer an ID from a project name.
417- Use taxonomy search for event and property discovery when exposed; otherwise
418 filter and paginate the active taxonomy reader. Use entity search for charts,
419 dashboards, notebooks, experiments, cohorts, and saved content.
420- Before any write, use the workspace or branch capability to inspect approval
421 requirements, branch protection, permissions, and current branches.
422
423## Taxonomy reads
424
425- Prefer the consolidated taxonomy reader when the catalog exposes one. Use
426 its advertised discriminator to select raw events, custom/labeled events,
427 event properties, user properties, group properties, derived properties,
428 lookups, channels, or persisted properties.
429- If the catalog exposes separate event or property readers, use only their
430 documented filters and pagination fields. Do not invent an alias or copy
431 parameters from another reader.
432- Resolve event and property names from returned taxonomy rows. Names are
433 case-sensitive; do not substitute display names.
434- Paginate exhaustive reads through every cursor. When the response reports a
435 total, reconcile it with the accumulated rows; otherwise require the reader's
436 documented terminal-cursor condition. A failed or partial page is not
437 completion.
438- Use the available transformation reader when auditing event/property merges,
439 value mappings, or other cleaning rules.
440
441## Metadata updates
442
443- Select the event or property mutation capability only after verifying that
444 its current schema supports the requested object type, metadata fields,
445 branch selector, and scope.
446- Read the exact current object first. Update only explicitly confirmed fields,
447 preserve existing descriptions unless the user asks to replace them, and do
448 not infer unsupported parameters from an older tool version.
449- Event-property metadata can be global or scoped to one event. Use the
450 schema's explicit scope control; never assume omission means global unless
451 the current schema documents it.
452- Custom/labeled event definitions are full replacements, not merges. Pass the
453 complete verified definition and warn that renames can break references.
454- Never update bracket-prefixed or vendor-prefixed system events unless the
455 user explicitly requests it.
456- Require explicit confirmation before any write and honor tracking-plan write
457 permissions and branch protection.
458
459---
460
461# Workflows
462
463For step-by-step execution procedures (data quality audits, governance analyses, event verification,
464deprecation workflows, tracking plan generation, tool usage strategy), see the **governance** skill.