Insights — Agent Specifications

Each insight agent is a dedicated BullMQ worker that fetches channel-specific metrics and passes them to Claude for analysis. All agents follow the worker pattern described in architecture.md.

Agent Index

1. GSC Insights

agent__gsc-insights · Google Search Console · Sonnet 4.6

Overview

Data Fetched

Provider methods called: getStats(), getKeywordStats(), searchQueries()

Metrics passed to LLM:

• Total impressions, clicks, CTR, average position — current period vs prior period
• Top 20 queries by impressions with position, CTR, and click data
• Top 10 pages by impressions
• Queries currently in positions 4–10 (low-hanging-fruit set)
• Queries trending up vs down period-over-period

System Prompt Focus

Analyse search visibility trends. Identify underperforming high-impression keywords (high impressions, low CTR). Spot quick-win opportunities (positions 4–10 that could reach page 1 with optimisation). Flag declining terms that need attention. Be specific — cite query names, position numbers, and CTR percentages from the data.

Output Sections

• Strengths — Keywords performing well, high-CTR queries, pages with strong and stable rankings
• Weaknesses — High-impression / low-CTR queries, declining positions, pages losing traffic
• Opportunities — Keywords in positions 4–10 closest to page 1, content gaps implied by query clusters, pages that could rank higher with on-page optimisation
• Recommendations — Specific, prioritised actions citing the exact query or page (e.g. “Update the meta title on /services/emergency-plumbing to improve CTR from 0.8% toward the 3% benchmark — this query receives 4,200 impressions/month”)

2. GA Insights

agent__ga-insights · Google Analytics · Sonnet 4.6

Overview

Data Fetched

Provider methods called: getOverviewMetrics(), getDailyMetrics(), getTrafficSources(), getOrganicTrafficMetrics(), top pages

Metrics passed to LLM:

• Sessions, users, new users, bounce rate — current period vs prior period
• Traffic by source/medium (organic, direct, social, referral, paid)
• Top 10 pages by sessions with bounce rate per page
• Daily session trend over the period
• Device breakdown (mobile / desktop / tablet)
• Organic traffic trends (sessions, and conversions if available)

System Prompt Focus

Identify traffic trends and diagnose causes. Highlight high bounce rate pages and suggest reasons. Evaluate the channel mix — is the business over-reliant on one source? Surface seasonal patterns and drop-off points that indicate UX or content problems.

Output Sections

• Strengths — Growing traffic channels, high-performing landing pages, strong engagement metrics, positive period-over-period trends
• Weaknesses — Pages with high bounce rates, declining traffic sources, mobile vs desktop conversion gaps, single-channel dependency risk
• Opportunities — Under-utilised channels with growth potential, pages with high traffic but low conversion, seasonal trend patterns to capitalise on
• Recommendations — Prioritised CRO and content actions with specific page and metric targets

3. Google Ads Insights

agent__google-ads-insights · Google Ads · Sonnet 4.6

Overview

Data Fetched

Provider methods called: getCampaignsAsLookup(), getKeywordMetricsByKeyword()

Metrics passed to LLM:

• Campaign-level: impressions, clicks, CTR, average CPC, cost, conversions, conversion rate, ROAS — current period vs prior
• Top 20 keywords by spend with quality score, bid, CPC, and conversions
• Ad group structure overview
• Keywords with spend and zero conversions (wasted spend indicators)

System Prompt Focus

Identify budget efficiency gaps and quality score improvement opportunities. Flag wasted spend (spend with no conversions). Highlight campaigns with strong ROAS suited for scaling. Recommend specific bid, budget, and keyword actions.

Output Sections

• Strengths — High-ROAS campaigns, converting keywords, efficient ad groups with strong quality scores
• Weaknesses — Low quality score keywords, wasted spend items, underperforming campaigns draining budget
• Opportunities — Bid adjustment opportunities, quality score improvement targets, keyword gap coverage
• Recommendations — Specific bid, budget reallocation, and keyword optimisation actions with estimated impact

4. Meta Ads Insights

agent__meta-ads-insights · Meta Ads · Sonnet 4.6

Overview

Data Fetched

Provider methods called: getMetaAdsCampaignPerformanceSummary()

Metrics passed to LLM:

• Campaign-level: impressions, reach, clicks, CTR, CPC, spend, results, cost per result, ROAS — current period vs prior
• Frequency per campaign (indicator of creative fatigue)
• Audience overlap signals
• Creative-level CTR where available

System Prompt Focus

Evaluate campaign efficiency and creative fatigue. High frequency + declining CTR signals creative refresh is needed. Identify campaigns where budget is best spent and those that are underperforming relative to spend.

