websets_guide
Get guidance on using Exa's content websets to create collections, search web content, enhance data, and set up notifications with practical examples.
Instructions
Get helpful guidance, examples, and workflows for using Exa's content websets effectively. Learn how to create websets, search content, enhance data, and set up notifications with practical examples.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | What you'd like guidance on |
Implementation Reference
- src/tools/websetsGuide.ts:28-448 (handler)The main handler function for the 'websets_guide' tool. It selects predefined guidance content based on the input 'topic' and returns it formatted as markdown text in a content array.handler: async ({ topic }) => { const guides = { getting_started: { title: "Getting Started with Content Websets", content: ` **Welcome to Exa's Content Websets!** Content websets help you gather, organize, and enhance web content at scale. **Available Operations:** - \`create_webset\`, \`list_websets\`, \`get_webset_status\`, \`update_webset\`, \`delete_webset\` - \`search_webset\`, \`get_search_results\`, \`cancel_search\` - \`enhance_content\`, \`get_enhancement_results\`, \`delete_enhancement\` - \`setup_notifications\`, \`list_notifications\`, \`remove_notifications\` - \`list_content_items\` Here's how to get started: **Step 1: Create Your First Webset** Use the websets_manager tool with operation "create_webset": \`\`\` operation: "create_webset" webset: { searchQuery: "AI startups in San Francisco 2024", description: "Research on AI companies in SF", advanced: { resultCount: 20, focusArea: "company" } } \`\`\` **Step 2: Monitor Progress** Check status with operation "get_webset_status": \`\`\` operation: "get_webset_status" resourceId: "your-webset-id" \`\`\` **Step 3: Explore Your Content** Once complete, view items with operation "list_content_items": \`\`\` operation: "list_content_items" resourceId: "your-webset-id" \`\`\` **Next Steps:** - Search within your webset - Enhance content with AI analysis - Set up notifications for updates ` }, creating_websets: { title: "Creating Effective Content Websets", content: ` **Creating Content Websets** Websets take 10-15 minutes to build but provide rich, organized content. **Basic Webset:** \`\`\` operation: "create_webset" webset: { searchQuery: "sustainable fashion brands", description: "Research on eco-friendly clothing companies" } \`\`\` **Advanced Webset with Filters:** \`\`\` operation: "create_webset" webset: { searchQuery: "fintech companies Series A funding", description: "Fintech startups that raised Series A in 2024", advanced: { resultCount: 50, focusArea: "company", criteria: [ { description: "Must have raised Series A funding" }, { description: "Founded after 2020" } ], tags: { "industry": "fintech", "funding_stage": "series_a" } } } \`\`\` **Tips for Better Websets:** - Be specific in your search query - Use criteria to filter results - Set appropriate result counts (10-100) - Add descriptive tags for organization ` }, searching_content: { title: "Searching Within Websets", content: ` **Searching Your Websets** Once a webset is complete, you can search within it for specific information. **Basic Search:** \`\`\` operation: "search_webset" resourceId: "your-webset-id" search: { query: "pricing information", maxResults: 10 } \`\`\` **Advanced Search with Filters:** \`\`\` operation: "search_webset" resourceId: "your-webset-id" search: { query: "executive team leadership bios", maxResults: 20, advanced: { focusArea: { type: "company" }, requirements: [ { description: "Must mention C-level executives" }, { description: "Include background information" } ] } } \`\`\` **Getting Search Results:** \`\`\` operation: "get_search_results" resourceId: "your-search-id" \`\`\` **Search Best Practices:** - Use specific, descriptive queries - Search for concepts, not just keywords - Combine multiple searches for comprehensive coverage ` }, enhancing_data: { title: "Enhancing Content with AI", content: ` **Data Enhancement** Transform raw content into structured, useful data with AI analysis. **Basic Enhancement:** \`\`\` operation: "enhance_content" resourceId: "your-webset-id" enhancement: { task: "Extract company founding year and employee count" } \`\`\` **Structured Enhancement with Options:** \`\`\` operation: "enhance_content" resourceId: "your-webset-id" enhancement: { task: "Categorize company by business model", advanced: { outputFormat: "options", choices: [ { label: "B2B SaaS" }, { label: "B2C Marketplace" }, { label: "Enterprise Software" }, { label: "Consumer App" }, { label: "Other" } ] } } \`\`\` **Specific Data Extraction:** \`\`\` operation: "enhance_content" resourceId: "your-webset-id" enhancement: { task: "Extract CEO email address", advanced: { outputFormat: "email" } } \`\`\` **Enhancement Ideas:** - Extract contact information - Categorize content by type/industry - Score content by relevance - Extract key metrics or numbers - Identify decision makers ` }, setting_notifications: { title: "Setting Up Notifications", content: ` **Webhook Notifications** Get notified when websets, searches, or enhancements complete. **Available Events:** - \`webset.created\` - When a new webset is created - \`webset.idle\` - When webset processing completes - \`webset.deleted\` - When a webset is deleted - \`webset.search.completed\` - When a search finishes - \`webset.search.created\` - When a search starts - \`webset.item.created\` - When new items are added - \`webset.item.enriched\` - When items are enhanced **Basic Notification Setup:** \`\`\` operation: "setup_notifications" notification: { webhookUrl: "https://your-app.com/webhooks/exa", events: ["webset.idle", "webset.search.completed"] } \`\`\` **Comprehensive Notifications:** \`\`\` operation: "setup_notifications" notification: { webhookUrl: "https://your-app.com/webhooks/exa", events: [ "webset.created", "webset.idle", "webset.deleted", "webset.search.completed", "webset.item.created" ], advanced: { tags: { "environment": "production", "team": "research" } } } \`\`\` **Managing Notifications:** - List all: operation "list_notifications" - Get details: operation "get_notification_details" - Remove: operation "remove_notifications" **Webhook Requirements:** - Must use HTTPS URLs - Should return 2xx status codes - Include signature verification for security ` }, workflow_examples: { title: "Complete Workflow Examples", content: ` **Example 1: Competitor Research Workflow** 1. **Create Webset:** \`\`\` operation: "create_webset" webset: { searchQuery: "project management software companies", description: "Research competitors in PM space", advanced: { resultCount: 30, focusArea: "company" } } \`\`\` 2. **Search for Pricing:** \`\`\` operation: "search_webset" resourceId: "webset-id" search: { query: "pricing plans subscription costs" } \`\`\` 3. **Extract Pricing Data:** \`\`\` operation: "enhance_content" resourceId: "webset-id" enhancement: { task: "Extract pricing information and plans", advanced: { outputFormat: "text" } } \`\`\` **Example 2: Lead Generation Workflow** 1. **Create Target Company Webset:** \`\`\` operation: "create_webset" webset: { searchQuery: "healthcare startups seed funding 2024", advanced: { resultCount: 50, criteria: [{ description: "Recently funded startups" }] } } \`\`\` 2. **Find Decision Makers:** \`\`\` operation: "search_webset" resourceId: "webset-id" search: { query: "founder CEO leadership team contact" } \`\`\` 3. **Extract Contact Info:** \`\`\` operation: "enhance_content" resourceId: "webset-id" enhancement: { task: "Extract CEO name and company email", advanced: { outputFormat: "email" } } \`\`\` **Example 3: Market Research Workflow** 1. **Create Industry Webset** 2. **Search for Market Size Data** 3. **Enhance with Trend Analysis** 4. **Set Up Monitoring Notifications** ` }, troubleshooting: { title: "Troubleshooting Common Issues", content: ` **Common Issues and Solutions** **Webset Creation Issues:** - ❌ "Webset failed": Try more specific search queries - ❌ "No results found": Broaden your search terms - ❌ "Timeout": Websets with 100+ results may take longer **Search Issues:** - ❌ "Search returned no results": Try broader query terms - ❌ "Search taking too long": Reduce maxResults parameter **Enhancement Issues:** - ❌ "Enhancement failed": Ensure task is clear and specific - ❌ "Invalid format": Check outputFormat matches your data type **Notification Issues:** - ❌ "Webhook not receiving events": Verify HTTPS URL is accessible - ❌ "Authentication errors": Check webhook signature validation **API Issues:** - ❌ "Authentication failed": Verify EXA_API_KEY is set correctly - ❌ "Rate limiting": Space out requests, respect rate limits **Best Practices:** - Always check webset status before searching/enhancing - Use descriptive resource IDs and tags for organization - Monitor webhook endpoints for reliability - Start with small websets to test workflows ` }, best_practices: { title: "Best Practices and Tips", content: ` **Best Practices for Content Websets** **Webset Design:** - 🎯 Be specific with search queries for better results - 📊 Start with 10-20 results, scale up as needed - 🏷️ Use tags and descriptions for organization - ⏰ Plan for 10-15 minute webset build times **Search Optimization:** - 🔍 Search for concepts, not just keywords - 🎯 Use multiple targeted searches vs one broad search - 📝 Be specific about what information you need - 🔄 Iterate and refine search queries **Enhancement Strategy:** - 📋 Be very specific about what data to extract - 🏗️ Use structured formats (options, email, etc.) when possible - 🎯 One enhancement per specific data type - ✅ Validate enhancement results before scaling **Workflow Efficiency:** - 🔄 Batch similar operations together - 📊 Monitor progress with status checks - 🔔 Use webhooks for long-running operations - 📁 Organize with consistent naming conventions **Resource Management:** - 🏷️ Use meaningful resource IDs and descriptions - 🧹 Clean up unused websets and enhancements - 📊 Track usage with tags and metadata - 🔍 Monitor activities with event listing **Performance Tips:** - ⚡ Use progressive disclosure - start simple, add complexity - 🎯 Target specific data needs vs broad exploration - 📦 Batch related enhancements together - ⏰ Plan workflows around processing times **Security Considerations:** - 🔒 Use HTTPS for all webhook URLs - 🔐 Implement webhook signature verification - 🚫 Avoid logging sensitive data - 🛡️ Validate all input parameters ` } }; const guide = guides[topic as keyof typeof guides]; return { content: [{ type: "text" as const, text: `# ${guide.title}\n\n${guide.content.trim()}\n\n---\n\n**Need more help?** Try other guide topics: ${Object.keys(guides).join(', ')}` }] }; },
- src/tools/websetsGuide.ts:15-25 (schema)Zod schema defining the input parameter 'topic' as an enum of available guidance topics.topic: z.enum([ "getting_started", "creating_websets", "searching_content", "enhancing_data", "setting_notifications", "workflow_examples", "troubleshooting", "best_practices" ]).describe("What you'd like guidance on") },
- src/tools/websetsGuide.ts:11-450 (registration)Initial registration of the 'websets_guide' tool into the local toolRegistry, including name, description, schema, handler, and metadata.toolRegistry["websets_guide"] = { name: "websets_guide", description: "Get helpful guidance, examples, and workflows for using Exa's content websets effectively. Learn how to create websets, search content, enhance data, and set up notifications with practical examples.", schema: { topic: z.enum([ "getting_started", "creating_websets", "searching_content", "enhancing_data", "setting_notifications", "workflow_examples", "troubleshooting", "best_practices" ]).describe("What you'd like guidance on") }, category: ToolCategory.WEBSETS, service: ServiceType.WEBSETS, handler: async ({ topic }) => { const guides = { getting_started: { title: "Getting Started with Content Websets", content: ` **Welcome to Exa's Content Websets!** Content websets help you gather, organize, and enhance web content at scale. **Available Operations:** - \`create_webset\`, \`list_websets\`, \`get_webset_status\`, \`update_webset\`, \`delete_webset\` - \`search_webset\`, \`get_search_results\`, \`cancel_search\` - \`enhance_content\`, \`get_enhancement_results\`, \`delete_enhancement\` - \`setup_notifications\`, \`list_notifications\`, \`remove_notifications\` - \`list_content_items\` Here's how to get started: **Step 1: Create Your First Webset** Use the websets_manager tool with operation "create_webset": \`\`\` operation: "create_webset" webset: { searchQuery: "AI startups in San Francisco 2024", description: "Research on AI companies in SF", advanced: { resultCount: 20, focusArea: "company" } } \`\`\` **Step 2: Monitor Progress** Check status with operation "get_webset_status": \`\`\` operation: "get_webset_status" resourceId: "your-webset-id" \`\`\` **Step 3: Explore Your Content** Once complete, view items with operation "list_content_items": \`\`\` operation: "list_content_items" resourceId: "your-webset-id" \`\`\` **Next Steps:** - Search within your webset - Enhance content with AI analysis - Set up notifications for updates ` }, creating_websets: { title: "Creating Effective Content Websets", content: ` **Creating Content Websets** Websets take 10-15 minutes to build but provide rich, organized content. **Basic Webset:** \`\`\` operation: "create_webset" webset: { searchQuery: "sustainable fashion brands", description: "Research on eco-friendly clothing companies" } \`\`\` **Advanced Webset with Filters:** \`\`\` operation: "create_webset" webset: { searchQuery: "fintech companies Series A funding", description: "Fintech startups that raised Series A in 2024", advanced: { resultCount: 50, focusArea: "company", criteria: [ { description: "Must have raised Series A funding" }, { description: "Founded after 2020" } ], tags: { "industry": "fintech", "funding_stage": "series_a" } } } \`\`\` **Tips for Better Websets:** - Be specific in your search query - Use criteria to filter results - Set appropriate result counts (10-100) - Add descriptive tags for organization ` }, searching_content: { title: "Searching Within Websets", content: ` **Searching Your Websets** Once a webset is complete, you can search within it for specific information. **Basic Search:** \`\`\` operation: "search_webset" resourceId: "your-webset-id" search: { query: "pricing information", maxResults: 10 } \`\`\` **Advanced Search with Filters:** \`\`\` operation: "search_webset" resourceId: "your-webset-id" search: { query: "executive team leadership bios", maxResults: 20, advanced: { focusArea: { type: "company" }, requirements: [ { description: "Must mention C-level executives" }, { description: "Include background information" } ] } } \`\`\` **Getting Search Results:** \`\`\` operation: "get_search_results" resourceId: "your-search-id" \`\`\` **Search Best Practices:** - Use specific, descriptive queries - Search for concepts, not just keywords - Combine multiple searches for comprehensive coverage ` }, enhancing_data: { title: "Enhancing Content with AI", content: ` **Data Enhancement** Transform raw content into structured, useful data with AI analysis. **Basic Enhancement:** \`\`\` operation: "enhance_content" resourceId: "your-webset-id" enhancement: { task: "Extract company founding year and employee count" } \`\`\` **Structured Enhancement with Options:** \`\`\` operation: "enhance_content" resourceId: "your-webset-id" enhancement: { task: "Categorize company by business model", advanced: { outputFormat: "options", choices: [ { label: "B2B SaaS" }, { label: "B2C Marketplace" }, { label: "Enterprise Software" }, { label: "Consumer App" }, { label: "Other" } ] } } \`\`\` **Specific Data Extraction:** \`\`\` operation: "enhance_content" resourceId: "your-webset-id" enhancement: { task: "Extract CEO email address", advanced: { outputFormat: "email" } } \`\`\` **Enhancement Ideas:** - Extract contact information - Categorize content by type/industry - Score content by relevance - Extract key metrics or numbers - Identify decision makers ` }, setting_notifications: { title: "Setting Up Notifications", content: ` **Webhook Notifications** Get notified when websets, searches, or enhancements complete. **Available Events:** - \`webset.created\` - When a new webset is created - \`webset.idle\` - When webset processing completes - \`webset.deleted\` - When a webset is deleted - \`webset.search.completed\` - When a search finishes - \`webset.search.created\` - When a search starts - \`webset.item.created\` - When new items are added - \`webset.item.enriched\` - When items are enhanced **Basic Notification Setup:** \`\`\` operation: "setup_notifications" notification: { webhookUrl: "https://your-app.com/webhooks/exa", events: ["webset.idle", "webset.search.completed"] } \`\`\` **Comprehensive Notifications:** \`\`\` operation: "setup_notifications" notification: { webhookUrl: "https://your-app.com/webhooks/exa", events: [ "webset.created", "webset.idle", "webset.deleted", "webset.search.completed", "webset.item.created" ], advanced: { tags: { "environment": "production", "team": "research" } } } \`\`\` **Managing Notifications:** - List all: operation "list_notifications" - Get details: operation "get_notification_details" - Remove: operation "remove_notifications" **Webhook Requirements:** - Must use HTTPS URLs - Should return 2xx status codes - Include signature verification for security ` }, workflow_examples: { title: "Complete Workflow Examples", content: ` **Example 1: Competitor Research Workflow** 1. **Create Webset:** \`\`\` operation: "create_webset" webset: { searchQuery: "project management software companies", description: "Research competitors in PM space", advanced: { resultCount: 30, focusArea: "company" } } \`\`\` 2. **Search for Pricing:** \`\`\` operation: "search_webset" resourceId: "webset-id" search: { query: "pricing plans subscription costs" } \`\`\` 3. **Extract Pricing Data:** \`\`\` operation: "enhance_content" resourceId: "webset-id" enhancement: { task: "Extract pricing information and plans", advanced: { outputFormat: "text" } } \`\`\` **Example 2: Lead Generation Workflow** 1. **Create Target Company Webset:** \`\`\` operation: "create_webset" webset: { searchQuery: "healthcare startups seed funding 2024", advanced: { resultCount: 50, criteria: [{ description: "Recently funded startups" }] } } \`\`\` 2. **Find Decision Makers:** \`\`\` operation: "search_webset" resourceId: "webset-id" search: { query: "founder CEO leadership team contact" } \`\`\` 3. **Extract Contact Info:** \`\`\` operation: "enhance_content" resourceId: "webset-id" enhancement: { task: "Extract CEO name and company email", advanced: { outputFormat: "email" } } \`\`\` **Example 3: Market Research Workflow** 1. **Create Industry Webset** 2. **Search for Market Size Data** 3. **Enhance with Trend Analysis** 4. **Set Up Monitoring Notifications** ` }, troubleshooting: { title: "Troubleshooting Common Issues", content: ` **Common Issues and Solutions** **Webset Creation Issues:** - ❌ "Webset failed": Try more specific search queries - ❌ "No results found": Broaden your search terms - ❌ "Timeout": Websets with 100+ results may take longer **Search Issues:** - ❌ "Search returned no results": Try broader query terms - ❌ "Search taking too long": Reduce maxResults parameter **Enhancement Issues:** - ❌ "Enhancement failed": Ensure task is clear and specific - ❌ "Invalid format": Check outputFormat matches your data type **Notification Issues:** - ❌ "Webhook not receiving events": Verify HTTPS URL is accessible - ❌ "Authentication errors": Check webhook signature validation **API Issues:** - ❌ "Authentication failed": Verify EXA_API_KEY is set correctly - ❌ "Rate limiting": Space out requests, respect rate limits **Best Practices:** - Always check webset status before searching/enhancing - Use descriptive resource IDs and tags for organization - Monitor webhook endpoints for reliability - Start with small websets to test workflows ` }, best_practices: { title: "Best Practices and Tips", content: ` **Best Practices for Content Websets** **Webset Design:** - 🎯 Be specific with search queries for better results - 📊 Start with 10-20 results, scale up as needed - 🏷️ Use tags and descriptions for organization - ⏰ Plan for 10-15 minute webset build times **Search Optimization:** - 🔍 Search for concepts, not just keywords - 🎯 Use multiple targeted searches vs one broad search - 📝 Be specific about what information you need - 🔄 Iterate and refine search queries **Enhancement Strategy:** - 📋 Be very specific about what data to extract - 🏗️ Use structured formats (options, email, etc.) when possible - 🎯 One enhancement per specific data type - ✅ Validate enhancement results before scaling **Workflow Efficiency:** - 🔄 Batch similar operations together - 📊 Monitor progress with status checks - 🔔 Use webhooks for long-running operations - 📁 Organize with consistent naming conventions **Resource Management:** - 🏷️ Use meaningful resource IDs and descriptions - 🧹 Clean up unused websets and enhancements - 📊 Track usage with tags and metadata - 🔍 Monitor activities with event listing **Performance Tips:** - ⚡ Use progressive disclosure - start simple, add complexity - 🎯 Target specific data needs vs broad exploration - 📦 Batch related enhancements together - ⏰ Plan workflows around processing times **Security Considerations:** - 🔒 Use HTTPS for all webhook URLs - 🔐 Implement webhook signature verification - 🚫 Avoid logging sensitive data - 🛡️ Validate all input parameters ` } }; const guide = guides[topic as keyof typeof guides]; return { content: [{ type: "text" as const, text: `# ${guide.title}\n\n${guide.content.trim()}\n\n---\n\n**Need more help?** Try other guide topics: ${Object.keys(guides).join(', ')}` }] }; }, enabled: true };
- src/index.ts:126-142 (registration)Final registration of the 'websets_guide' tool (imported as websetsGuideTool) into the MCP server via server.tool() call within the registerTools() method.const simplifiedRegistry = { web_search_exa: toolRegistry["web_search_exa"], websets_manager: toolRegistry["websets_manager"], websets_guide: websetsGuideTool, knowledge_graph: toolRegistry["knowledge_graph"], }; // Register our tools Object.values(simplifiedRegistry).forEach(tool => { if (tool) { this.server.tool( tool.name, tool.description, tool.schema, tool.handler ); }