Skip to main content
⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. Google Ads only - NOT available for TikTok. 🎯 What This Tool Does (Performance Agent - Phase 1 Feature 3):
  • Identifies OPPORTUNITY keywords: Converting search terms NOT in your keyword list
  • Identifies NEGATIVE keywords: Expensive terms with zero conversions
  • Analyzes MATCH TYPE performance: Exact vs Phrase vs Broad efficiency
  • Provides specific recommendations with suggested bids and match types
  • Ranks opportunities by profit potential (not just ROAS)
Returns comprehensive keyword intelligence:
  • Top 20 opportunity keywords with suggested bids and match types
  • Top 20 negative keyword candidates with wasted cost breakdown
  • Match type performance comparison (Exact/Phrase/Broad)
  • Broad→Exact conversion recommendations
  • Total opportunity value and wasted spend amounts
  • Actionable recommendations for immediate implementation
🔍 What Search Term Mining Reveals: Opportunity Keywords (Money Left on Table):
  • Search terms that ARE converting but you’re NOT bidding on them directly
  • These are queries triggering your ads via Broad/Phrase match, but should be added as Exact keywords
  • Example: User searches “enterprise security software pricing” → converts → but you only have “security software” as keyword
  • Action: Add high-converting search terms as new keywords with suggested bids
Negative Keywords (Money Wasted):
  • Search terms costing >$10 with ZERO conversions
  • Low-intent queries like “free”, “download”, “crack”, “how to”
  • Example: “free security software download” → 120 clicks, $540 spent, 0 conversions
  • Action: Add as negative keywords to stop wasting budget
Match Type Optimization:
  • Compares performance of Exact vs Phrase vs Broad match
  • Identifies Broad keywords that should be converted to Exact for better control
  • Example: Broad “security software” has 45% wasted spend, but top search terms have 20x ROAS
  • Action: Convert high-performing Broad keywords to Exact match
Parameters:
  • lookback_days: 7, 30, 60, 90, or 120 days (default: 30)
  • start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date.
  • end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user’s date request is vague or ambiguous (e.g., “March to June” without a year, “last quarter”, “recently”, “a few months ago”), ask the user to specify exact dates before calling this tool. Do not assume or guess dates.
  • analysis_type: ‘opportunities’, ‘negatives’, ‘match_types’, ‘all’, or ‘raw_report’ (default: ‘all’)
    • Use ‘raw_report’ when the user wants to SEE their actual search terms — the words customers type into Google
  • force_refresh: true to trigger immediate API collection (default: false, uses cached data)
  • customer_id: Optional (uses connected account if omitted)
  • campaign_id: Optional — filter search terms to a specific campaign (get from list_campaigns)
  • page: Page number for raw_report pagination (default: 1)
  • page_size: Results per page for raw_report (1-100, default: 50)
  • sort_by: Sort for raw_report: ‘cost’ (default), ‘clicks’, ‘impressions’, ‘conversions’
  • min_clicks: Minimum clicks filter for raw_report (default: 0)
Execution time: 1-3 seconds (cached database query) Data source: search_term_daily_metrics table (updated nightly, 120-day retention) ⚡ RAW REPORT PAGINATION CONTRACT:
  • When using analysis_type=‘raw_report’, results are paginated
  • Check pagination.has_more — if true, call again with next page
  • Continue until has_more is false, then present consolidated results
  • Use campaign_id to focus on a specific campaign’s search terms
Use this tool when:
  • User asks “what keywords should I add?”
  • User wants to find wasted spend at keyword level
  • User asks “what should I add as negative keywords?”
  • User wants to improve match type efficiency
  • User asks “which Broad keywords should be Exact?”
  • User wants to discover hidden keyword opportunities
  • User asks “show me my search terms” or “what are people searching for?” → use analysis_type=‘raw_report’
  • User asks “show me search terms for campaign X” → use analysis_type=‘raw_report’ with campaign_id
⚠️ Platform Limitation: This tool ONLY works for Google Ads. TikTok Ads does not provide search term data due to privacy restrictions. 📊 AFTER calling this tool, help the user understand: Opportunity Keywords:
  • What it means: These are winning search terms you’re missing
  • Profit potential: Shows expected additional profit if added
  • Suggested action: Add as new keywords with recommended bid and match type
  • Priority: Start with highest opportunity_value (profit potential)
Example: Search term: “enterprise security software pricing”
  • 8 conversions, $240 cost, $4,800 value
  • Opportunity Value: $4,560 profit potential
  • Suggested Bid: $6.00 (based on current CPC and ROAS)
  • Suggested Match Type: EXACT (high intent, proven converter)
  • Action: Add this as an Exact match keyword with $6 bid
Negative Keywords:
  • What it means: These queries waste money and never convert
  • Cost: Total wasted spend on non-converting terms
  • Common patterns: “free”, “download”, “crack”, “review”, “how to”
  • Action: Add as negative keywords (campaign or account level)
Example: Search term: “free security software”
  • 120 clicks, $540 wasted, 0 conversions
  • Reason: Low purchase intent (free)
  • Action: Add “free” as negative keyword at campaign level
Match Type Performance:
  • Exact: Tightest control, lowest waste, highest ROAS (recommended)
  • Phrase: Moderate flexibility, some waste, decent ROAS
  • Broad: Most volume, highest waste, lowest ROAS (use sparingly)
Example Analysis:
  • Exact: 450 keywords, ROAS 4.8x, 2% wasted spend ✅
  • Phrase: 280 keywords, ROAS 3.2x, 8% wasted spend ⚠️
  • Broad: 120 keywords, ROAS 1.8x, 45% wasted spend 🔴
Quick Actions:
  1. Add top 5 opportunity keywords as Exact match
  2. Block top 10 negative keywords at campaign level
  3. Convert high-performing Broad keywords to Exact
  4. Review Phrase keywords with >10% wasted spend
Visualization Tip: For opportunity keywords, suggest creating a scatter plot (x=ROAS, y=Spend, size=conversions) to visualize profit potential. Implementation Steps:
  1. Review top opportunities and negatives
  2. Start with 5-10 new keywords (don’t overwhelm account)
  3. Add negatives in batches (test impact over 7 days)
  4. Convert Broad→Exact gradually (monitor volume drop)
  5. Re-run analysis monthly to discover new opportunities
Best Practices:
  • Focus on opportunity_value (profit) not just ROAS
  • Start with Exact match for all new keywords (tightest control)
  • Add negatives at campaign level first (easier to undo than account level)
  • Monitor match type distribution: Aim for 60%+ Exact, 30% Phrase, 10% Broad
  • Review search terms every 2 weeks during active optimization
💬 Community: For keyword optimization discussions, visit our Discord: https://discord.gg/dH3Qt4YS

​
OpenAPI

/api-reference/openapi.json post /api/v1/tools/analyze_search_terms/execute