Example Queries & Use Cases

Example Queries & Use Cases

This document provides practical examples of using MCP tools for common AI shopping assistant scenarios.

Table of Contents

• Basic Product Discovery
• Personalized Recommendations
• Offer-Driven Shopping
• User Context & Insights
• Multi-Tool Workflows
• Advanced Scenarios

---

Basic Product Discovery

Search for Products

Scenario: User wants to find coffee products

{
  "name": "search_products",
  "arguments": {
    "query": "coffee",
    "limit": 10
  }
}

Expected Result: List of coffee products with brands, names, and IDs

---

Get Product Details

Scenario: User clicks on a product to see more information

{
  "name": "get_product_details_enhanced",
  "arguments": {
    "product_id": "DEMO_PROD_034",
    "user_id": "DEMO_USER_HEALTH"
  }
}

Expected Result:

• Product details (name, brand, category, tags)
• Similar products
• Active offers
• User’s purchase history for this product

---

Find Similar Products

Scenario: “Show me products similar to this one”

{
  "name": "find_similar_products",
  "arguments": {
    "product_id": "DEMO_PROD_004",
    "min_similarity": 0.6,
    "limit": 5
  }
}

Expected Result: Similar products with similarity scores for explainability

Use Case: “Since you like Oatly Oat Milk, you might also like…”

---

Personalized Recommendations

New Product Discovery

Scenario: “Show me new products I might like”

{
  "name": "discover_new_products",
  "arguments": {
    "user_id": "DEMO_USER_HEALTH",
    "limit": 10
  }
}

Expected Result: Products user hasn’t tried, based on preferences and community trends

---

Collaborative Filtering

Scenario: “What do people like me buy?”

{
  "name": "get_collaborative_recommendations",
  "arguments": {
    "user_id": "DEMO_USER_FOODIE",
    "limit": 10
  }
}

Expected Result: Products popular among similar users with purchase counts (social proof)

---

Category-Specific Discovery

Scenario: “Show me new snacks to try”

{
  "name": "discover_new_products",
  "arguments": {
    "user_id": "DEMO_USER_HEALTH",
    "category": "Snacks",
    "limit": 10
  }
}

Expected Result: Snack products user hasn’t purchased, filtered by preferences

---

Community Insights

Scenario: “What’s trending in my area?”

{
  "name": "get_community_insights",
  "arguments": {
    "user_id": "DEMO_USER_HEALTH"
  }
}

Expected Result:

• Popular products in user’s community
• Emerging brands
• Category trends
• Community size and demographics

---

Offer-Driven Shopping

Get My Active Offers

Scenario: “What offers are available for me?”

{
  "name": "get_active_offers",
  "arguments": {
    "user_id": "DEMO_USER_FAMILY",
    "limit": 20
  }
}

Expected Result: Eligible offers with point values, products, and expiration dates

---

Search for Specific Offers

Scenario: “Are there deals on yogurt?”

{
  "name": "search_offers",
  "arguments": {
    "query": "yogurt",
    "user_id": "DEMO_USER_HEALTH",
    "limit": 10
  }
}

Expected Result: Offers matching “yogurt” that user is eligible for

---

Match Shopping List to Offers

Scenario: “Which items on my list have offers?”

{
  "name": "match_products_to_offers",
  "arguments": {
    "product_ids": [
      "DEMO_PROD_001",
      "DEMO_PROD_004",
      "DEMO_PROD_023",
      "DEMO_PROD_034"
    ],
    "user_id": "DEMO_USER_HEALTH"
  }
}

Expected Result: Products with their matching offers and point values

Value: Helps users maximize rewards on intended purchases

---

Optimize Offer Selection

Scenario: “Which offers should I activate to maximize points?”

{
  "name": "optimize_offer_activation",
  "arguments": {
    "user_id": "DEMO_USER_FAMILY",
    "limit": 5
  }
}

Expected Result: Top offers ranked by:

• Point value
• Likelihood of redemption based on purchase history
• Optimization score

---

User Context & Insights

Purchase History

Scenario: “What do I usually buy?”

{
  "name": "get_user_purchase_history",
  "arguments": {
    "user_id": "DEMO_USER_HEALTH",
    "limit": 20
  }
}

