MCP Prompts

MCP Prompts provide guided workflow templates that combine L2 tools, MCP resources, and structured step-by-step instructions to accomplish complex data analysis tasks. These prompts are optimized for AI assistants and replace the deprecated L3 workflow tools.

Overview

Prompts define multi-step workflows with clear goals, available tools, success criteria, and expected outputs. AI assistants use these prompts to orchestrate tool calls autonomously while following best practices.

Key Benefits:

• Autonomous Orchestration - AI agents decide tool sequences based on the goal
• Progressive Guidance - Step-by-step instructions with success criteria
• Tool Integration - Seamless use of L2 tools and MCP resources
• Flexible Execution - Agents adapt to data quality and intermediate results
• Transparent Process - Clear reasoning and decision points

Available Prompts

analyze_customers

Generate ICP (Ideal Customer Profile) insights from customer CSV data through 7-step guided analysis.

Workflow Steps:

1. Schema Detection - Identify email/phone/address columns
2. Identity Resolution - Convert identifiers to person IDs
3. Domain Selection - Choose relevant enrichment domains
4. Profile Enrichment - Enrich person IDs with profile data
5. Trait Aggregation - Count cluster frequencies
6. Lift Calculation - Compute distinctiveness scores
7. ICP Synthesis - Generate personas with targeting expressions

Arguments:

Example Usage:

{
  "method": "prompts/get",
  "params": {
    "name": "analyze_customers",
    "arguments": {
      "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
      "csv_filename": "customers.csv",
      "market_context": "B2B SaaS platform for marketing automation"
    }
  }
}

Response:

The prompt template is returned as text that guides the AI agent through the workflow. The agent will autonomously:

1. Sample the CSV using resources/read with ?offset=0&limit=10
2. Call resolve_identities with detected schema
3. Call get_person to enrich profiles
4. Call group_people_by_trait to aggregate clusters
5. Call calculate_trait_lift to compute lift scores
6. Synthesize personas and targeting expressions

Expected Outputs:

• Detected schema with confidence scores
• Resolution statistics (total, resolved, rate)
• Domain selection with reasoning
• Top 15 clusters by lift score
• 2-4 personas with key traits and targeting expressions
• ICP analysis summary

L2 Tools Used:

• resolve_identities - Convert identifiers to person IDs
• get_person - Enrich profiles with domains
• group_people_by_trait - Aggregate cluster frequencies
• calculate_trait_lift - Calculate distinctiveness scores

build_cluster_expression

Convert natural language audience descriptions into structured boolean expressions with cluster hashes for targeting.

Workflow Steps:

1. Parse Description - Extract criteria, geographic filter, size hint
2. Search Clusters - Find matching clusters for each criterion
3. Geocode Location - Convert location names to coordinates (if applicable)
4. Build Expression - Construct boolean expression with AND/OR/NOT logic
5. Estimate Size - Validate expression and estimate audience
6. Return Result - Provide expression with metadata

Arguments:

Example Usage:

{
  "method": "prompts/get",
  "params": {
    "name": "build_cluster_expression",
    "arguments": {
      "description": "software engineers at B2B SaaS companies in San Francisco",
      "context": "ABM campaign targeting technical decision makers",
      "max_criteria": "3"
    }
  }
}

Response:

The prompt template guides the AI agent to:

1. Parse "software engineers at B2B SaaS companies in San Francisco" into:

   • Criteria: ["software engineers", "B2B SaaS companies"]
   • Geographic: "San Francisco"

2. Call search_clusters for each criterion in parallel:

   {
     "query": "software engineer",
     "domain": "professional",
     "limit": 5
   }

3. Call geocode_location for geographic filter:

   {
     "location": "San Francisco",
     "provider": "google"
   }

4. Build boolean expression using AND logic:

   cluster:abc123 AND cluster:def456

5. Call find_persons to estimate audience size:

   {
     "expression": "cluster:abc123 AND cluster:def456",
     "location": {
       "latitude": 37.7749,
       "longitude": -122.4194,
       "radius_km": 25
     },
     "limit": 0
   }

Expected Outputs:

