> For the complete documentation index, see [llms.txt](https://mcp.conserver.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mcp.conserver.io/guide/prompts.md).

# Query Prompts

## Overview

Prompts are pre-built query templates that help you effectively search and retrieve vCons using the MCP server's search tools. They guide you on:

* **Exact match searches** using tags
* **Keyword searches** for specific phrases
* **Semantic searches** for natural language queries
* **Complex multi-criteria searches** combining multiple filters
* **Best practices** for different query scenarios

## Available Prompts

### 1. Find by Exact Tags

**Prompt:** `find_by_exact_tags`

**Use when:** You need precise category matching with specific tag values.

**Example queries:**

* "Find all customers from June that were tagged as 'angry'"
* "Show me high-priority sales calls"
* "List all support tickets marked as urgent"

**Arguments:**

* `tag_criteria` (required): Natural language description of tags to match
* `date_range` (optional): Date range description

**What it teaches:**

* How to parse natural language into specific tag key-value pairs
* Converting date descriptions to ISO 8601 format
* Using the `search_by_tags` tool effectively
* When to use `get_unique_tags` to discover available tags

***

### 2. Find by Semantic Search

**Prompt:** `find_by_semantic_search`

**Use when:** You want to find conversations by meaning, not just exact words.

**Example queries:**

* "Find all the angry customers from June"
* "Show me conversations about billing problems"
* "Locate positive customer feedback"

**Arguments:**

* `search_description` (required): Natural language description of what you're looking for
* `date_range` (optional): Date range description

**What it teaches:**

* How semantic search finds meaning beyond keywords
* Understanding similarity thresholds (0.6-0.8)
* Using the `search_vcons_semantic` tool
* When embeddings are required vs. keyword search

***

### 3. Find by Keywords

**Prompt:** `find_by_keywords`

**Use when:** You need to find specific words or phrases in conversation content.

**Example queries:**

* "Find conversations mentioning 'refund'"
* "Search for 'technical support' in dialogs"
* "Locate invoice #12345 discussions"

**Arguments:**

* `keywords` (required): Specific keywords or phrases to search
* `filters` (optional): Additional filters like dates, tags, parties

**What it teaches:**

* Full-text search capabilities
* What content is searchable (dialog, analysis, subject, parties)
* Using the `search_vcons_content` tool
* Interpreting relevance scores and snippets

***

### 4. Find Recent by Topic

**Prompt:** `find_recent_by_topic`

**Use when:** You need recent conversations filtered by topic or category.

**Example queries:**

* "Show me recent support calls"
* "Find this week's sales conversations"
* "List today's billing inquiries"

**Arguments:**

* `topic` (required): Topic or category to search
* `timeframe` (optional): Recency timeframe (default: last 30 days)

**What it teaches:**

* Converting relative time phrases to date ranges
* Choosing between tag-based and semantic search
* Combining date filters with topic searches
* Sorting and presenting time-sensitive results

***

### 5. Find by Customer/Party

**Prompt:** `find_by_customer`

**Use when:** You need all conversations involving a specific person.

**Example queries:**

* "Find all conversations with <john@example.com>"
* "Show me calls from 555-1234"
* "List all interactions with Jane Smith"

**Arguments:**

* `party_identifier` (required): Name, email, or phone number
* `date_range` (optional): Date range to filter results

**What it teaches:**

* Identifying party type (email vs. phone vs. name)
* Using the appropriate party filter
* Using the `search_vcons` tool with party parameters
* Understanding case-insensitive and partial matching

***

### 6. Discover Available Tags

**Prompt:** `discover_available_tags`

**Use when:** You want to explore what tags exist in your system.

**Example queries:**

* "What tags are available for filtering?"
* "Show me all department tags"
* "List available priority levels"

**Arguments:**

* `tag_category` (optional): Focus on specific tag category

**What it teaches:**

* Using the `get_unique_tags` tool
* Understanding tag structure (key-value pairs)
* Viewing tag usage counts
* Building effective tag-based queries

***

### 7. Complex Multi-Criteria Search

**Prompt:** `complex_search`

**Use when:** You need to combine multiple search criteria.

**Example queries:**

* "Find high-priority sales calls from Q1 where customer mentioned pricing"
* "Show angry customers from the support department this month"
* "List urgent billing issues from last week"

**Arguments:**

* `search_criteria` (required): Complete search description with all criteria

**What it teaches:**

* Breaking down complex queries into components
* Choosing the right search strategy for mixed criteria
* Combining tags, keywords, dates, and semantic search
* Using the `search_vcons_hybrid` tool effectively

***

### 8. Find Similar Conversations

**Prompt:** `find_similar_conversations`

**Use when:** You want to find conversations similar to a specific one.

**Example queries:**

* "Find conversations similar to UUID abc-123-def"
* "Show me calls like this customer complaint"
* "Locate similar support tickets"

**Arguments:**

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

**What it teaches:**

* Using vCon embeddings for similarity
* Adjusting similarity thresholds
* Understanding semantic similarity scores
* When to use UUID vs. description

***

### 9. Help Me Search

**Prompt:** `help_me_search`

**Use when:** You're unsure which search approach to use.

**Example queries:**

* "How do I find billing disputes?"
* "What's the best way to search for recent angry customers?"
* "Should I use tags or keywords for this search?"

**Arguments:**

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

**What it teaches:**

* Decision tree for choosing search tools
* Understanding exact match vs. keyword vs. semantic search
* Query optimization strategies
* Common pitfalls to avoid

***

## How to Use Prompts

### In Claude Desktop or Compatible MCP Clients

1. **List available prompts:** The client will automatically discover prompts from the server.
2. **Select a prompt:** Choose the prompt that matches your use case.
3. **Fill in arguments:** Provide the required information (e.g., search criteria, date range).
4. **Execute:** The prompt will guide you with a detailed strategy and example tool calls.

### Example Workflow

**User Goal:** Find angry customers from June

1. **Choose Prompt:** `find_by_exact_tags` (if you have sentiment tags) or `find_by_semantic_search` (for natural language)
2. **Provide Arguments:**
   * `tag_criteria`: "angry customers"
   * `date_range`: "from June"
3. **Follow Guidance:** The prompt will show:
   * How to parse "angry" into `{sentiment: "angry"}`
   * How to convert "June" to ISO 8601 dates
   * Which tool to call (`search_by_tags`)
   * Example JSON for the tool call
4. **Execute Tool:** Use the suggested tool with parameters
5. **Review Results:** Get matching vCons with UUIDs and details

***

## Search Strategy Decision Tree

Use this flowchart to choose the right prompt:

```
Do you know the exact tag value?
├─ YES → Use "find_by_exact_tags"
└─ NO
   ├─ Do you need specific words/phrases?
   │  └─ YES → Use "find_by_keywords"
   └─ NO
      ├─ Are you searching by meaning/concept?
      │  └─ YES → Use "find_by_semantic_search"
      └─ NO
         ├─ Is this a person/party search?
         │  └─ YES → Use "find_by_customer"
         └─ NO
            ├─ Multiple criteria?
            │  └─ YES → Use "complex_search"
            └─ UNSURE → Use "help_me_search"
```

***

## Prompt Benefits

### 1. Educational

Prompts teach you:

* How the search tools work
* Best practices for each scenario
* Parameter optimization
* Error handling and fallbacks

### 2. Efficient

Prompts provide:

* Pre-structured queries
* Example JSON for tool calls
* Step-by-step guidance
* Time-saving templates

### 3. Comprehensive

Prompts cover:

* All search tool variations
* Date parsing and formatting
* Tag discovery and usage
* Multi-criteria combining

***

## Search Tool Reference

Here's a quick reference of the tools prompts will guide you to use:

| Tool                    | Purpose                 | Key Parameters                            |
| ----------------------- | ----------------------- | ----------------------------------------- |
| `search_vcons`          | Basic metadata search   | party\_name, party\_email, subject, dates |
| `search_vcons_content`  | Keyword search          | query, tags, dates                        |
| `search_vcons_semantic` | Semantic/meaning search | query, threshold, tags                    |
| `search_vcons_hybrid`   | Combined approach       | query, semantic\_weight, tags             |
| `search_by_tags`        | Exact tag matching      | tags (object), limit                      |
| `get_unique_tags`       | Discover available tags | include\_counts, key\_filter              |
| `get_vcon`              | Retrieve specific vCon  | uuid                                      |

***

## Common Use Cases

### Customer Service

* **Find escalated issues:** `find_by_exact_tags` with priority tags
* **Search complaints:** `find_by_semantic_search` for "complaints" or "issues"
* **Track customer history:** `find_by_customer` with email/phone

### Sales

* **High-value opportunities:** `find_by_exact_tags` with priority + department
* **Pricing discussions:** `find_by_keywords` searching for "pricing" or "quote"
* **Recent qualified leads:** `find_recent_by_topic` with "sales" topic

### Analytics

* **Sentiment analysis:** `find_by_exact_tags` or `find_by_semantic_search` for sentiment
* **Topic clustering:** `find_similar_conversations` to group related calls
* **Trend discovery:** `find_recent_by_topic` with time ranges

### Compliance

* **Audit trails:** `find_by_customer` for specific party interactions
* **Keyword monitoring:** `find_by_keywords` for compliance terms
* **Tag validation:** `discover_available_tags` to review taxonomy

***

## Tips and Best Practices

### Start Broad, Then Narrow

1. Begin with `discover_available_tags` to see what's possible
2. Use `help_me_search` to understand the best approach
3. Execute the recommended search
4. Refine with additional filters if needed

### Use Date Filters Effectively

* **Relative:** "last week", "this month", "Q1"
* **Absolute:** "June 2024", "2024-01-01 to 2024-03-31"
* **Recent:** Defaults to last 30 days in most prompts

### Tag Strategy

* Use `get_unique_tags` first to discover what tags exist
* Tag searches are EXACT - "angry" won't match "frustrated"
* Combine tags with AND logic (all must match)
* Consider semantic search for fuzzy matching

### Semantic Search Considerations

* Requires pre-generated embeddings
* Works across synonyms and paraphrases
* Adjust threshold based on precision needs:
  * 0.6-0.7: Broader results
  * 0.7-0.8: Balanced
  * 0.8-0.9: Very similar only

### Performance Optimization

* Always use date filters for "recent" queries
* Limit results to what you need (10-50)
* Use tags to pre-filter before content search
* Start with exact matches, fall back to semantic

***

## Integration with Other Features

### With Resources

After finding vCons, access them via resources:

```
vcon://v1/vcons/{uuid}
```

### With Tags

Use prompts to search, then use tag tools to organize:

* `manage_tag` - Add/update/remove tags
* `get_tags` - View existing tags
* `remove_all_tags` - Clear tags

### With Database Tools

Combine prompt-guided searches with:

* `get_database_stats` - Analyze search performance
* `analyze_query` - Optimize slow searches

***

## Troubleshooting

### "No results found"

1. Try `discover_available_tags` to verify tags exist
2. Broaden date range or remove filters
3. Use semantic search for fuzzy matching
4. Check if embeddings are generated (for semantic search)

### "Embedding generation not yet implemented"

1. Fall back to `search_vcons_content` for keywords
2. Or generate embeddings using provided scripts
3. Or use `search_vcons_hybrid` with low semantic weight

### Too many results

1. Add date range filters
2. Include more specific tags
3. Use more specific keywords
4. Increase semantic threshold

### Wrong results

1. Verify tag values with `get_unique_tags`
2. Check date format (should be ISO 8601)
3. Try different search strategy (exact vs. semantic)
4. Use `help_me_search` prompt for guidance

***

## Next Steps

* **Try the prompts:** Start with `help_me_search` to explore
* **Learn the tools:** Each prompt teaches specific tool usage
* **Optimize queries:** Use insights to build better searches
* **Discover your data:** Use `discover_available_tags` to understand your corpus

For more information:

* [Search Guide](/guide/search.md) - Detailed search tool documentation
* [Tags Guide](/guide/tags.md) - Tag system documentation
* [Getting Started](/guide/getting-started.md) - Getting started guide