Expected Result: Products user has purchased with purchase counts

---

Category-Specific History

Scenario: “Show my dairy purchases”

{
  "name": "get_user_purchase_history",
  "arguments": {
    "user_id": "DEMO_USER_HEALTH",
    "category": "Dairy",
    "limit": 20
  }
}

Expected Result: Only dairy products from purchase history

---

Shopping Patterns

Scenario: “What are my shopping habits?”

{
  "name": "get_purchase_patterns",
  "arguments": {
    "user_id": "DEMO_USER_FAMILY"
  }
}

Expected Result:

• Total products purchased
• Unique categories
• Category distribution
• Brand preferences
• Shopping frequency

---

Brand Preferences

Scenario: “What are my favorite brands?”

{
  "name": "get_user_brands",
  "arguments": {
    "user_id": "DEMO_USER_ECO",
    "limit": 10
  }
}

Expected Result: Brands ranked by purchase frequency

---

Category Affinity

Scenario: “What dairy brands do I prefer?”

{
  "name": "get_category_brand_affinity",
  "arguments": {
    "user_id": "DEMO_USER_HEALTH",
    "category": "Dairy",
    "limit": 10
  }
}

Expected Result: Dairy brands ranked by user’s purchase frequency

---

Household Context

Scenario: “What does my household buy?”

{
  "name": "get_household_context",
  "arguments": {
    "user_id": "DEMO_USER_HEALTH"
  }
}

Expected Result:

• Household members
• Combined budget
• Shared product preferences
• Household type and demographics

---

Multi-Tool Workflows

Complete Shopping Assistant

Scenario: User asks “Help me plan my weekly grocery trip”

Workflow:

1. Get purchase history to understand usual items
2. Predict repurchases to identify restocking needs
3. Get active offers to find deals
4. Match products to offers for savings

// Step 1: Get purchase history
{
  "name": "get_user_purchase_history",
  "arguments": {
    "user_id": "DEMO_USER_TRADITIONAL",
    "limit": 30
  }
}

// Step 2: Predict repurchases
{
  "name": "predict_repurchases",
  "arguments": {
    "user_id": "DEMO_USER_TRADITIONAL",
    "days_ahead": 7,
    "limit": 15
  }
}

// Step 3: Get active offers
{
  "name": "get_active_offers",
  "arguments": {
    "user_id": "DEMO_USER_TRADITIONAL",
    "venue_type": "grocery",
    "limit": 20
  }
}

// Step 4: Match to offers
{
  "name": "match_products_to_offers",
  "arguments": {
    "product_ids": ["<from step 2>"],
    "user_id": "DEMO_USER_TRADITIONAL"
  }
}

Result: Complete shopping list with restocking items and applicable offers

---

New User Onboarding

Scenario: “I’m new, help me explore products”

Workflow:

1. Get community insights to see what’s popular
2. Discover brands in key categories
3. Get local trending products
4. Show active offers to drive engagement

// Step 1: Community insights
{
  "name": "get_community_insights",
  "arguments": {
    "user_id": "DEMO_USER_SINGLE"
  }
}

// Step 2: Discover brands in popular category
{
  "name": "discover_brands",
  "arguments": {
    "category": "Snacks",
    "limit": 15
  }
}

// Step 3: Local trending
{
  "name": "get_local_trending",
  "arguments": {
    "user_id": "DEMO_USER_SINGLE",
    "limit": 10
  }
}

// Step 4: Active offers
{
  "name": "get_active_offers",
  "arguments": {
    "user_id": "DEMO_USER_SINGLE",
    "limit": 20
  }
}

Result: Comprehensive introduction to available products and deals

---

Category Expansion

Scenario: “I want to try new categories”

Workflow:

1. Get current categories
2. Predict category expansion opportunities
3. Discover brands in new categories
4. Find alternatives to ease transition

// Step 1: Current categories
{
  "name": "get_user_categories",
  "arguments": {
    "user_id": "DEMO_USER_SINGLE",
    "limit": 20
  }
}

// Step 2: Predict expansion
{
  "name": "predict_category_expansion",
  "arguments": {
    "user_id": "DEMO_USER_SINGLE",
    "limit": 3
  }
}