• Structured boolean expression with cluster hashes
• Geographic filter with lat/long and radius
• Estimated audience size
• Criteria mapping with alternatives
• Expression reasoning

L2 Tools Used:

• search_clusters - Find matching clusters for criteria
• geocode_location - Convert location to coordinates
• find_persons - Estimate audience size

Prompt Structure

All prompts follow a consistent structure:

Metadata:

• Name, description, arguments

Workflow Content:

• Goal statement
• Context and inputs
• Available L2 tools
• Step-by-step instructions with success criteria
• Example outputs
• Important notes and best practices

Step Format:

### Step N: [Step Name]
**Goal**: [What this step accomplishes]

**Actions**:
1. [Specific action with tool call example]
2. [Review/validation step]

**Success Criteria**: [How to know this step succeeded]

**Output**: [What data/state results from this step]

Using Prompts with AI Assistants

Getting a Prompt

{
  "method": "prompts/get",
  "params": {
    "name": "analyze_customers",
    "arguments": {
      "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
      "csv_filename": "customers.csv",
      "market_context": "B2B SaaS"
    }
  }
}

The response contains the rendered prompt template with arguments interpolated. The AI assistant reads this prompt and follows the workflow autonomously.

Listing Available Prompts

{
  "method": "prompts/list"
}

Response:

{
  "prompts": [
    {
      "name": "analyze_customers",
      "description": "Guided workflow for ICP analysis from customer CSV data...",
      "arguments": [
        {
          "name": "workflow_id",
          "description": "Workflow session identifier (UUID)",
          "required": true
        }
      ]
    },
    {
      "name": "build_cluster_expression",
      "description": "Convert natural language audience descriptions...",
      "arguments": [...]
    }
  ]
}

Prompts vs L3 Tools: Comparison

Why Prompts Are Better:

1. Agent Autonomy - AI decides optimal tool sequence based on intermediate results
2. Transparent Process - Users see each step and can intervene
3. Natural Iteration - Conversational refinement without special APIs
4. Faster Evolution - Prompt updates don't require server deployment
5. Better Debugging - Clear reasoning trail for troubleshooting
6. Protocol Native - Uses standard MCP methods (prompts/list, prompts/get)

Migration from L3 Tools

Migrating from analyze_customers Tool

Old Approach (L3 Tool):

