Verb AI Query Cookbook

Learn what you can do with Verb AI MCP tools.

Verb AI MCP Query Guide

How to Transform Business Questions into Effective Data Queries

---

Overview

The Verb AI MCP provides access to real-time behavioral data from a compensated panel of 2,000+ US-based users (ages 21–34, skewing female). The data captures what people actually do on their devices — not what they say they do.

The key principle: The MCP answers objective, data-level questions well. It does not answer subjective or interpretive questions directly. Your job is to decompose business questions into structured queries the system can execute, then synthesize the results.

---

Database Schema

Every event table links to AGENT_SYNC via USER_ID (or USER_IDENTIFIER for network traffic).

---

1. AGENT_SYNC — User Demographics

The panel's demographic backbone. Join this to any event table to segment behaviors by audience.

Column	Type	Description
USER_ID	PK	Unique user identifier. Links to all event tables.
DATE_OF_BIRTH / YEAR_OF_BIRTH	Date/Int	Use for age segmentation. Panel is 21–34.
GENDER	String	Values: Female, Male, Non-binary, Prefer not to say
HOUSEHOLD_INCOME	Numeric	Annual USD. Brackets: $1–50K, $50–100K, $100K+
EDUCATION_LEVEL	String	Highest completed (High School → Master's+)
EMPLOYMENT_STATUS	String	Full-time, Part-time, Student, Unemployed, Self-employed
MARITAL_STATUS	String	Single, Married, etc.
COUNTRY_OF_RESIDENCE	String	Currently 100% US
FULL_ADDRESS	String	Street-level address. Use for state/city extraction.
CITIZENSHIP / COUNTRY_OF_BIRTH	String	Origin demographics
RACE	String	Racial/ethnic background

Common patterns:

• Age calculation: YEAR(CURRENT_DATE) - YEAR_OF_BIRTH

• State extraction: Parse from FULL_ADDRESS

• Income brackets: GROUP BY ranges of HOUSEHOLD_INCOME

---

2. PRODUCT_EVENTS_FLAT_DYM — E-commerce Interactions

The richest table for purchase funnel analysis. Captures views, cart adds, and purchases across all e-commerce platforms.

Column	Type	Description
USER_ID	FK	Links to AGENT_SYNC
ACTION	String	Critical field. Values: viewed, added_to_cart, purchased
PRODUCT_NAME	String	Full product name as displayed on retailer site
BRAND	String	Brand name (may be NULL — check PRODUCT_NAME too)
CATEGORY	String	Product category from the retailer's taxonomy
PRICE	Numeric	Listed price at time of interaction
CURRENCY	String	Usually USD
DESCRIPTION	String	Full product description text. Use for keyword filtering.
PRODUCT_URL / PAGE_URL	String	Source URL. Extract retailer domain from this.
PROMOTION	String	Any active promotion text (coupons, BOGO, rebates)
RATINGS	Numeric	Product star rating
REVIEWS_COUNT	Numeric	Number of reviews
FEATURES	String	Product feature list
AVAILABILITY	String	In-stock status
IMAGE_URLS	String	Product images
PRODUCT_ID	String	Retailer's product identifier
EVENT_TIME	Timestamp	When the interaction happened
CREATE_TIME	Timestamp	When the record was created

Critical notes:

• ACTION is the funnel stage indicator. Always filter or group by this.

• BRAND is often NULL. Search PRODUCT_NAME and DESCRIPTION with ILIKE for brand detection.

• PAGE_URL tells you which retailer (Amazon, Target, Instacart, DoorDash, etc.)

• PROMOTION captures deal text — useful for understanding price sensitivity.

---

3. SEARCH_EVENTS_FLAT_DYM — Search Activity

Captures every search query across Google, Bing, YouTube, and other engines. The best table for understanding intent and discovery.

Column	Type	Description
USER_ID	FK	Links to AGENT_SYNC
QUERY	String	The actual search terms typed. Most valuable field.
SEARCH_ENGINE	String	google, bing, youtube, other
RESULTS_COUNT	Numeric	Number of results returned
RESULTS_DESCRIPTION	String	Summary of top results
PAGE_URL	String	Search results page URL
LANGUAGE	String	Interface language
EVENT_TYPE	String	Search event classification
EVENT_TIME	Timestamp	When the search happened

Critical notes:

• QUERY is case-sensitive in some contexts — always use ILIKE for matching.

• For topic analysis, use keyword patterns: QUERY ILIKE '%white claw%' or QUERY ILIKE '%ramen%'

• Combine with time windows to see search-to-action sequences.

---

4. YOUTUBE_EVENTS_FLAT_DYM — YouTube Interactions

Captures video views, including full metadata about what panelists watch.

Column	Type	Description
USER_ID	FK	Links to AGENT_SYNC
SNIPPET_TITLE / API_TITLE	String	Video title. Use for content categorization.
CHANNEL_TITLE / CHANNEL_ID	String	Creator/channel info
DESCRIPTION_SNIPPET / DESCRIPTION_TOP_LEVEL	String	Video description text
VIEW_COUNT	Numeric	Total video views (public metric)
LIKE_COUNT	Numeric	Total likes on the video
COMMENT_COUNT	Numeric	Total comments
TAGS	String	Video keyword tags
CATEGORY_ID	String	YouTube category
DURATION_ISO8601	String	Video length (ISO format, e.g., PT10M30S)
VIDEO_ID / API_VIDEO_ID	String	YouTube video identifier
PAGE_URL	String	Full YouTube URL
GEO_CITY / GEO_COUNTRY_NAME / GEO_REGION	String	Viewer location
PUBLISHED_AT	Timestamp	When the video was published
EVENT_TIME	Timestamp	When the panelist watched it

Critical notes:

• VIEW_COUNT and LIKE_COUNT are the video's total public metrics, not the panelist's personal view count. Use COUNT of events per user for panelist engagement.

• For creator tier analysis, use VIEW_COUNT as a proxy for creator size.

• TAGS and DESCRIPTION_SNIPPET are valuable for content topic classification.

---

5. NETWORK_TRAFFIC_EVENTS_DYM — Network Traffic

Raw domain-level traffic. Shows which apps and websites panelists access.

Column	Type	Description
USER_IDENTIFIER	FK	Links to AGENT_SYNC.USER_ID (note: different column name)
SNI	String	Server Name Indication — the domain being accessed

Critical notes:

• This is the most granular but least structured table. It shows raw domain hits.

• Use SNI with ILIKE to detect app/platform usage: SNI ILIKE '%instagram%', SNI ILIKE '%tiktok%'

• Best for: understanding which platforms users are on before/after other events, mapping media exposure pathways.

• High volume table — always filter by time and user segments.

---

6. NEWS_EVENTS_FLAT_DYM — News Interactions

Captures news article consumption and engagement.

Column	Type	Description
USER_ID	FK	Links to AGENT_SYNC
ARTICLE_URL / PAGE_URL	String	Article URL
NEWS_OUTLET	String	Publishing organization
AUTHOR	String	Article author
CONTENT_SUMMARY	String	Article summary text
KEYWORDS	String	Topic keywords
NEWS_TYPE	String	Content category
COMMENTS_COUNT / LIKES	Numeric	Engagement metrics
LANGUAGE	String	Content language
GEO_*	Various	Geographic location fields
PUBLICATION_DATE / EVENT_TIME	Timestamp	When published / when read

---

7. REDDIT_EVENTS_FLAT_DYM — Reddit Activity

Captures Reddit browsing, posting, and commenting behavior.

Column	Type	Description
USER_ID	FK	Links to AGENT_SYNC
SUBREDDIT	String	Which subreddit. Key for interest mapping.
TITLE	String	Post title
CONTENT	String	Post/comment text
AUTHOR	String	Reddit username
SCORE	Numeric	Upvotes/downvotes
POST_ID	String	Unique post identifier
PAGE_URL	String	Reddit URL
EVENT_TYPE	String	Platform source
CREATED_UTC_TS / EVENT_TIME	Timestamp	Timestamps

---

8. DONATIONS_EVENTS_DYM — Donation Events

Tracks donation-related activity on digital platforms.

Column	Type	Description
USER_ID	FK	Links to AGENT_SYNC
EVENT_KEY	String	Unique donation identifier
EVENT_TYPE	String	Type of engagement
PLATFORM	String	Platform (tiktok, instagram)
DATA	JSON	Raw event details
DONATION_EVENT_TIME / EVENT_TIME	Timestamp	Timestamps

---

9. BETTING_EVENTS_FLAT_DYM — Betting Activity

Captures sports betting and gambling platform interactions.

Column	Type	Description
USER_ID	FK	Links to AGENT_SYNC
ACTION	String	User action type
BET_TYPE	String	Type of bet
PLATFORM	String	Betting platform
EVENT_NAME / EVENT_CATEGORY	String	Event details
PARTICIPANTS	String	Event participants
SELECTION	String	Selected outcome
ODDS	Numeric	Betting odds
STAKE_AMOUNT / POTENTIAL_PAYOUT	Numeric	Financial amounts
IS_LIVE_EVENT	Boolean	Live event indicator
MARKET_CATEGORY	String	Market classification
GEO_*	Various	Geographic location fields
EVENT_DATE / EVENT_TIME	Timestamp	Timestamps

---

Query Translation Patterns

The core skill is translating business questions into multi-step, objective queries. Below are common patterns.

---

Pattern 1: "What's popular?" → Aggregate Event Counts

Business question: "What are the most popular RTD brands?"

Wrong approach: Asking the MCP "what's popular" directly.

Right approach — multi-step:

1. Identify keywords first: Ask: "What distinct values of BRAND or PRODUCT_NAME in PRODUCT_EVENTS_FLAT_DYM contain keywords like 'seltzer', 'cocktail', 'hard', 'white claw', 'truly', 'high noon'?"

2. Aggregate: "Count distinct USER_IDs and total events grouped by BRAND for products matching those keywords, ordered by count descending."

3. Segment by action: "Break this down by ACTION (viewed, added_to_cart, purchased) to see funnel performance."

---

Pattern 2: "What's the average price?" → Multi-Step Keyword + Aggregation

Business question: "What's the average price of RTD drinks?"

Wrong approach: Asking for "average RTD price" directly — the MCP has no RTD category tag.

Right approach — multi-step:

1. Define the universe: "Find all distinct products in PRODUCT_EVENTS_FLAT_DYM where PRODUCT_NAME or DESCRIPTION ILIKE any of: '%hard seltzer%', '%canned cocktail%', '%RTD%', '%ready to drink%', '%white claw%', '%truly%', '%high noon%', '%cutwater%'"

2. Extract prices: "For those products, what are the distinct PRODUCT_NAME and PRICE combinations?"

3. Calculate: "What is the average, median, min, and max PRICE across those products?"

---

Pattern 3: "Where do people discover X?" → Channel/Platform Analysis

Business question: "Which channels drive RTD discovery?"

Right approach:

1. Search behavior: "In SEARCH_EVENTS_FLAT_DYM, how many users searched queries containing RTD brand names? Group by SEARCH_ENGINE."

2. Content exposure: "In YOUTUBE_EVENTS_FLAT_DYM, how many users watched videos with RTD-related keywords in SNIPPET_TITLE or TAGS?"

3. Network traffic: "In NETWORK_TRAFFIC_EVENTS_DYM, which SNI domains (instacart, doordash, target, amazon, etc.) are most visited by users who also have RTD product events?"

4. Product source: "In PRODUCT_EVENTS_FLAT_DYM, extract the domain from PAGE_URL for RTD products. Group by domain to see which retailers."

---

Pattern 4: "Does X lead to Y?" → Temporal Sequence Analysis

Business question: "Does watching creator content lead to purchases?"

Right approach — event sequencing:

1. Define exposure group: "Find USER_IDs in YOUTUBE_EVENTS_FLAT_DYM who watched videos with beverage/RTD keywords in the title between [date range]."

2. Define action group: "Find USER_IDs in PRODUCT_EVENTS_FLAT_DYM who had ACTION = 'purchased' for beverage products in the same or subsequent time window."

3. Compare: "What % of the exposure group also appears in the action group? What % of users NOT in the exposure group appear in the action group?"

4. Time sequence: "For users in both groups, what was the time gap between YouTube event and purchase event?"

---

Pattern 5: "Who is our audience?" → Demographic Segmentation

Business question: "Who are the people engaging with Japanese content?"

Right approach:

1. Define the behavior: "Find USER_IDs from SEARCH_EVENTS where QUERY ILIKE any of '%japan%', '%anime%', '%ramen%', '%sushi%', '%sake%', '%matcha%'"

2. Also check YouTube: "Add USER_IDs from YOUTUBE_EVENTS where SNIPPET_TITLE or TAGS contain those same keywords."

3. Join to demographics: "For those USER_IDs, pull GENDER, YEAR_OF_BIRTH, HOUSEHOLD_INCOME, EDUCATION_LEVEL, EMPLOYMENT_STATUS, FULL_ADDRESS from AGENT_SYNC."

4. Aggregate: "What's the distribution of each demographic field?"

---

Pattern 6: "What content performs best?" → Engagement Metrics

Business question: "Which types of creator content drive the most engagement?"

Right approach:

1. Categorize content: "In YOUTUBE_EVENTS_FLAT_DYM, classify videos by keywords in SNIPPET_TITLE: 'tasting', 'tutorial', 'review', 'challenge', 'reaction', 'reveal'"

2. Per-category metrics: "For each category, count: distinct users, total events, average VIEW_COUNT, average LIKE_COUNT, average COMMENT_COUNT"

3. Engagement rate: "Calculate engagement per participant (total events / distinct users) for each category"

4. Cross-reference downstream: "For users who watched each content type, how many also appear in PRODUCT_EVENTS with beverage-related actions?"

---

Pattern 7: "Is there a trend?" → Time-Series Analysis

Business question: "Is awareness for brand X growing week over week?"

Right approach:

1. Define the signal: "Count events per week in SEARCH_EVENTS where QUERY ILIKE '%brand_name%'"

2. Add YouTube: "Count events per week in YOUTUBE_EVENTS where SNIPPET_TITLE or DESCRIPTION ILIKE '%brand_name%'"

3. Add product interactions: "Count events per week in PRODUCT_EVENTS where PRODUCT_NAME or BRAND ILIKE '%brand_name%'"

4. Compare periods: "Show week-over-week change for each signal."

Important caveat: Watch for false positives. Brand names like "Toki" or "Hibiki" may match unrelated content (anime characters, rappers). Always validate by checking the actual content context.

---

Common Pitfalls

❌ Asking interpretive questions directly

Bad: "Why do consumers prefer White Claw?" Good: "How many distinct users have events for White Claw products broken down by ACTION type? What QUERY terms do users search before or after White Claw product events?"

❌ Assuming category labels exist

Bad: "Show me all RTD beverage data" Good: "Show me products where PRODUCT_NAME or DESCRIPTION contains keywords: [list of RTD brands and category terms]"

❌ Confusing video-level metrics with user-level metrics

Bad: "How many views did RTD content get?" (this gives you public YouTube view counts) Good: "How many distinct panelists watched videos with RTD-related titles?" (this gives you panel reach)

❌ Forgetting to validate keyword matches

Bad: "How many people searched for 'Yamazaki'?" (could be the whisky OR a Japanese actor) Good: "How many people searched for 'Yamazaki'? Show me the top 10 QUERY values to verify context."

❌ Single-step queries for complex questions

Bad: "What's the conversion rate from creator content to purchase?" Good: Break into 3 steps: define exposure group → define conversion group → calculate overlap percentage.

---

Quick Reference: Question → Table Mapping

If you want to know...	Primary table(s)	Key columns
What people search for	SEARCH_EVENTS_FLAT_DYM	QUERY, SEARCH_ENGINE
What people buy / view / cart	PRODUCT_EVENTS_FLAT_DYM	ACTION, PRODUCT_NAME, BRAND, PRICE, PAGE_URL
What videos people watch	YOUTUBE_EVENTS_FLAT_DYM	SNIPPET_TITLE, CHANNEL_TITLE, VIEW_COUNT
What apps/sites people use	NETWORK_TRAFFIC_EVENTS_DYM	SNI
What news people read	NEWS_EVENTS_FLAT_DYM	KEYWORDS, NEWS_OUTLET, CONTENT_SUMMARY
What subreddits people visit	REDDIT_EVENTS_FLAT_DYM	SUBREDDIT, TITLE, CONTENT
Who the users are	AGENT_SYNC	GENDER, YEAR_OF_BIRTH, HOUSEHOLD_INCOME, FULL_ADDRESS
Donation behavior	DONATIONS_EVENTS_DYM	PLATFORM, EVENT_TYPE
Betting behavior	BETTING_EVENTS_FLAT_DYM	PLATFORM, BET_TYPE, EVENT_NAME

---

Multi-Table Query Templates

Template A: Content Exposure → Purchase Funnel

Step 1: Get exposed users from YOUTUBE_EVENTS (filter by title keywords)
Step 2: Get purchasers from PRODUCT_EVENTS (filter by ACTION + product keywords)
Step 3: Intersect USER_IDs
Step 4: Join to AGENT_SYNC for demographics
Step 5: Calculate exposure-to-purchase rate vs. control group

Template B: Platform Usage Before Purchase

Step 1: Get users with purchases from PRODUCT_EVENTS
Step 2: For those users, query NETWORK_TRAFFIC (SNI) in the 24h before purchase EVENT_TIME
Step 3: Aggregate top domains to identify pre-purchase media touchpoints

Template C: Category Interest Sizing

Step 1: Define keyword list for the category
Step 2: Count distinct users with matching QUERY in SEARCH_EVENTS
Step 3: Count distinct users with matching SNIPPET_TITLE in YOUTUBE_EVENTS
Step 4: Count distinct users with matching PRODUCT_NAME in PRODUCT_EVENTS
Step 5: Deduplicate across tables for total category reach

Template D: Price Point Analysis

Step 1: Identify relevant products via keyword search in PRODUCT_EVENTS
Step 2: Pull distinct PRODUCT_NAME + PRICE combinations
Step 3: Filter to ACTION = 'purchased' for actual transaction prices
Step 4: Calculate average, median, min, max
Step 5: Segment by BRAND for competitive pricing view

---

Tips for Power Users

1. Always start with a keyword exploration step. Before aggregating, pull a sample of 20–50 matching records to verify your keywords are capturing the right products/content.

2. Use ILIKE liberally. Product names and descriptions have inconsistent casing and formatting.

3. Extract retailer from PAGE_URL. The domain in the URL tells you which platform (amazon.com, target.com, instacart.com, doordash.com, etc.)

4. Time windows matter. Specify date ranges explicitly. The panel grows weekly, so apples-to-apples comparisons need consistent time frames.

5. Control groups are powerful. When measuring "does X drive Y," always compare to users who did NOT experience X.

6. Watch for false positives with brand names. Validate that search results and content matches are actually about the brand/product you're studying.

7. Join to AGENT_SYNC last. Build your behavioral cohort first, then enrich with demographics. This keeps queries efficient.

8. The NETWORK_TRAFFIC table uses USER_IDENTIFIER, not USER_ID. The join column name is different from all other table