// Step 3: Discover brands in new category
{
  "name": "discover_brands",
  "arguments": {
    "category": "<from step 2>",
    "limit": 10
  }
}

// Step 4: Find starter products
{
  "name": "discover_new_products",
  "arguments": {
    "user_id": "DEMO_USER_SINGLE",
    "category": "<from step 2>",
    "limit": 10
  }
}

Result: Guided expansion into new shopping categories

---

Advanced Scenarios

Budget-Conscious Shopping

Scenario: “Help me shop for $50 with maximum offers”

Workflow:

// 1. Get spending patterns
{
  "name": "track_spending_patterns",
  "arguments": {
    "user_id": "DEMO_USER_FAMILY",
    "days": 30
  }
}

// 2. Optimize offers
{
  "name": "optimize_offer_activation",
  "arguments": {
    "user_id": "DEMO_USER_FAMILY",
    "limit": 10
  }
}

// 3. Get retailer offers at budget stores
{
  "name": "get_retailer_offers",
  "arguments": {
    "retailer_id": "RET_ALDI",
    "user_id": "DEMO_USER_FAMILY",
    "limit": 20
  }
}

Result: Budget-optimized shopping plan with maximum points

---

Health-Conscious Discovery

Scenario: “Show me healthy alternatives to what I buy”

Workflow:

// 1. Get current purchases
{
  "name": "get_user_purchase_history",
  "arguments": {
    "user_id": "DEMO_USER_TRADITIONAL",
    "limit": 20
  }
}

// 2. For each product, find similar products
{
  "name": "find_similar_products",
  "arguments": {
    "product_id": "<from step 1>",
    "limit": 3
  }
}

// 3. Filter for organic/healthy using product context
{
  "name": "get_product_context",
  "arguments": {
    "product_id": "<from step 2>"
  }
}

Result: Healthier alternatives with similarity explanations

---

Social Shopping

Scenario: “What are people in my community buying?”

Workflow:

// 1. Community insights
{
  "name": "get_community_insights",
  "arguments": {
    "user_id": "DEMO_USER_FOODIE"
  }
}

// 2. Collaborative recommendations
{
  "name": "get_collaborative_recommendations",
  "arguments": {
    "user_id": "DEMO_USER_FOODIE",
    "limit": 15
  }
}

// 3. Local trending
{
  "name": "get_local_trending",
  "arguments": {
    "user_id": "DEMO_USER_FOODIE",
    "limit": 10
  }
}

Result: Community-driven product discovery with social proof

---

Testing Recommendations

Use Demo Users for Different Scenarios

Health & Organic: DEMO_USER_HEALTH, DEMO_USER_ECO

{"user_id": "DEMO_USER_HEALTH"}

Budget & Value: DEMO_USER_FAMILY

{"user_id": "DEMO_USER_FAMILY"}

Convenience: DEMO_USER_SINGLE

{"user_id": "DEMO_USER_SINGLE"}

Exploration: DEMO_USER_FOODIE

{"user_id": "DEMO_USER_FOODIE"}

Traditional: DEMO_USER_TRADITIONAL

{"user_id": "DEMO_USER_TRADITIONAL"}

See DEMO_USERS.md for complete profiles.

---

Error Handling Examples

User Not Found

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "User not found: INVALID_USER_ID"
  },
  "id": 1
}

Solution: Verify user_id exists in database

---

No Results

{
  "jsonrpc": "2.0",
  "result": {
    "products": [],
    "message": "No products found matching criteria"
  },
  "id": 1
}

Solution: Broaden search criteria or check data availability

---

Performance Tips

1. Use appropriate limits: Default limits are optimized, only increase if needed
2. Cache user context: Purchase history, preferences change slowly
3. Batch product lookups: Use match_products_to_offers instead of individual queries
4. Filter early: Use category/venue_type filters to reduce result sets
5. Leverage community nodes: Collaborative filtering is optimized via communities

---

Next Steps

• Review MCP_TOOLS.md for complete tool reference
• Explore GRAPH_SCHEMA.md to understand data relationships
• Test with DEMO_USERS.md profiles
• Check README.md for integration guidance