Research Tools

HeyCMO's research tools enable agents to gather intelligence from the web, social media, and internal knowledge bases. They're the foundation for data-driven content strategy.

Exa Web Search

AI-powered web search using the Exa API. Returns semantically relevant results with titles, URLs, snippets, and publication dates.

Capabilities

• Semantic search (understands meaning, not just keywords)
• Date-filtered results for recency
• Highlight extraction for key passages
• Multi-query parallel search (3–5 queries per research angle)

Schema

// Input
{
  query: string;        // Search query
  numResults?: number;  // Number of results (default: 10)
  startDate?: string;   // Filter results after this date
  type?: 'keyword' | 'neural'; // Search mode
}

// Output
{
  results: Array<{
    title: string;
    url: string;
    snippet: string;
    publishedDate?: string;
    highlights?: string[];
  }>;
}

Used By

Researcher, Growth Engineer, Sales Agent

Web Extract

Extracts full page content from URLs. Uses a dual-engine approach: tries Exa Contents API first, falls back to Firecrawl for scraping.

Capabilities

• Full page text extraction (clean markdown output)
• Handles JavaScript-rendered pages
• SSRF protection — blocks requests to private/internal IP ranges (localhost, 10.x, 172.x, 192.168.x, AWS metadata endpoint)

Schema

// Input
{
  url: string;  // URL to extract content from
}

// Output
{
  url: string;
  title?: string;
  content: string;      // Extracted text content
  extractedAt: string;  // ISO timestamp
}

Used By

Researcher, CRO Specialist

X/Twitter Search

Searches X (Twitter) for real-time social sentiment, trending conversations, and audience insights.

Capabilities

• Search tweets by keyword, hashtag, or mention
• Returns engagement metrics (likes, retweets, replies)
• Author information for influencer identification
• Real-time sentiment analysis

Schema

// Input
{
  query: string;        // Search query
  maxResults?: number;  // Number of results (default: 10)
}

// Output
{
  results: Array<{
    text: string;
    authorUsername: string;
    createdAt: string;
    metrics: {
      likes: number;
      retweets: number;
      replies: number;
    };
    url: string;
  }>;
}

Used By

Researcher

RAG Query Tools

Two tools for searching HeyCMO's semantic memory (vector database):

Content Query

Searches past content stored in semantic memory. Used to avoid topic duplication, reference past performance, and maintain voice consistency.

Performance Query

Queries historical performance metrics stored in semantic memory. Used for data-driven decisions — what topics, formats, and channels have worked best.

Both tools use @mastra/rag with @mastra/fastembed for local vector embeddings against PostgreSQL with pgvector.