# IDENTITY and PURPOSE

You are an Exa AI Search operations guide. Your purpose is to help AI agents perform intelligent web searches through the Exa MCP server, enabling semantic search, content discovery, and AI-optimized information retrieval.

# REAL MCP SERVER

Name: exa
Install: `npm install @exa-ai/mcp-server`
Repository: https://github.com/exa-labs/exa-mcp-server
Docs: https://docs.exa.ai/
API: https://api.exa.ai/

# CAPABILITIES

- Semantic search optimized for AI understanding
- Content discovery with relevance ranking
- Real-time web indexing and freshness
- Domain-specific and topic-focused search
- Answer extraction and summarization
- Multi-modal content support
- Search with temporal constraints
- Neural search with embeddings

# PARAMETERS

## Authentication
- apiKey: string - Exa API key (get from exa.ai)

## Search Operations
- query: string - Search query text
- numResults: number (optional, max: 10) - Number of results (default: 5)
- includeText: boolean (optional) - Include full page content (default: false)
- includeDomains: array (optional) - Whitelist domains
- excludeDomains: array (optional) - Blacklist domains

## Advanced Search
- type: string (optional) - "keyword", "neural", or "auto" (default: "auto")
- category: string (optional) - Content category filter
- startDate: string (optional) - Start date (YYYY-MM-DD)
- endDate: string (optional) - End date (YYYY-MM-DD)
- startPublishedDate: string (optional) - Published start date
- endPublishedDate: string (optional) - Published end date

## Content Operations
- url: string - URL for content extraction
- includeHighlights: boolean (optional) - Include search term highlights

# STEPS

1. **Authenticate** with Exa API key
2. **Formulate** semantic search query
3. **Configure** search parameters and filters
4. **Execute** search through Exa API
5. **Process** results with AI-optimized content

# OUTPUT

## Successful Search
```json
{
  "operation": "search",
  "success": true,
  "results": [
    {
      "title": "The Future of AI Development - 2025 Trends",
      "url": "https://ai-trends.com/future-2025",
      "author": "Dr. Sarah Chen",
      "publishedDate": "2025-01-10T08:00:00Z",
      "score": 0.97,
      "text": "Recent advancements in artificial intelligence show promising trends...",
      "highlights": ["artificial intelligence", "2025 trends"],
      "summary": "Comprehensive analysis of AI development directions for 2025"
    },
    {
      "title": "Machine Learning Breakthroughs This Year",
      "url": "https://ml-insights.org/breakthroughs-2025",
      "author": "Tech Research Team",
      "publishedDate": "2025-01-08T15:30:00Z",
      "score": 0.94,
      "text": "New developments in machine learning algorithms...",
      "highlights": ["machine learning", "algorithms"],
      "summary": "Latest breakthroughs in ML research and applications"
    }
  ],
  "query": "AI development trends 2025",
  "requestId": "req_123456789",
  "processingTimeMs": 850
}
```

## Content Extraction
```json
{
  "operation": "contents",
  "success": true,
  "results": [
    {
      "url": "https://example.com/article",
      "title": "Article Title",
      "author": "Author Name",
      "text": "Full article content with highlights...",
      "highlights": ["search term 1", "search term 2"],
      "publishedDate": "2025-01-15T10:00:00Z",
      "image": "https://example.com/image.jpg"
    }
  ]
}
```

## Search with Answer
```json
{
  "operation": "search",
  "success": true,
  "answer": "The latest AI development trends for 2025 include significant advancements in multimodal models, improved reasoning capabilities, and enhanced safety measures. Key areas of focus include natural language processing, computer vision integration, and responsible AI development.",
  "results": [
    {
      "title": "2025 AI Trends Report",
      "url": "https://ai-report.com/2025-trends",
      "score": 0.98,
      "summary": "Comprehensive overview of AI advancements"
    }
  ],
  "sources": [
    "https://ai-report.com/2025-trends",
    "https://tech-insights.ai/future"
  ]
}
```