{
  "name": "analyze_customers",
  "arguments": {
    "csv_key": "customers.csv",
    "market_context": {
      "base_context": "B2B SaaS",
      "refinements": []
    },
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

New Approach (Prompt):

{
  "method": "prompts/get",
  "params": {
    "name": "analyze_customers",
    "arguments": {
      "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
      "csv_filename": "customers.csv",
      "market_context": "B2B SaaS"
    }
  }
}

Key Differences:

1. Parameter Format - csv_filename instead of csv_key (just filename, not S3 path)
2. Market Context - Simple string instead of object with refinements
3. Interaction Model - Get prompt → follow steps → use L2 tools, instead of single tool call
4. Iteration - Natural conversation instead of market_context.refinements array

Migration Steps:

1. Replace tool call with prompts/get
2. Update parameter names and formats
3. Let AI assistant follow the prompt workflow
4. Remove special iteration handling (now conversational)
5. Update error handling for step-by-step failures

Migrating from build_cluster_expression Tool

Old Approach (L3 Tool):

{
  "name": "build_cluster_expression",
  "arguments": {
    "audience_description": "software engineers in San Francisco"
  }
}

New Approach (Prompt):

{
  "method": "prompts/get",
  "params": {
    "name": "build_cluster_expression",
    "arguments": {
      "description": "software engineers in San Francisco"
    }
  }
}

Key Differences:

1. Parameter Name - description instead of audience_description
2. Intermediate Visibility - Agent shows cluster search results, geocoding, etc.
3. Refinement - Conversational ("try broader criteria") instead of tool re-invocation
4. Expression Building - Visible AND/OR logic decisions

Best Practices

For AI Assistants

1. Follow Steps Sequentially - Complete each step before moving to the next
2. Check Success Criteria - Validate outputs meet the criteria before proceeding
3. Show Your Work - Explain tool calls and reasoning at each step
4. Handle Low Quality - If resolution rate < 20%, suggest improvements
5. Adapt to Data - Adjust domain selection, criteria extraction based on results
6. Provide Clear Outputs - Summarize final results in user-friendly format

For Users

1. Provide Context - Rich market context improves domain/criteria selection
2. Start Simple - Use basic arguments first, add hints if needed
3. Review Intermediate Steps - Check schema detection, cluster matches
4. Iterate Conversationally - Ask for refinements naturally ("focus on enterprise")
5. Leverage Resources - Use resources/read to inspect results

Example: Complete analyze_customers Workflow

User: "Analyze my customer data"

AI: I'll help you analyze your customer data. First, I need to upload your CSV file.
[Calls generate_url_for_upload]

User: [Uploads customers.csv]

AI: Great! Now I'll get the analyze_customers prompt template.
[Calls prompts/get with workflow_id, csv_filename, market_context]

AI: I'll follow the 7-step workflow. Starting with schema detection...
[Calls resources/read with ?offset=0&limit=10]

AI: I've detected email and phone columns. Now resolving identities...
[Calls resolve_identities with detected schema]

AI: Resolution rate is 78%. Now selecting enrichment domains...
[AI analyzes market context and selects: professional, firmographic, geographic, technographic]

AI: Enriching profiles with selected domains...
[Calls get_person with person IDs and domains]

AI: Aggregating cluster frequencies...
[Calls group_people_by_trait]

AI: Calculating lift scores...
[Calls calculate_trait_lift]

AI: Generating ICP personas...
[Synthesizes 3 personas with targeting expressions]

AI: Here's your ICP analysis:

**Persona 1: Technical Decision Makers**
- Description: Senior engineering leaders at mid-sized B2B SaaS companies
- Key Traits:
  - Job Title: Engineering Manager (lift: 5.2x)
  - Company Size: 50-200 employees (lift: 3.8x)
  - Industry: B2B SaaS (lift: 4.1x)
- Targeting Expression (Precision): cluster:abc123 AND cluster:def456 AND cluster:ghi789
- Estimated Reach: ~2,500 people

This example shows the conversational flow where the AI assistant follows the prompt workflow autonomously while keeping the user informed.

Error Handling

Resolution Rate Too Low

Prompt Guidance:

If resolution rate < 20%, analysis may not be meaningful. Consider:
- Better data quality
- Different identifier types
- Larger sample size

AI Response Example:

Warning: Only 15% of identifiers were resolved. This is below the 20% threshold for meaningful analysis.

Suggestions:
1. Check if email formats are valid
2. Try including phone or address columns
3. Verify this is the correct customer data file

Would you like to try with different columns or upload a different file?

Cluster Search No Results

Prompt Guidance:

If similarity < 0.5, criterion may be too vague or specific
Consider alternative clusters from results

AI Response Example:

I couldn't find good matches for "VP". The best match was "Vice President" with similarity 0.45, which is below the 0.5 threshold.

Try being more specific:
- "VP of Engineering"
- "VP of Sales"
- "VP of Marketing"

Would you like me to try a more specific criterion?

Advanced Usage

Custom Domain Selection

While analyze_customers prompt includes domain selection, you can guide it:

{
  "market_context": "B2B SaaS for marketing automation. Focus on technographic and behavioral data to understand tool usage patterns."
}

The AI will prioritize technographic and behavioral domains based on this context.

Geographic Targeting

For build_cluster_expression, provide location hints:

{
  "description": "software engineers in San Francisco Bay Area",
  "context": "Targeting requires 50km radius around San Francisco to include South Bay"
}

The AI will use the context to select appropriate radius.

Size Constraints

Guide expression building with size hints:

{
  "description": "marketing managers with 5+ years experience, target audience around 10K",
  "context": "ABM campaign with 10K target size"
}

The AI will adjust AND/OR logic to hit the size target.

Next Steps

• Review MCP Resources for file access workflows
• Explore L2 Core Tools used by prompts
• Check API Integration for caching and rate limits
• Read Getting Started for authentication setup