MCP Tools Reference

Complete reference for all 29 MCP tools available in the Consumer Graph shopping assistant.

Tool Categories

Product Discovery (8 tools)
Offer Management (4 tools)
User Context (9 tools)
Recommendations (4 tools)
Analytics & Predictions (4 tools)

Product Discovery

search_products

Search for products by name, brand, or category with flexible text matching.

Parameters:

query (string, required) - Search term (product name, brand, or category)
limit (number, optional) - Max results (default: 20)

Returns: List of products with names, brands, categories, and IDs

Use Cases:

User searches for specific product: “Find coffee”
Brand search: “Show me Starbucks products”
Category exploration: “What snacks are available?”

Example:

{
  "name": "search_products",
  "arguments": {
    "query": "organic milk",
    "limit": 10
  }
}

get_product_context

Get detailed context about a specific product including category, brand, and basic information.

Parameters:

product_id (string, required) - Product ID

Returns: Product details with category, brand, tags, and attributes

Use Cases:

Get product details after search
Understand product attributes for recommendations
Check if product is organic, vegan, etc.

get_product_details_enhanced

Get comprehensive product information including similar products, offers, and purchase patterns.

Parameters:

product_id (string, required) - Product ID
user_id (string, optional) - User ID for personalized context

Returns: Complete product profile with:

Basic details (name, brand, category)
Similar products
Active offers
User purchase history (if user_id provided)

Use Cases:

Product detail page
Comprehensive product recommendations
Offer-aware product information

find_similar_products

Find products similar to a given product based on graph similarity scores.

Parameters:

product_id (string, required) - Product ID to find similar items for
min_similarity (number, optional) - Minimum similarity score 0.0-1.0 (default: 0.5)
limit (number, optional) - Max results (default: 10)

Returns: Products with similarity scores explaining relationship strength

Use Cases:

Product recommendations: “Customers who bought X also bought Y”
Alternative suggestions: “Try these instead”
Explainable recommendations with quantifiable similarity

Example:

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

Key Feature: Returns similarity scores (0.0-1.0) for explainable AI

discover_new_products

Discover new products based on user preferences, community trends, and similar users.

Parameters:

user_id (string, required) - User ID
category (string, optional) - Filter by category
limit (number, optional) - Max results (default: 20)

Returns: Products the user hasn’t purchased yet, ranked by relevance

Use Cases:

“Show me new products I might like”
Category-specific discovery: “New snacks to try”
Expanding user’s product repertoire

find_alternatives

Find alternative products in the same category, excluding user’s previously purchased products.

Parameters:

user_id (string, required) - User ID
category (string, required) - Category name
limit (number, optional) - Max results (default: 10)

Returns: Alternative products in category user hasn’t tried

Use Cases:

“Show me other cereals”
“What else in dairy should I try?”
Helping users explore within familiar categories

discover_brands

Discover brands in a specific category.

Parameters:

category (string, required) - Category name (e.g., ‘Dairy’)
limit (number, optional) - Max results (default: 20)

Returns: Brands active in the category with product counts

Use Cases:

“What coffee brands are available?”
“Show me yogurt brands”
Brand exploration within category

get_brand_products

Get all products from a specific brand.

Parameters:

brand (string, required) - Brand name
limit (number, optional) - Max results (default: 20)

Returns: All products from the brand

Use Cases:

“Show me all Chobani products”
“What does Organic Valley offer?”
Brand-focused shopping

Offer Management

get_active_offers

Get active offers for a user, filtered by eligibility.

Parameters:

user_id (string, required) - User ID
venue_type (enum, optional) - Filter by venue:
- grocery, convenience, airport, gas_station, pharmacy, restaurant
limit (number, optional) - Max results (default: 20)

Returns: Eligible offers with:

Point values
Priority/tier
Applicable products/brands/categories
Start/end dates
Retailer information

Use Cases:

“What offers are available for me?”
“Show me grocery store offers”
Personalized deal discovery

Example:

{
  "name": "get_active_offers",
  "arguments": {
    "user_id": "DEMO_USER_HEALTH",
    "venue_type": "grocery",
    "limit": 10
  }
}

search_offers