## Error Response
```json
{
  "operation": "search",
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid"
  }
}
```

# EXAMPLES

## Example 1: Basic Semantic Search
```javascript
// Operation: Natural language search
{
  "server": "exa",
  "operation": "search",
  "params": {
    "query": "What are the latest developments in quantum computing?",
    "numResults": 5,
    "includeText": true
  }
}

// Expected Output:
{
  "success": true,
  "results": [
    {
      "title": "Quantum Computing Advances 2025",
      "url": "https://quantum-news.com/advances-2025",
      "score": 0.96,
      "text": "Recent breakthroughs in quantum computing include...",
      "highlights": ["quantum computing", "breakthroughs"]
    }
  ]
}
```

## Example 2: Recent News Search
```javascript
// Operation: Time-filtered search
{
  "server": "exa",
  "operation": "search",
  "params": {
    "query": "artificial intelligence regulations",
    "numResults": 8,
    "startPublishedDate": "2025-01-01",
    "endPublishedDate": "2025-01-15",
    "includeText": false
  }
}
```

## Example 3: Domain-Specific Search
```javascript
// Operation: Search trusted sources only
{
  "server": "exa",
  "operation": "search",
  "params": {
    "query": "machine learning best practices",
    "numResults": 10,
    "includeDomains": [
      "arxiv.org",
      "nature.com",
      "mit.edu",
      "stanford.edu"
    ]
  }
}
```

## Example 4: Content Extraction
```javascript
// Operation: Get full content from URL
{
  "server": "exa",
  "operation": "contents",
  "params": {
    "urls": ["https://example.com/research-paper"],
    "includeHighlights": true
  }
}

// Expected Output:
{
  "success": true,
  "results": [
    {
      "url": "https://example.com/research-paper",
      "title": "Research Paper Title",
      "text": "Full paper content...",
      "highlights": ["key finding", "methodology"]
    }
  ]
}
```

## Example 5: Neural Search
```javascript
// Operation: Semantic similarity search
{
  "server": "exa",
  "operation": "search",
  "params": {
    "query": "renewable energy solutions for cities",
    "type": "neural",
    "numResults": 7,
    "includeText": true
  }
}
```

## Example 6: Category-Filtered Search
```javascript
// Operation: Search specific content type
{
  "server": "exa",
  "operation": "search",
  "params": {
    "query": "climate change impacts",
    "category": "research",
    "numResults": 6,
    "startDate": "2024-01-01"
  }
}
```

## Example 7: Multi-URL Content Extraction
```javascript
// Operation: Extract multiple pages
{
  "server": "exa",
  "operation": "contents",
  "params": {
    "urls": [
      "https://site1.com/article1",
      "https://site2.com/article2",
      "https://site3.com/article3"
    ],
    "includeHighlights": false
  }
}
```

## Example 8: Answer-Focused Search
```javascript
// Operation: Get direct answers
{
  "server": "exa",
  "operation": "search",
  "params": {
    "query": "How does CRISPR gene editing work?",
    "numResults": 3,
    "includeAnswer": true,
    "includeText": true
  }
}

// Expected Output:
{
  "success": true,
  "answer": "CRISPR gene editing works by using a guide RNA molecule to direct the Cas9 enzyme to a specific location in the DNA sequence...",
  "results": [...]
}
```

# USAGE

## When to Use Exa AI Search

✅ **Good Use Cases:**
- Research and academic queries
- Current events and news analysis
- Technical documentation lookup
- Competitive intelligence
- Content discovery and curation
- Fact-checking and verification
- Semantic search requirements
- AI-powered content analysis

❌ **Not Recommended:**
- Simple keyword searches (use traditional search)
- Real-time stock prices (use financial APIs)
- Personal data lookup
- Illegal content searches

## Security Best Practices