Output Sections

• Strengths — Strong-ROAS campaigns, high-engagement creatives, efficient audience targeting, good cost-per-result metrics
• Weaknesses — Fatigued creatives (high frequency + declining CTR), low CTR campaigns, inefficient cost-per-result
• Opportunities — Lookalike audience expansion, creative refresh opportunities, budget reallocation from low to high performers
• Recommendations — Creative, audience targeting, and budget allocation actions with expected outcome

5. Facebook Insights

agent__facebook-insights · Facebook Page · Sonnet 4.6

Overview

Data Fetched

Provider methods called: getDailyInsights(), getPublishedPosts()

Metrics passed to LLM:

• Page-level: impressions, reach, engaged users — daily trend over the period vs prior period
• Top 10 posts by reach and engagement with post type (link, photo, video, text)
• Post frequency and day-of-week / time patterns
• Page follower count and growth trend

System Prompt Focus

Analyse what content performs best for this page. Identify which post formats and topics consistently drive engagement vs those that underperform. Surface posting cadence and timing improvements.

Output Sections

• Strengths — High-engagement post types or topics, strong reach days, content themes that consistently resonate
• Weaknesses — Low-engagement content patterns, inconsistent posting frequency, declining organic reach
• Opportunities — Underused post formats (video, reels), optimal posting time windows, untapped topic areas based on what performs
• Recommendations — Specific content strategy, format mix, and posting schedule actions

6. Instagram Insights

agent__instagram-insights · Instagram · Sonnet 4.6

Overview

Data Fetched

Provider methods called: Instagram Graph API via Meta provider (insights per media, account-level metrics)

Metrics passed to LLM:

• Feed post reach, impressions, and engagement rate per post
• Average engagement rate trend over the period
• Post frequency and posting day/time distribution
• Content format breakdown (image, carousel, reel)
• Follower count and gain trend

System Prompt Focus

Analyse engagement rate trends across content formats. Identify which formats (reel vs carousel vs single image) and topics generate the strongest engagement. Surface gaps in posting cadence and recommend format experiments.

Output Sections

• Strengths — High-engagement post types, strong reach periods, content themes with consistent engagement
• Weaknesses — Underperforming formats, irregular posting gaps, declining engagement rate trend
• Opportunities — Reel adoption if underused, carousel vs single-image experiment, hashtag strategy gaps, posting time optimisation
• Recommendations — Content format mix, cadence, and caption/hashtag guidance with supporting data

7. LinkedIn Insights

agent__linkedin-insights · LinkedIn · Sonnet 4.6

Overview

Data Fetched

Provider methods called: getPageStatistics(), getFollowersGainStatistics(), getShareStatistics()

Metrics passed to LLM:

• Page views, unique visitors, follower count, follower gain/loss — period vs prior
• Top post impressions, clicks, engagement rate
• Audience demographics: job function, industry, seniority (where available)
• Content type breakdown (text, image, document, video)

System Prompt Focus

Evaluate thought leadership positioning and content resonance for a B2B audience. Diagnose follower growth health. Identify which content formats and topics perform best for the specific audience demographics of this page.

Output Sections

• Strengths — High-performing post topics, strong follower growth, content resonating with the target seniority/function
• Weaknesses — Low engagement relative to follower count, stagnant follower growth, content misaligned with audience demographics
• Opportunities — Employee advocacy potential, document posts (high-performing on LinkedIn), video content, hooking into industry conversations
• Recommendations — Content format, topic focus, and engagement tactic actions with audience data to support them

8. GBP Insights

agent__gbp-insights · Google Business Profile · Sonnet 4.6

Overview

Data Fetched

Provider methods called: GBP Performance API (views, searches, actions)

Metrics passed to LLM:

• Business profile views split: Search vs Maps
• Search queries used to find the profile (branded vs non-branded)
• Customer actions: direction requests, website clicks, call clicks — period vs prior
• Photo views and count
• Review summary: total count, average rating, review count trend

System Prompt Focus

Identify local visibility gaps and optimisation opportunities. Analyse how customers are discovering and interacting with the profile. Surface actions that will drive more calls, direction requests, and website visits.

Output Sections

• Strengths — Strong discovery queries, high call-click rate, growing direction requests, high photo engagement
• Weaknesses — Low photo view count, poor search-vs-maps ratio, stagnant or declining review count, missing categories
• Opportunities — GBP post frequency gaps, Q&A section optimisation, photo refresh opportunities, review generation campaigns
• Recommendations — Specific profile optimisation, posting cadence, and review acquisition actions with priority ratings