Search for offers by product, brand, or category.

Parameters:

query (string, required) - Search term
user_id (string, optional) - Filter by user eligibility
limit (number, optional) - Max results (default: 20)

Returns: Matching offers with eligibility information

Use Cases:

“Find coffee offers”
“Are there deals on Starbucks?”
“Show me dairy offers”

get_retailer_offers

Get all active offers available at a specific retailer.

Parameters:

retailer_id (string, required) - Retailer ID
user_id (string, optional) - Filter by user eligibility
limit (number, optional) - Max results (default: 20)

Returns: Retailer-specific offers

Use Cases:

“What offers are at Target?”
“Show me Whole Foods deals”
Retailer-specific shopping planning

match_products_to_offers

Match products to available offers, showing which items have deals.

Parameters:

product_ids (array of strings, required) - List of product IDs
user_id (string, required) - User ID for eligibility

Returns: Products with their matching offers and point values

Use Cases:

Shopping cart optimization: “Which items have offers?”
“Show me offers for my shopping list”
Maximizing rewards on intended purchases

Example:

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

User Context

get_user_purchase_history

Get user’s purchase history with product details.

Parameters:

user_id (string, required) - User ID
limit (number, optional) - Max results (default: 20)
category (string, optional) - Filter by category

Returns: Purchased products with purchase counts and details

Use Cases:

“What do I usually buy?”
“Show my dairy purchases”
Understanding user preferences

get_purchase_patterns

Get user’s shopping patterns including frequency, spending, and preferences.

Parameters:

user_id (string, required) - User ID

Returns: Aggregate patterns:

Total products purchased
Unique categories
Category distribution
Brand preferences
Average spending patterns

Use Cases:

“What are my shopping habits?”
Understanding user’s shopping profile
Personalization context

get_purchase_timeline

Get chronological purchase timeline for a user.

Parameters:

user_id (string, required) - User ID
days (number, optional) - Time window in days (default: 30)

Returns: Time-ordered purchase events

Use Cases:

“What did I buy this month?”
Recent purchase history
Repurchase timing analysis

get_user_brands

Get brands user has purchased from, ranked by purchase count.

Parameters:

user_id (string, required) - User ID
limit (number, optional) - Max results (default: 20)

Returns: Brands with purchase counts

Use Cases:

“What are my favorite brands?”
Brand loyalty analysis
Personalized brand recommendations

get_user_categories

Get product categories user shops in, ranked by purchase count.

Parameters:

user_id (string, required) - User ID
limit (number, optional) - Max results (default: 20)

Returns: Categories with purchase counts

Use Cases:

“What categories do I shop?”
Understanding shopping scope
Category expansion opportunities

get_category_brand_affinity

Get user’s brand preferences within a specific category.

Parameters:

user_id (string, required) - User ID
category (string, required) - Category name
limit (number, optional) - Max results (default: 20)

Returns: Brands in category ranked by user’s purchase frequency

Use Cases:

“What dairy brands do I prefer?”
“My favorite snack brands”
Category-specific brand loyalty

get_user_retailers

Get retailers user shops at, ranked by visit frequency.

Parameters:

user_id (string, required) - User ID
limit (number, optional) - Max results (default: 10)

Returns: Retailers with shopping frequency

Use Cases:

“Where do I usually shop?”
Retailer preference analysis
Location-based recommendations

get_user_location_context

Get user’s location information (ZIP code, coordinates).

Parameters:

user_id (string, required) - User ID

Returns: Location data:

ZIP code
Latitude/Longitude (if available)
Nearby retailer context

Use Cases:

Location-based recommendations
“What’s near me?”
Regional offer targeting

get_household_context

Get household members, shared purchase patterns, and combined spending power.

Parameters:

user_id (string, required) - User ID

Returns: Household information:

Household members
Combined budget
Shared product preferences
Household type

Use Cases:

“What does my household buy?”
Family shopping planning
Multi-member recommendations

Example:

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

Recommendations

get_collaborative_recommendations

Get product recommendations based on what similar users have purchased (collaborative filtering).

Parameters:

user_id (string, required) - User ID
limit (number, optional) - Max results (default: 10)