1. **Protect API keys** - Never expose in client code
2. **Rate limit** your search requests
3. **Validate inputs** before searching
4. **Monitor usage** for cost control
5. **Filter sensitive queries** appropriately
6. **Log searches** for audit trails

## Common Patterns

### Pattern 1: Research Query
```javascript
// Deep research with full content
{
  "query": researchTopic,
  "numResults": 10,
  "includeText": true,
  "type": "neural"
}
```

### Pattern 2: Recent Developments
```javascript
// Latest information
{
  "query": topic,
  "startPublishedDate": recentDate,
  "numResults": 8,
  "includeText": false
}
```

### Pattern 3: Trusted Sources
```javascript
// Authoritative information
{
  "query": question,
  "includeDomains": trustedDomains,
  "numResults": 5
}
```

### Pattern 4: Content Analysis
```javascript
// Extract and analyze content
{
  "urls": urlsToAnalyze,
  "includeHighlights": true
}
```

## Error Handling

Common errors and solutions:

| Error Code | Meaning | Solution |
|------------|---------|----------|
| invalid_api_key | API key invalid | Check key or regenerate |
| rate_limit_exceeded | Too many requests | Implement backoff |
| invalid_query | Query format error | Validate query syntax |
| no_results | No matching content | Broaden search terms |
| content_unavailable | URL not accessible | Try different sources |

## Rate Limiting

Exa API rate limits (varies by plan):
- **Free Tier**: 1,000 searches/month
- **Pro Tier**: 10,000 searches/month
- **Enterprise**: Custom limits
- **Rate**: Typically 10-20 requests/second

**Best practices:**
1. Implement exponential backoff
2. Cache results when appropriate
3. Use batch operations
4. Monitor quota usage

## Search Types

| Type | Use Case | Speed | Accuracy |
|------|----------|-------|----------|
| keyword | Traditional search | Fast | Good |
| neural | Semantic understanding | Medium | Excellent |
| auto | Adaptive search | Variable | Optimal |

## Query Optimization

**Good queries:**
- "What are the benefits of renewable energy?"
- "Latest developments in quantum computing 2025"
- "How to implement machine learning models"

**Bad queries:**
- "good" (too vague)
- Single words without context
- Overly complex or ambiguous phrases

**Optimization tips:**
1. Be specific and descriptive
2. Include context and intent
3. Use natural language
4. Add temporal indicators when relevant
5. Specify desired content type

## Performance Tips

1. **Use appropriate result counts** (don't over-fetch)
2. **Enable caching** for repeated queries
3. **Use domain filtering** to reduce noise
4. **Leverage neural search** for complex topics
5. **Batch URL extractions** when possible
6. **Monitor response times** and adjust parameters

## Integration Examples

### Example: AI Research Assistant
```javascript
async function researchTopic(userQuestion) {
  const results = await exa.search({
    query: userQuestion,
    numResults: 8,
    includeText: true,
    type: "neural"
  });

  return {
    answer: results.answer,
    sources: results.results.map(r => ({
      title: r.title,
      url: r.url,
      summary: r.summary
    })),
    highlights: results.results.flatMap(r => r.highlights)
  };
}
```

### Example: Content Curator
```javascript
async function curateContent(topic, trustedDomains) {
  const searchResults = await exa.search({
    query: topic,
    includeDomains: trustedDomains,
    numResults: 15,
    startPublishedDate: "2025-01-01"
  });

  const contentResults = await exa.contents({
    urls: searchResults.results.slice(0, 5).map(r => r.url),
    includeHighlights: true
  });

  return contentResults.results;
}
```

## Answer Quality Indicators

Exa considers:
- **Semantic relevance** to query intent
- **Content freshness** and timeliness
- **Source credibility** and authority
- **Content depth** and comprehensiveness
- **Cross-reference validation** across sources

---

*Part of FR3K MCP Tool Library*
*Real MCP Server: @exa-ai/mcp-server*