# MCP Prompts

Prompts are reusable query templates that help users effectively search and retrieve vCons. They provide guided workflows for common search patterns.

## Overview

The vCon MCP Server provides 9 prompt templates:

1. [**find\_by\_exact\_tags**](#find_by_exact_tags) - Exact tag matching
2. [**find\_by\_semantic\_search**](#find_by_semantic_search) - AI-powered meaning search
3. [**find\_by\_keywords**](#find_by_keywords) - Keyword/phrase search
4. [**find\_recent\_by\_topic**](#find_recent_by_topic) - Recent conversations by topic
5. [**find\_by\_customer**](#find_by_customer) - Search by party/customer
6. [**discover\_available\_tags**](#discover_available_tags) - Explore available tags
7. [**complex\_search**](#complex_search) - Multi-criteria searches
8. [**find\_similar\_conversations**](#find_similar_conversations) - Find similar vCons
9. [**help\_me\_search**](#help_me_search) - Query strategy guidance

***

## Prompt Definitions

### find\_by\_exact\_tags

Find vCons using exact tag matches for precise queries.

**Arguments:**

* `tag_criteria` (required): Natural language description of tags to match
  * Examples: "angry customers", "high priority sales", "department support"
* `date_range` (optional): Date range description
  * Examples: "from June", "last week", "Q1 2024"

**Best For:**

* Queries with known categories
* Filtering by metadata
* Precise department/priority/status matching

**Example Usage:**

```
Query: "Find all angry customers from June"
tag_criteria: "angry customers"
date_range: "from June"

→ Guides to: search_by_tags with {sentiment: "angry"}
```

**Strategy:**

1. Parse tag criteria to identify key-value pairs
2. Convert date range to ISO 8601
3. Use `search_by_tags` tool
4. Handle exact matching (no fuzzy logic)

***

### find\_by\_semantic\_search

Find vCons using AI-powered semantic search to understand meaning and intent.

**Arguments:**

* `search_description` (required): Natural language description
  * Examples: "angry customers", "billing disputes", "positive feedback"
* `date_range` (optional): Date range description

**Best For:**

* Concept-based queries
* Finding similar meanings
* Natural language questions
* Fuzzy matching needs

**Example Usage:**

```
Query: "Find frustrated customers from last month"
search_description: "frustrated customers"
date_range: "last month"

→ Guides to: search_vcons_semantic
→ Matches: angry, upset, dissatisfied, complaining (similar concepts)
```

**Strategy:**

1. Understand intent (AI embeddings)
2. Find related concepts and synonyms
3. Use `search_vcons_semantic` tool
4. Adjust similarity threshold as needed

***

### find\_by\_keywords

Find vCons containing specific keywords or phrases.

**Arguments:**

* `keywords` (required): Keywords or phrases to search for
  * Examples: "refund", "billing issue", "technical support"
* `filters` (optional): Additional filters (tags, dates, parties)

**Best For:**

* Exact word matching
* Specific terminology
* Phrase searches
* ID or code lookups

**Example Usage:**

```
Query: "Find conversations mentioning 'refund' or 'billing issue'"
keywords: "refund OR billing issue"
filters: "department: support"

→ Guides to: search_vcons_content
```

**What Gets Searched:**

* ✅ Subject lines
* ✅ Dialog bodies
* ✅ Analysis bodies
* ✅ Party information
* ❌ Attachments (not indexed)

**Strategy:**

1. Extract specific keywords
2. Parse additional filters
3. Use `search_vcons_content` tool
4. Review relevance scores and snippets

***

### find\_recent\_by\_topic

Find recent vCons filtered by topic or category.

**Arguments:**

* `topic` (required): Topic or category
  * Examples: "support", "sales", "billing"
* `timeframe` (optional): Recency timeframe
  * Examples: "today", "this week", "last 7 days", "this month"
  * Default: "recent" (last 30 days)

**Best For:**

* Dashboard views
* Recent activity monitoring
* Time-sensitive queries
* Category browsing

**Example Usage:**

```
Query: "Show me recent support calls"
topic: "support"
timeframe: "this week"

→ Combines date filtering with topic search
```

**Strategy:**

1. Convert timeframe to date range
2. Determine if topic is tag or concept
3. Choose appropriate search tool
4. Apply date filtering

***

### find\_by\_customer

Find all vCons involving a specific customer, party, or participant.

**Arguments:**

* `party_identifier` (required): Customer/party identifier
  * Email: `john@example.com`
  * Phone: `+1-555-1234`
  * Name: `John Smith`
* `date_range` (optional): Date range to filter

**Best For:**

* Customer history lookup
* Party-specific searches
* Contact tracing
* Relationship mapping

**Example Usage:**

```
Query: "Find all conversations with john@example.com"
party_identifier: "john@example.com"

→ Guides to: search_vcons with party_email filter
```

**Search Behavior:**

* `party_name`: Case-insensitive partial match
* `party_email`: Exact match
* `party_tel`: Exact match

**Strategy:**

1. Identify party type (email/phone/name)
2. Use `search_vcons` with appropriate filter
3. Show all parties in each conversation
4. Suggest follow-up actions

***

### discover\_available\_tags

Discover what tags are available in the system for filtering.

**Arguments:**

* `tag_category` (optional): Focus on specific tag category
  * Examples: "department", "priority", "sentiment"

**Best For:**

* Exploring data
* Understanding tag schema
* Planning searches
* Documentation

**Example Usage:**

```
Query: "What tags are available for filtering?"
→ Uses: get_unique_tags with include_counts

Response shows:
{
  "department": ["sales", "support", "billing"],
  "priority": ["high", "medium", "low"],
  "sentiment": ["positive", "neutral", "negative"]
}
```

**Strategy:**

1. Use `get_unique_tags` tool
2. Organize by category
3. Show usage counts
4. Suggest example searches

***

### complex\_search

Perform complex searches combining multiple criteria: tags, keywords, dates, and semantic meaning.

**Arguments:**

* `search_criteria` (required): Complete search description
  * Example: "high-priority sales calls from Q1 mentioning pricing"

**Best For:**

* Multi-dimensional queries
* Business intelligence
* Complex filtering
* Advanced searches

**Example Usage:**

```
Query: "Find high-priority sales calls from Q1 where customer mentioned pricing"
search_criteria: "high-priority sales calls from Q1 mentioning pricing"

→ Parses into:
  - Tags: {priority: "high", department: "sales"}
  - Date: Q1 2024 (Jan 1 - Mar 31)
  - Content: "pricing"
→ Uses: search_vcons_hybrid or search_vcons_content
```

**Strategy:**

1. Parse criteria into components (tags, dates, keywords, concepts)
2. Choose best search strategy
3. Build comprehensive query
4. Refine results as needed

***

### find\_similar\_conversations

Find conversations similar to a specific vCon or topic.

**Arguments:**

* `reference` (required): vCon UUID or topic description
* `limit` (optional): Number of results (default: 10)

**Best For:**

* Similar issue lookup
* Pattern discovery
* Related conversation finding
* Contextual search

**Example Usage:**

```
Query: "Find conversations similar to this one"
reference: "123e4567-e89b-12d3-a456-426614174000"
limit: "10"

→ Uses semantic similarity to find related vCons
```

**Strategy:**

1. Determine if reference is UUID or description
2. Extract or generate embedding
3. Use `search_vcons_semantic` with similarity threshold
4. Adjust threshold for precision vs recall

***

### help\_me\_search

Get guidance on the best way to search for vCons based on your needs.

**Arguments:**

* `what_you_want` (required): Description of what you're trying to find

**Best For:**

* New users
* Complex queries
* Strategy planning
* Tool selection

**Example Usage:**

```
Query: "I want to find frustrated customers who complained about billing"
what_you_want: "frustrated customers who complained about billing"

→ Analyzes query type
→ Recommends: search_vcons_semantic or search_vcons_hybrid
→ Provides step-by-step guidance
```

**Decision Tree:**

| Query Type        | Recommended Tool               |
| ----------------- | ------------------------------ |
| Exact tag values  | `search_by_tags`               |
| Specific keywords | `search_vcons_content`         |
| Natural language  | `search_vcons_semantic`        |
| Mixed criteria    | `search_vcons_hybrid`          |
| Party information | `search_vcons` (party filters) |
| Date ranges       | Any tool + date filters        |

***

## Using Prompts

### Claude Desktop

Prompts appear in the prompt selector:

```typescript
// User selects prompt: "find_by_exact_tags"
// Fills in arguments:
//   tag_criteria: "angry customers"
//   date_range: "June 2024"

// Claude receives guidance and executes appropriate tools
```

### Custom MCP Client

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: 'my-client',
  version: '1.0.0'
});

// List available prompts
const prompts = await client.listPrompts();

// Get a specific prompt
const prompt = await client.getPrompt({
  name: 'find_by_exact_tags',
  arguments: {
    tag_criteria: 'angry customers',
    date_range: 'June 2024'
  }
});

// The prompt.messages array contains guidance
```

***

## Prompt Strategy Guide

### When to Use Each Prompt

```
📋 Known categories/tags → find_by_exact_tags
🔍 Specific words → find_by_keywords
🤖 Concepts/meaning → find_by_semantic_search
📅 Recent + topic → find_recent_by_topic
👤 Specific person → find_by_customer
🏷️  Explore tags → discover_available_tags
🔧 Multiple criteria → complex_search
🔗 Similar content → find_similar_conversations
❓ Not sure → help_me_search
```

### Query Analysis Flow

```
1. Is it a simple query?
   → Yes: Use specific prompt (tags, keywords, party)
   → No: Continue

2. Does it involve multiple criteria?
   → Yes: Use complex_search
   → No: Continue

3. Is it concept-based or exact words?
   → Concept: Use find_by_semantic_search
   → Exact: Use find_by_keywords

4. Still unsure?
   → Use help_me_search
```

***

## Examples by Use Case

### Customer Service

```typescript
// Find recent angry customers
Prompt: find_recent_by_topic
  topic: "angry customers"
  timeframe: "this week"

// Find all conversations with customer
Prompt: find_by_customer
  party_identifier: "customer@example.com"

// Find billing complaints
Prompt: find_by_keywords
  keywords: "billing complaint refund"
  filters: "department: support"
```

### Sales

```typescript
// Find high-value sales calls
Prompt: find_by_exact_tags
  tag_criteria: "high value sales"
  date_range: "this quarter"

// Find pricing discussions
Prompt: find_by_keywords
  keywords: "pricing discount contract"
  filters: "department: sales"

// Find successful sales patterns
Prompt: find_similar_conversations
  reference: "uuid-of-successful-call"
  limit: "20"
```

### Analytics

```typescript
// Explore available tags
Prompt: discover_available_tags

// Complex multi-criteria search
Prompt: complex_search
  search_criteria: "high-priority support calls from Q1 with negative sentiment"

// Find similar issues
Prompt: find_similar_conversations
  reference: "customer complaint about delays"
  limit: "50"
```

***

## Best Practices

### 1. Start Simple

Begin with specific prompts before moving to complex searches.

### 2. Discover First

Use `discover_available_tags` to understand your data before searching.

### 3. Refine Iteratively

Start broad, then narrow based on results.

### 4. Combine Filters

Use date ranges with every search for better performance.

### 5. Use Right Tool

Let prompts guide you to the appropriate search tool.

***

## Next Steps

* See [Tools Reference](https://mcp.conserver.io/api-reference/tools) for tool details
* See [Resources Reference](https://mcp.conserver.io/api-reference/resources) for URI-based access
* See [Search Guide](https://github.com/vcon-dev/vcon-mcp/blob/main/guide/search.md) for search strategies
* See [Tag Guide](https://github.com/vcon-dev/vcon-mcp/blob/main/guide/tags.md) for tag management