@hailer/mcp 0.0.1

package/.claude/skills/get-insight-data-skill/SKILL.md

@@ -0,0 +1,1053 @@
+---
+name: Getting Insight Data
+description: Complete guide for executing insights and retrieving results - use when running reports or exporting data
+---
+
+# Getting Insight Data - Complete Guide
+
+Complete reference for executing Hailer insights and retrieving full results using the `get_insight_data` MCP tool.
+
+## Table of Contents
+1. [Quick Reference](#quick-reference)
+2. [Overview](#overview)
+3. [Core Concepts](#core-concepts)
+4. [Basic Usage](#basic-usage)
+5. [Update vs Cached Data](#update-vs-cached-data)
+6. [Working with Results](#working-with-results)
+7. [Large Datasets](#large-datasets)
+8. [Common Scenarios](#common-scenarios)
+9. [Performance Considerations](#performance-considerations)
+10. [Best Practices](#best-practices)
+11. [Troubleshooting](#troubleshooting)
+
+## Quick Reference
+
+**Get Cached Results (Fast):**
+
+```javascript
+get_insight_data({
+  insightId: 'insight-id'
+})
+```
+
+**Force Refresh (Recalculate):**
+
+```javascript
+get_insight_data({
+  insightId: 'insight-id',
+  update: true  // Recalculate from current data
+})
+```
+
+**Response Format:**
+```javascript
+{
+  columns: ['title', 'priority', 'dueDate'],
+  rows: [
+    ['Task 1', 'High', '2024-12-31'],
+    ['Task 2', 'Medium', '2024-12-25'],
+    // ... all matching activities
+  ]
+}
+```
+
+**Key Features:**
+- Executes saved insight SQL query
+- Returns ALL matching activities (not limited like preview)
+- Supports cached results (fast) or fresh calculation (slower)
+- Data returned in tabular format (columns + rows)
+- Can handle large result sets
+
+## Overview
+
+**What is get_insight_data?**
+
+This tool executes a saved insight's SQL query and returns the complete results. Unlike `preview_insight` (limited to ~20 activities), this returns ALL data matching your query.
+
+**Think of it as:**
+- Running a saved SQL query
+- Executing a database view
+- Generating a report
+- Exporting query results
+
+**When to Use:**
+- View full insight results
+- Export data for analysis
+- Verify insight after creation
+- Check updated data after workflow changes
+- Generate reports
+- Feed data to other tools
+
+**When NOT to Use:**
+- Testing queries (use preview_insight)
+- Need just a few records (use list_activities)
+- Real-time data not needed (results may be cached)
+- Insight doesn't exist yet (create it first)
+
+## Core Concepts
+
+### Insight Execution Flow
+
+```
+1. Insight Created
+   ↓
+2. get_insight_data() called
+   ↓
+3. Check cache
+   ↓
+4a. Cached? → Return cached results (fast)
+4b. Not cached/update=true? → Execute SQL (slower)
+   ↓
+5. Return columns + rows
+```
+
+### Data vs Preview
+
+| Feature | preview_insight | get_insight_data |
+|---------|----------------|------------------|
+| Requires saved insight | ❌ No | ✅ Yes |
+| Data limit | ~20 activities | All activities |
+| Speed | Very fast | Depends on data size |
+| Use case | Testing | Production reports |
+| Caching | Not cached | Can use cache |
+
+### Cached vs Fresh Data
+
+**Cached Results (update: false, default):**
+- Fast retrieval
+- May be stale if activities changed
+- Good for static reports
+- Recommended for frequent access
+
+**Fresh Results (update: true):**
+- Recalculates from current data
+- Slower execution
+- Always current
+- Use after workflow updates
+
+## Basic Usage
+
+### Example 1: Get Cached Results
+
+```javascript
+// Get results from saved insight (uses cache)
+get_insight_data({
+  insightId: '68446dc05b30685f67c6fcd4'
+})
+
+// Response:
+// ✅ Insight Data Retrieved
+// Insight ID: 68446dc05b30685f67c6fcd4
+// Updated: No (cached)
+//
+// Results:
+// - Rows: 1523
+// - Columns: 3
+//
+// Data Preview (first 50 rows):
+// | title | priority | dueDate |
+// |-------|----------|---------|
+// | Task 1 | High | 2024-12-31 |
+// | Task 2 | Medium | 2024-12-25 |
+// ...
+```
+
+### Example 2: Force Refresh
+
+```javascript
+// Recalculate with current activity data
+get_insight_data({
+  insightId: '68446dc05b30685f67c6fcd4',
+  update: true  // Recalculate
+})
+
+// Response:
+// ✅ Insight Data Retrieved
+// Insight ID: 68446dc05b30685f67c6fcd4
+// Updated: Yes (recalculated)
+//
+// Results:
+// - Rows: 1547  // New activities added since cache
+// - Columns: 3
+```
+
+### Example 3: Complete Workflow
+
+```javascript
+// 1. Create insight
+const result = create_insight({
+  name: 'High Priority Tasks',
+  sources: [{
+    name: 'tasks',
+    workflowId: 'tasks-workflow-id',
+    fields: [
+      { name: 'title', meta: 'name' },
+      { name: 'priority', fieldId: 'priority-field-id' }
+    ]
+  }],
+  query: 'SELECT title, priority FROM tasks WHERE priority = "High"'
+})
+
+// 2. Get insight data
+const data = get_insight_data({
+  insightId: result.insightId
+})
+
+// 3. Process results
+console.log(`Found ${data.rows.length} high priority tasks`)
+data.rows.forEach(row => {
+  const [title, priority] = row
+  console.log(`- ${title} (${priority})`)
+})
+```
+
+## Update vs Cached Data
+
+### When to Use Cached Results (update: false)
+
+**Scenarios:**
+- Reading same insight multiple times
+- Data doesn't change frequently
+- Performance is critical
+- Report is for historical reference
+- Running scheduled reports
+
+**Example:**
+```javascript
+// Dashboard that refreshes every minute
+setInterval(() => {
+  const data = get_insight_data({
+    insightId: 'dashboard-insight-id'
+    // No update - uses cache (fast)
+  })
+  updateDashboard(data)
+}, 60000)
+```
+
+### When to Force Update (update: true)
+
+**Scenarios:**
+- After creating new activities
+- After updating activity fields
+- Need real-time accuracy
+- First time executing insight
+- Data known to have changed
+- Debugging data issues
+
+**Example:**
+```javascript
+// 1. Create activities
+create_activity({
+  workflowId: 'tasks-workflow-id',
+  name: 'New Task',
+  fields: { priority: 'High' }
+})
+
+// 2. Get fresh data (includes new activity)
+get_insight_data({
+  insightId: 'tasks-insight-id',
+  update: true  // Force recalculation
+})
+```
+
+### Hybrid Approach
+
+```javascript
+// Check last update time, refresh if old
+function getInsightDataSmart(insightId) {
+  const insights = list_insights()
+  const insight = insights.find(i => i._id === insightId)
+
+  const lastUpdate = new Date(insight.lastCalculated)
+  const ageMinutes = (Date.now() - lastUpdate) / 1000 / 60
+
+  // Refresh if older than 5 minutes
+  const shouldUpdate = ageMinutes > 5
+
+  return get_insight_data({
+    insightId: insightId,
+    update: shouldUpdate
+  })
+}
+```
+
+## Working with Results
+
+### Result Structure
+
+```javascript
+const result = get_insight_data({
+  insightId: 'insight-id'
+})
+
+// Structure:
+// {
+//   columns: ['column1', 'column2', 'column3'],
+//   rows: [
+//     ['value1a', 'value2a', 'value3a'],
+//     ['value1b', 'value2b', 'value3b'],
+//     ...
+//   ]
+// }
+```
+
+### Processing Results
+
+**Example 1: Convert to Objects**
+
+```javascript
+const data = get_insight_data({
+  insightId: 'insight-id'
+})
+
+// Convert to array of objects
+const objects = data.rows.map(row => {
+  const obj = {}
+  data.columns.forEach((col, i) => {
+    obj[col] = row[i]
+  })
+  return obj
+})
+
+console.log(objects)
+// [
+//   { title: 'Task 1', priority: 'High', dueDate: '2024-12-31' },
+//   { title: 'Task 2', priority: 'Medium', dueDate: '2024-12-25' },
+//   ...
+// ]
+```
+
+**Example 2: Filter Results**
+
+```javascript
+const data = get_insight_data({
+  insightId: 'insight-id'
+})
+
+// Find rows where column 2 (priority) is 'High'
+const highPriorityRows = data.rows.filter(row => row[1] === 'High')
+
+console.log(`Found ${highPriorityRows.length} high priority items`)
+```
+
+**Example 3: Group by Column**
+
+```javascript
+const data = get_insight_data({
+  insightId: 'insight-id'
+})
+
+// Group by priority (column index 1)
+const grouped = {}
+data.rows.forEach(row => {
+  const priority = row[1]
+  if (!grouped[priority]) {
+    grouped[priority] = []
+  }
+  grouped[priority].push(row)
+})
+
+console.log('Tasks by priority:', grouped)
+// {
+//   'High': [[...], [...]],
+//   'Medium': [[...], [...], ...],
+//   'Low': [[...]]
+// }
+```
+
+**Example 4: Export to CSV**
+
+```javascript
+const data = get_insight_data({
+  insightId: 'insight-id'
+})
+
+// Generate CSV
+let csv = data.columns.join(',') + '\n'
+data.rows.forEach(row => {
+  csv += row.map(cell => `"${cell}"`).join(',') + '\n'
+})
+
+console.log(csv)
+// title,priority,dueDate
+// "Task 1","High","2024-12-31"
+// "Task 2","Medium","2024-12-25"
+// ...
+```
+
+**Example 5: Calculate Statistics**
+
+```javascript
+const data = get_insight_data({
+  insightId: 'budget-insight-id'
+})
+
+// Assuming column 0 is 'projectName', column 1 is 'budget'
+const budgets = data.rows.map(row => parseFloat(row[1]))
+
+const total = budgets.reduce((sum, b) => sum + b, 0)
+const avg = total / budgets.length
+const max = Math.max(...budgets)
+const min = Math.min(...budgets)
+
+console.log(`Total Budget: $${total}`)
+console.log(`Average Budget: $${avg}`)
+console.log(`Max Budget: $${max}`)
+console.log(`Min Budget: $${min}`)
+```
+
+## Large Datasets
+
+### Handling Many Rows
+
+**Insight returns thousands of rows:**
+
+```javascript
+const data = get_insight_data({
+  insightId: 'large-insight-id'
+})
+
+console.log(`Retrieved ${data.rows.length} rows`)
+// Retrieved 15,247 rows
+
+// Process in batches
+const batchSize = 100
+for (let i = 0; i < data.rows.length; i += batchSize) {
+  const batch = data.rows.slice(i, i + batchSize)
+  processBatch(batch)
+}
+```
+
+### Pagination Strategy
+
+**Use SQL LIMIT/OFFSET in insight query:**
+
+```javascript
+// Create paginated insight
+create_insight({
+  name: 'Tasks Page 1',
+  sources: [...],
+  query: 'SELECT * FROM tasks ORDER BY created DESC LIMIT 100 OFFSET 0'
+})
+
+create_insight({
+  name: 'Tasks Page 2',
+  sources: [...],
+  query: 'SELECT * FROM tasks ORDER BY created DESC LIMIT 100 OFFSET 100'
+})
+
+// Get pages
+const page1 = get_insight_data({ insightId: 'page1-id' })
+const page2 = get_insight_data({ insightId: 'page2-id' })
+```
+
+### Memory Considerations
+
+```javascript
+// For very large datasets, process incrementally
+const data = get_insight_data({
+  insightId: 'huge-insight-id'
+})
+
+// Don't store all processed data in memory
+let processed = 0
+data.rows.forEach(row => {
+  // Process row immediately
+  processRow(row)
+  processed++
+
+  // Don't accumulate results
+})
+
+console.log(`Processed ${processed} rows`)
+```
+
+## Common Scenarios
+
+### Scenario 1: Daily Report Generation
+
+```javascript
+// Generate daily high priority tasks report
+
+// 1. Get insight data (fresh)
+const data = get_insight_data({
+  insightId: 'daily-tasks-insight-id',
+  update: true  // Fresh data
+})
+
+// 2. Format as report
+console.log('=== Daily High Priority Tasks Report ===')
+console.log(`Generated: ${new Date().toISOString()}`)
+console.log(`Total Tasks: ${data.rows.length}\n`)
+
+// 3. Output table
+console.log(data.columns.join(' | '))
+console.log(data.columns.map(() => '---').join(' | '))
+data.rows.forEach(row => {
+  console.log(row.join(' | '))
+})
+```
+
+### Scenario 2: Data Export
+
+```javascript
+// Export insight data to JSON file
+
+const data = get_insight_data({
+  insightId: 'export-insight-id',
+  update: true
+})
+
+// Convert to objects
+const records = data.rows.map(row => {
+  const record = {}
+  data.columns.forEach((col, i) => {
+    record[col] = row[i]
+  })
+  return record
+})
+
+// Save to file (pseudo-code)
+const json = JSON.stringify(records, null, 2)
+saveToFile('export.json', json)
+
+console.log(`Exported ${records.length} records`)
+```
+
+### Scenario 3: Verify Insight After Creation
+
+```javascript
+// 1. Create insight
+const result = create_insight({
+  name: 'New Insight',
+  sources: [...],
+  query: 'SELECT ...'
+})
+
+// 2. Immediately get data to verify
+const data = get_insight_data({
+  insightId: result.insightId,
+  update: true  // Force calculation
+})
+
+// 3. Verify results
+if (data.rows.length === 0) {
+  console.warn('⚠️ Insight returns no data!')
+} else {
+  console.log(`✅ Insight working: ${data.rows.length} rows`)
+}
+```
+
+### Scenario 4: Compare Before/After
+
+```javascript
+// Check data before and after workflow changes
+
+// Before changes
+const before = get_insight_data({
+  insightId: 'insight-id',
+  update: true
+})
+console.log('Before:', before.rows.length, 'rows')
+
+// Make changes
+create_activity({ ... })
+update_activity({ ... })
+
+// After changes (force refresh)
+const after = get_insight_data({
+  insightId: 'insight-id',
+  update: true  // Fresh data
+})
+console.log('After:', after.rows.length, 'rows')
+console.log('Difference:', after.rows.length - before.rows.length)
+```
+
+### Scenario 5: Dashboard Data
+
+```javascript
+// Get multiple insight datasets for dashboard
+
+async function getDashboardData() {
+  // Get all insights (can run in parallel)
+  const [tasksData, projectsData, statsData] = await Promise.all([
+    get_insight_data({ insightId: 'tasks-insight-id' }),
+    get_insight_data({ insightId: 'projects-insight-id' }),
+    get_insight_data({ insightId: 'stats-insight-id' })
+  ])
+
+  return {
+    tasks: {
+      total: tasksData.rows.length,
+      data: tasksData.rows
+    },
+    projects: {
+      total: projectsData.rows.length,
+      data: projectsData.rows
+    },
+    stats: {
+      data: statsData.rows
+    }
+  }
+}
+```
+
+### Scenario 6: Find Specific Records
+
+```javascript
+// Use insight to find specific records
+
+const data = get_insight_data({
+  insightId: 'all-tasks-insight-id'
+})
+
+// Find specific task by title (column 0)
+const task = data.rows.find(row => row[0] === 'Important Task')
+
+if (task) {
+  console.log('Found task:', task)
+} else {
+  console.log('Task not found')
+}
+```
+
+## Performance Considerations
+
+### Execution Time
+
+**Fast insights (< 1 second):**
+- Simple SELECT with WHERE
+- Single workflow source
+- Small result set (< 1000 rows)
+- Using cached results
+
+**Slow insights (> 5 seconds):**
+- Complex JOINs (3+ workflows)
+- Large result sets (> 10,000 rows)
+- Complex aggregations
+- Force update on large dataset
+
+### Optimization Tips
+
+**1. Use cached results when possible:**
+```javascript
+// Fast - uses cache
+get_insight_data({ insightId: 'id' })
+
+// Slow - recalculates
+get_insight_data({ insightId: 'id', update: true })
+```
+
+**2. Limit result sets in SQL:**
+```javascript
+// Better: Limited results
+create_insight({
+  query: 'SELECT * FROM tasks LIMIT 1000'
+})
+
+// Worse: All results
+create_insight({
+  query: 'SELECT * FROM tasks'  // Could be 50,000 rows
+})
+```
+
+**3. Use aggregations in SQL:**
+```javascript
+// Better: Aggregate in SQL
+create_insight({
+  query: `
+    SELECT priority, COUNT(*) as count
+    FROM tasks
+    GROUP BY priority
+  `
+})
+const data = get_insight_data({ insightId: 'id' })
+// Returns: 3 rows (one per priority)
+
+// Worse: Aggregate in code
+create_insight({
+  query: 'SELECT priority FROM tasks'
+})
+const data = get_insight_data({ insightId: 'id' })
+// Returns: 10,000 rows, then count in code
+```
+
+**4. Schedule expensive updates:**
+```javascript
+// Update heavy insights during off-hours
+if (new Date().getHours() < 6) {  // 12am - 6am
+  get_insight_data({
+    insightId: 'expensive-insight-id',
+    update: true
+  })
+}
+```
+
+## Best Practices
+
+### 1. Verify Insight Exists
+
+```javascript
+// Check insight exists before getting data
+const insights = list_insights()
+const insight = insights.find(i => i._id === 'target-id')
+
+if (!insight) {
+  console.error('Insight not found')
+  return
+}
+
+const data = get_insight_data({
+  insightId: insight._id
+})
+```
+
+### 2. Handle Empty Results
+
+```javascript
+const data = get_insight_data({
+  insightId: 'insight-id'
+})
+
+if (!data.rows || data.rows.length === 0) {
+  console.warn('No data returned')
+  return
+}
+
+// Process data
+console.log(`Processing ${data.rows.length} rows`)
+```
+
+### 3. Use update: true After Data Changes
+
+```javascript
+// Workflow: Create activities → Get fresh data
+
+// 1. Create activities
+create_activity({ ... })
+create_activity({ ... })
+
+// 2. Get fresh insight data
+const data = get_insight_data({
+  insightId: 'insight-id',
+  update: true  // Include new activities
+})
+```
+
+### 4. Cache Results Locally When Appropriate
+
+```javascript
+// Cache insight data for repeated access
+let cachedData = null
+let cacheTime = null
+
+function getInsightDataCached(insightId) {
+  const now = Date.now()
+  const cacheMaxAge = 5 * 60 * 1000  // 5 minutes
+
+  if (cachedData && cacheTime && (now - cacheTime < cacheMaxAge)) {
+    console.log('Using local cache')
+    return cachedData
+  }
+
+  console.log('Fetching fresh data')
+  cachedData = get_insight_data({ insightId })
+  cacheTime = now
+
+  return cachedData
+}
+```
+
+### 5. Validate Column Structure
+
+```javascript
+const data = get_insight_data({
+  insightId: 'insight-id'
+})
+
+// Verify expected columns
+const expectedColumns = ['title', 'priority', 'dueDate']
+const hasAllColumns = expectedColumns.every(col =>
+  data.columns.includes(col)
+)
+
+if (!hasAllColumns) {
+  console.error('Unexpected column structure:', data.columns)
+  return
+}
+
+// Safe to process
+processData(data)
+```
+
+### 6. Handle NULL Values
+
+```javascript
+const data = get_insight_data({
+  insightId: 'insight-id'
+})
+
+// Convert rows, handle NULL
+const records = data.rows.map(row => {
+  return data.columns.reduce((obj, col, i) => {
+    obj[col] = row[i] ?? 'N/A'  // Replace NULL with 'N/A'
+    return obj
+  }, {})
+})
+```
+
+### 7. Log Data Retrieval
+
+```javascript
+console.log(`Fetching insight data: ${insightId}`)
+console.log(`Update mode: ${update ? 'Fresh' : 'Cached'}`)
+
+const startTime = Date.now()
+const data = get_insight_data({
+  insightId: insightId,
+  update: update
+})
+const elapsed = Date.now() - startTime
+
+console.log(`Retrieved ${data.rows.length} rows in ${elapsed}ms`)
+console.log(`Columns: ${data.columns.join(', ')}`)
+```
+
+## Troubleshooting
+
+### Error: "Insight Not Found"
+
+**Cause:** Invalid insight ID or insight deleted.
+
+**Solution:**
+
+```javascript
+// 1. List insights to find correct ID
+const insights = list_insights()
+console.log('Available insights:')
+insights.forEach(i => {
+  console.log(`- ${i.name}: ${i._id}`)
+})
+
+// 2. Use correct ID
+get_insight_data({
+  insightId: 'correct-insight-id'
+})
+```
+
+### Error: "Permission Denied"
+
+**Cause:** Don't have access to insight or underlying workflows.
+
+**Solution:**
+- Check insight permissions
+- Verify access to workflows in insight sources
+- Contact insight owner or workspace admin
+
+### Returns Empty Data
+
+**Causes:**
+1. No activities match query
+2. Insight SQL has WHERE clause too restrictive
+3. JOINs eliminate all rows
+
+**Solutions:**
+
+```javascript
+// 1. Check if cached results are stale
+get_insight_data({
+  insightId: 'insight-id',
+  update: true  // Force fresh calculation
+})
+
+// 2. Verify activities exist
+list_activities({
+  workflowId: 'workflow-id',
+  limit: 1
+})
+
+// 3. Test with preview_insight
+preview_insight({
+  sources: [...],
+  query: '...'
+})
+```
+
+### Data Seems Outdated
+
+**Cause:** Using cached results, activities changed.
+
+**Solution:**
+
+```javascript
+// Force recalculation
+get_insight_data({
+  insightId: 'insight-id',
+  update: true  // Get current data
+})
+```
+
+### Very Slow Execution
+
+**Causes:**
+1. Large dataset
+2. Complex JOINs
+3. Server load
+
+**Solutions:**
+
+```javascript
+// 1. Use cached results
+get_insight_data({
+  insightId: 'insight-id'
+  // Don't use update: true
+})
+
+// 2. Limit results in SQL
+// Modify insight query to include LIMIT
+
+// 3. Use aggregation instead of detail
+// Change insight to GROUP BY instead of returning all rows
+```
+
+### Unexpected Column Structure
+
+**Cause:** Insight query changed or different than expected.
+
+**Solution:**
+
+```javascript
+const data = get_insight_data({
+  insightId: 'insight-id'
+})
+
+// Check actual columns
+console.log('Actual columns:', data.columns)
+
+// Adapt processing
+data.rows.forEach(row => {
+  const record = {}
+  data.columns.forEach((col, i) => {
+    record[col] = row[i]
+  })
+  console.log(record)
+})
+```
+
+## Integration with Other Tools
+
+### With create_insight
+
+Standard workflow:
+
+```javascript
+// 1. Create insight
+const result = create_insight({
+  name: 'My Report',
+  sources: [...],
+  query: '...'
+})
+
+// 2. Get data
+const data = get_insight_data({
+  insightId: result.insightId,
+  update: true  // Force initial calculation
+})
+```
+
+### With preview_insight
+
+Test then execute:
+
+```javascript
+// 1. Preview query
+preview_insight({
+  sources: [...],
+  query: '...'
+})
+// ✅ Works!
+
+// 2. Create insight
+const result = create_insight({
+  name: 'Report',
+  sources: [...],
+  query: '...'
+})
+
+// 3. Get full data
+const data = get_insight_data({
+  insightId: result.insightId
+})
+```
+
+### With list_insights
+
+Find and execute:
+
+```javascript
+// 1. List insights
+const insights = list_insights()
+
+// 2. Find specific insight
+const insight = insights.find(i => i.name === 'Daily Report')
+
+// 3. Get data
+const data = get_insight_data({
+  insightId: insight._id,
+  update: true
+})
+```
+
+### With list_activities
+
+Compare results:
+
+```javascript
+// Get insight data
+const insightData = get_insight_data({
+  insightId: 'tasks-high-priority-id'
+})
+
+// Compare with list_activities
+const activities = list_activities({
+  workflowId: 'tasks-workflow-id',
+  filters: [{ field: 'priority-field-id', operator: 'eq', value: 'High' }]
+})
+
+console.log('Insight rows:', insightData.rows.length)
+console.log('Activities:', activities.items.length)
+// Should match
+```
+
+## Summary
+
+**Key Takeaways:**
+1. 📊 **Full results** - Returns ALL matching activities (not limited)
+2. ⚡ **Cached by default** - Fast with cached results
+3. 🔄 **Force update** - Use update: true for fresh data
+4. 📋 **Tabular format** - Returns columns + rows arrays
+5. 🎯 **Production use** - For reports and data exports
+6. 📈 **Large datasets** - Can return thousands of rows
+7. ✅ **After preview** - Create insight first, then get data
+
+**Quick Decision Tree:**
+
+```
+Need insight data?
+│
+├─ Testing query? → Use preview_insight
+├─ Insight not created? → Create first with create_insight
+├─ Need current data? → Use update: true
+├─ Performance critical? → Use cached (update: false)
+├─ Large dataset? → Consider SQL LIMIT or aggregation
+└─ For export? → Convert rows to desired format
+```
+
+## Additional Resources
+
+- See `create-insight-skill` for creating insights
+- See `preview-insight-skill` for testing queries
+- See `remove-insight-skill` for deleting insights
+- See `insight-api` skill for comprehensive Insight API documentation
+- Use `list_insights` to find insight IDs
+- Use `list_activities` to compare results