Returns: Products with purchase counts from similar users (social proof)

Use Cases:

“What do people like me buy?”
Discovering NEW products user hasn’t tried
Social proof for recommendations

Key Feature: Returns purchase counts showing popularity among similar users

Example:

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

get_community_insights

Get insights from similar users in your area (trending products, emerging brands).

Parameters:

user_id (string, required) - User ID
category (string, optional) - Filter by category

Returns: Community trends:

Popular products in community
Emerging brands
Category trends
Community size

Use Cases:

“What’s trending in my area?”
“Popular products among similar shoppers”
Local community recommendations

get_local_trending

Get trending products in user’s local area based on ZIP code.

Parameters:

user_id (string, required) - User ID for location
category (string, optional) - Filter by category
limit (number, optional) - Max results (default: 10)

Returns: Locally trending products

Use Cases:

“What’s popular near me?”
Regional product trends
Location-specific recommendations

compare_brands

Compare multiple brands by product count and categories.

Parameters:

brands (array of strings, required) - Brand names to compare

Returns: Side-by-side brand comparison:

Product counts
Categories covered
Key products

Use Cases:

“Compare Chobani vs Fage”
Brand decision support
Understanding brand offerings

Analytics & Predictions

track_spending_patterns

Analyze user’s spending patterns over time.

Parameters:

user_id (string, required) - User ID
days (number, optional) - Time window (default: 30)

Returns: Spending analysis:

Total spending
Category breakdown
Spending trends
Average transaction value

Use Cases:

Budget tracking
“How much do I spend on groceries?”
Spending habit analysis

predict_repurchases

Predict which products user is likely to repurchase soon.

Parameters:

user_id (string, required) - User ID
days_ahead (number, optional) - Prediction window (default: 7)
limit (number, optional) - Max results (default: 10)

Returns: Products with repurchase predictions and confidence

Use Cases:

“What do I need to restock?”
Proactive shopping reminders
Subscription product suggestions

predict_category_expansion

Predict new categories user might explore based on community patterns.

Parameters:

user_id (string, required) - User ID
limit (number, optional) - Max results (default: 5)

Returns: Recommended new categories with rationale

Use Cases:

“What new categories should I explore?”
Expanding user’s shopping scope
Cross-category recommendations

optimize_offer_activation

Recommend which offers to activate for maximum points based on user’s shopping patterns.

Parameters:

user_id (string, required) - User ID
limit (number, optional) - Max offers to recommend (default: 10)

Returns: Prioritized offers with:

Point value
Likelihood of redemption
Applicable products user buys
Optimization score

Use Cases:

“Which offers should I activate?”
Maximizing rewards
Personalized offer suggestions

Example:

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

Common Tool Combinations

Smart Shopping List

get_user_purchase_history - See what user usually buys
predict_repurchases - Identify items to restock
match_products_to_offers - Find deals on needed items

New Product Discovery

get_purchase_patterns - Understand preferences
get_community_insights - See what similar users like
discover_new_products - Find relevant new items
find_similar_products - Get alternatives with explanations

Offer Maximization

get_active_offers - See available offers
optimize_offer_activation - Prioritize high-value offers
get_purchase_patterns - Ensure offers match habits

Category Exploration

get_user_categories - Current shopping categories
predict_category_expansion - Suggested new categories
discover_brands - Brands in new category
find_alternatives - Try new products in category

Error Handling

All tools return JSON-RPC 2.0 responses. Errors include:

Missing required parameters
User not found
Product not found
Invalid date ranges
Database connection errors

Always check for error field in response before processing result.

Performance Notes

Most tools include limit parameters - use appropriate values
Community/Category optimization reduces query time by 70%
Tools include performance metadata in responses
Consider caching frequently accessed user context

Testing

Use demo users for testing all tools:

DEMO_USER_HEALTH - Health-conscious
DEMO_USER_FAMILY - Budget-conscious family
DEMO_USER_SINGLE - Convenience-oriented
DEMO_USER_FOODIE - Specialty shopper
DEMO_USER_TRADITIONAL - Traditional shopper
DEMO_USER_ECO - Eco-conscious

See DEMO_USERS.md for detailed profiles.