Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(marketing-analytics): add steps to improve the page that ranks (#128323)

Javier Bahamondes05ef0944f9f3
diff --git a/frontend/src/queries/schema.json b/frontend/src/queries/schema.json
index dad46faf8555..a2750ae65b06 100644
--- a/frontend/src/queries/schema.json
+++ b/frontend/src/queries/schema.json
@@ -36545,6 +36545,10 @@
"description": "Google Ads search term table for Performance Max campaigns.",
"type": "string"
},
+ "queryPageTable": {
+ "description": "Google Search Console table with one row per query and page, used to find the page that ranks for a search.",
+ "type": "string"
+ },
"queryTable": {
"description": "Google Search Console table with one row per query, or per query and page.",
"type": "string"
diff --git a/frontend/src/queries/schema/schema-general.ts b/frontend/src/queries/schema/schema-general.ts
index 843e9598ce57..90b5a0c740e8 100644
--- a/frontend/src/queries/schema/schema-general.ts
+++ b/frontend/src/queries/schema/schema-general.ts
@@ -8577,6 +8577,8 @@ export interface MarketingAnalyticsRecommendationsSource {
performanceMaxSearchTermTable?: string
/** Google Search Console table with one row per query, or per query and page. */
queryTable?: string
+ /** Google Search Console table with one row per query and page, used to find the page that ranks for a search. */
+ queryPageTable?: string
/** Google Search Console sites table, used to infer the brand name. */
sitesTable?: string
}
diff --git a/posthog/schema.py b/posthog/schema.py
index 2c2124e01698..87acca0b0ae1 100644
--- a/posthog/schema.py
+++ b/posthog/schema.py
@@ -6985,6 +6985,13 @@ class MarketingAnalyticsRecommendationsSource(BaseModel):
default=None,
description="Google Ads search term table for Performance Max campaigns.",
)
+ queryPageTable: str | None = Field(
+ default=None,
+ description=(
+ "Google Search Console table with one row per query and page, used to find"
+ " the page that ranks for a search."
+ ),
+ )
queryTable: str | None = Field(
default=None,
description=("Google Search Console table with one row per query, or per query and page."),
diff --git a/products/marketing_analytics/backend/hogql_queries/marketing_recommendations.py b/products/marketing_analytics/backend/hogql_queries/marketing_recommendations.py
index b67b0507c849..524d0514adfa 100644
--- a/products/marketing_analytics/backend/hogql_queries/marketing_recommendations.py
+++ b/products/marketing_analytics/backend/hogql_queries/marketing_recommendations.py
@@ -2,6 +2,7 @@ import re
from collections import defaultdict
from collections.abc import Iterable
from typing import Literal
+from urllib.parse import quote
import tldextract
@@ -70,6 +71,8 @@ ADS_CAMPAIGNS_URL = "https://ads.google.com/aw/campaigns"
ADS_KEYWORDS_URL = "https://ads.google.com/aw/keywords"
ADS_NEGATIVE_KEYWORDS_URL = "https://ads.google.com/aw/keywords/negative"
ADS_SEARCH_TERMS_URL = "https://ads.google.com/aw/keywords/searchterms"
+SEARCH_CONSOLE_PERFORMANCE_URL = "https://search.google.com/search-console/performance/search-analytics"
+SEARCH_CONSOLE_URL = "https://search.google.com/search-console"
REVIEW_TERMS_SHOWN = 3
# A non-brand campaign is up for review when its cost per conversion reaches this multiple of the non-brand average.
REVIEW_CPA_MULTIPLE = 3
@@ -112,6 +115,13 @@ class OrganicQueryStats:
position: float
+@frozen
+class RankingPage:
+ query: str
+ page: str
+ impressions: float
+
+
@frozen
class TermKeywordStats:
term: str
@@ -129,6 +139,7 @@ class RecommendationInputs:
currency: str | None
days: int
term_keywords: tuple[TermKeywordStats, ...] = ()
+ ranking_pages: tuple[RankingPage, ...] = ()
@frozen
@@ -215,6 +226,12 @@ class _Recommender:
current = self.top_keyword.get(keyword_row.term)
if current is None or keyword_row.cost > current.cost:
self.top_keyword[keyword_row.term] = keyword_row
+ top_pages: dict[str, RankingPage] = {}
+ for page_row in inputs.ranking_pages:
+ current_page = top_pages.get(page_row.query)
+ if current_page is None or page_row.impressions > current_page.impressions:
+ top_pages[page_row.query] = page_row
+ self.ranking_page = {query: row.page for query, row in top_pages.items()}
def run(self) -> list[MarketingAnalyticsRecommendation]:
campaign_rules = sorted(self._campaign_rules(), key=lambda rec: -(rec.impact or 0))
@@ -518,16 +535,18 @@ class _Recommender:
MarketingAnalyticsRecommendationRule.CONTENT_GAP,
term,
"Create or improve a page for this search",
- f"Converts in Ads at a CPA of {self._money(term.cost / term.conversions)} "
- f"(account {self._money(cpa)}), but "
+ f"You pay {self._money(term.cost * self.per_month)}/mo in Ads for this search, which converts "
+ f"at a CPA of {self._money(term.cost / term.conversions)} (account {self._money(cpa)}). "
+ (
- f"ranks #{term.organic.position:.1f} organically"
+ f"It ranks #{term.organic.position:.1f} organically, so moving that page into the top 3 "
if term.organic
- else "does not rank organically"
- ),
+ else "It does not rank organically, so a new page in the top 3 "
+ )
+ + "could bring these visitors without ad spend.",
term.conversions * cpa,
"gain",
"measured",
+ steps=self._content_gap_steps(term),
)
for term in terms
if term.term not in self.brand_terms
@@ -570,6 +589,7 @@ class _Recommender:
max(term.organic.impressions * TOP3_CTR - term.organic.clicks, 0) * term.cost / term.clicks,
"gain",
"estimated",
+ steps=self._improve_page_steps(term.term),
)
for term in terms
if term.organic
@@ -935,6 +955,60 @@ class _Recommender:
linkText="Campaigns",
)
+ def _content_gap_steps(self, term: _Term) -> tuple[Step, ...]:
+ keep_ad = Step(text="Keep the ad running until the page reaches the top 3, then test pausing it.")
+ if term.organic:
+ return (*self._improve_page_steps(term.term), keep_ad)
+ return (
+ Step(
+ text="Create a page that answers this search. Use the search in the page title and main heading.",
+ copyValue=term.term,
+ ),
+ self._internal_links_step(),
+ Step(
+ text="In Search Console, use URL inspection to request indexing of the new page.",
+ url=self._search_console_url(SEARCH_CONSOLE_URL),
+ linkText="Search Console",
+ ),
+ keep_ad,
+ )
+
+ def _improve_page_steps(self, query: str) -> tuple[Step, ...]:
+ page = self.ranking_page.get(query)
+ find_page = (
+ Step(text="Open the page that ranks for this search.", copyValue=page, url=page, linkText="page")
+ if page
+ else Step(
+ text="In Search Console, open Performance, filter by this search and check the Pages tab to find "
+ "the page that ranks.",
+ copyValue=query,
+ url=self._search_console_url(SEARCH_CONSOLE_PERFORMANCE_URL),
+ linkText="Performance",
+ )
+ )
+ return (
+ find_page,
+ Step(
+ text="Use the search in the page title and main heading, and answer it near the top of the page.",
+ copyValue=query,
+ ),
+ self._internal_links_step(),
+ Step(
+ text="In Search Console, use URL inspection to request indexing of the updated page.",
+ url=self._search_console_url(SEARCH_CONSOLE_URL),
+ linkText="Search Console",
+ ),
+ )
+
+ def _search_console_url(self, url: str) -> str:
+ # With several properties the right one is unknown, so Search Console opens its property picker.
+ sites = set(self.inputs.site_urls)
+ return f"{url}?resource_id={quote(sites.pop(), safe='')}" if len(sites) == 1 else url
+
+ @staticmethod
+ def _internal_links_step() -> Step:
+ return Step(text="Link to the page from related pages on your site, using the search as the link text.")
+
def _term_recommendation(
self,
rule: MarketingAnalyticsRecommendationRule,
diff --git a/products/marketing_analytics/backend/hogql_queries/marketing_recommendations_query_runner.py b/products/marketing_analytics/backend/hogql_queries/marketing_recommendations_query_runner.py
index 2b57687bff3c..8c11d6199964 100644
--- a/products/marketing_analytics/backend/hogql_queries/marketing_recommendations_query_runner.py
+++ b/products/marketing_analytics/backend/hogql_queries/marketing_recommendations_query_runner.py
@@ -25,6 +25,7 @@ from posthog.hogql_queries.utils.query_date_range import QueryDateRange
from products.marketing_analytics.backend.hogql_queries.marketing_recommendations import (
CampaignStats,
OrganicQueryStats,
+ RankingPage,
RecommendationInputs,
SearchTermStats,
TermKeywordStats,
@@ -85,6 +86,7 @@ class MarketingAnalyticsRecommendationsQueryRunner(
date_from, date_to = self.query_date_range.date_from(), self.query_date_range.date_to()
organic_queries = tuple(query for source in organic for query in self._organic_queries(source))
site_urls = tuple(url for source in organic for url in self._site_urls(source))
+ ranking_pages = tuple(page for source in organic for page in self._ranking_pages(source))
days = max((date_to - date_from).days + 1, 1)
# Each ad account has its own campaigns, costs and currency, so rules compare a campaign only with
# campaigns from the same account. Search Console data is shared because it has no account link.
@@ -100,6 +102,7 @@ class MarketingAnalyticsRecommendationsQueryRunner(
currency=self._currency(source),
days=self._days_with_data(source) or days,
term_keywords=tuple(self._term_keywords(source)),
+ ranking_pages=ranking_pages,
)
)
]
@@ -340,6 +343,27 @@ class MarketingAnalyticsRecommendationsQueryRunner(
if row[2]
]
+ def _ranking_pages(self, source: MarketingAnalyticsRecommendationsSource) -> list[RankingPage]:
+ if not source.queryPageTable or not self._readable(source.queryPageTable):
+ return []
+ rows = self._select(
+ f"""
+ SELECT q, argMax(page, page_impressions), max(page_impressions)
+ FROM (
+ SELECT lower(trim(query)) AS q, page, sum(impressions) AS page_impressions
+ FROM {{table}}
+ WHERE toDate(date) >= toDate({{date_from}}) AND toDate(date) <= toDate({{date_to}})
+ AND notEmpty(q) AND notEmpty(page)
+ GROUP BY q, page
+ )
+ GROUP BY q
+ ORDER BY max(page_impressions) DESC
+ LIMIT {ROW_LIMIT}
+ """,
+ source.queryPageTable,
+ )
+ return [RankingPage(query=row[0], page=row[1], impressions=float(row[2] or 0)) for row in rows]
+
def _site_urls(self, source: MarketingAnalyticsRecommendationsSource) -> list[str]:
if not source.sitesTable or not self._readable(source.sitesTable):
return []
@@ -393,6 +417,7 @@ def _recommendation_source(source_type: str, tables: dict[str, str]) -> Marketin
return MarketingAnalyticsRecommendationsSource(
sourceType=MarketingAnalyticsRecommendationsSourceType.GOOGLE_SEARCH_CONSOLE,
queryTable=query_table,
+ queryPageTable=tables.get("search_analytics_by_query_page"),
sitesTable=tables.get("sites"),
)
diff --git a/products/marketing_analytics/backend/hogql_queries/test_marketing_recommendations.py b/products/marketing_analytics/backend/hogql_queries/test_marketing_recommendations.py
index dfa1a58520b9..233d20267387 100644
--- a/products/marketing_analytics/backend/hogql_queries/test_marketing_recommendations.py
+++ b/products/marketing_analytics/backend/hogql_queries/test_marketing_recommendations.py
@@ -5,8 +5,10 @@ from django.test import SimpleTestCase
from parameterized import parameterized
from products.marketing_analytics.backend.hogql_queries.marketing_recommendations import (
+ SEARCH_CONSOLE_PERFORMANCE_URL,
CampaignStats,
OrganicQueryStats,
+ RankingPage,
RecommendationInputs,
SearchTermStats,
TermKeywordStats,
@@ -51,9 +53,11 @@ def _inputs(
terms: tuple[SearchTermStats, ...] = (),
organic: tuple[OrganicQueryStats, ...] = (),
term_keywords: tuple[TermKeywordStats, ...] = (),
+ ranking_pages: tuple[RankingPage, ...] = (),
) -> RecommendationInputs:
return RecommendationInputs(
term_keywords=term_keywords,
+ ranking_pages=ranking_pages,
campaigns=campaigns,
search_terms=terms,
organic_queries=organic,
@@ -151,6 +155,47 @@ class TestMarketingRecommendations(SimpleTestCase):
assert "costly converter" not in steps[2].text and "cheap but excluded" not in steps[2].text
assert all(step.linkText and step.linkText in step.text for step in steps if step.url)
+ @parameterized.expand(
+ [
+ ("near_top_3_with_known_page", 8.0, True, "striking_distance", "https://example.com/funnels"),
+ (
+ "near_top_3_without_page_table",
+ 8.0,
+ False,
+ "striking_distance",
+ f"{SEARCH_CONSOLE_PERFORMANCE_URL}?resource_id=sc-domain%3Aexample.com",
+ ),
+ ("ranks_beyond_page_one", 30.0, True, "content_gap", "https://example.com/funnels"),
+ ("does_not_rank", None, True, "content_gap", None),
+ ]
+ )
+ def test_organic_steps_start_from_the_page_that_ranks(
+ self, _name: str, position: float | None, has_pages: bool, rule: str, first_url: str | None
+ ) -> None:
+ terms = (
+ _term("funnel analysis", "c1", cost=100, conversions=5),
+ _term("session replay", "c1", cost=900, conversions=5),
+ )
+ organic = (
+ (OrganicQueryStats(query="funnel analysis", clicks=20, impressions=2000, position=position),)
+ if position
+ else ()
+ )
+ pages = (
+ RankingPage(query="funnel analysis", page="https://example.com/blog", impressions=300),
+ RankingPage(query="funnel analysis", page="https://example.com/funnels", impressions=1700),
+ )
+
+ recs = recommend(_inputs((_campaign(),), terms, organic, ranking_pages=pages if has_pages else ()))
+
+ organic_recs = [rec for rec in recs if rec.subject == "funnel analysis" and rec.rule == rule]
+ assert len(organic_recs) == 1
+ steps = organic_recs[0].steps or []
+ assert steps[0].url == first_url
+ if first_url is None:
+ assert steps[0].text.startswith("Create a page")
+ assert all(step.linkText and step.linkText in step.text for step in steps if step.url)
+
@parameterized.expand(
[
("another_ad_often_shows_above", 0.6, "keep", "Keep the ad"),
diff --git a/products/marketing_analytics/backend/hogql_queries/test_marketing_recommendations_query_runner.py b/products/marketing_analytics/backend/hogql_queries/test_marketing_recommendations_query_runner.py
index fa5f7e3778d7..2f4e8239e341 100644
--- a/products/marketing_analytics/backend/hogql_queries/test_marketing_recommendations_query_runner.py
+++ b/products/marketing_analytics/backend/hogql_queries/test_marketing_recommendations_query_runner.py
@@ -84,6 +84,30 @@ class TestMarketingAnalyticsRecommendationsQueryRunner(ClickhouseTestMixin, Base
budget = [(rec.subject, rec.action) for rec in response.results if rec.rule == "budget_constrained"]
assert budget == ([("Campaign 101", "Raise the daily budget from $100 to $300")] if has_status else [])
+ def test_ranking_page_is_the_page_with_most_impressions_for_the_query(self) -> None:
+ query_page = self._table(
+ "search_analytics_by_query_page",
+ {"date": "Date", "query": "String", "page": "String", "impressions": "Float64"},
+ "date,query,page,impressions\n"
+ "2026-01-10,Funnel Analysis,https://example.com/blog,600\n"
+ "2026-01-11,funnel analysis,https://example.com/funnels,400\n"
+ "2026-01-12,funnel analysis,https://example.com/funnels,400\n"
+ "2025-12-01,funnel analysis,https://example.com/old,5000\n",
+ )
+ runner = MarketingAnalyticsRecommendationsQueryRunner(
+ query=MarketingAnalyticsRecommendationsQuery(
+ dateRange=DateRange(date_from="2026-01-01", date_to="2026-01-30")
+ ),
+ team=self.team,
+ user=self.user,
+ )
+
+ pages = runner._ranking_pages(
+ MarketingAnalyticsRecommendationsSource(sourceType="GoogleSearchConsole", queryPageTable=query_page)
+ )
+
+ assert [(page.query, page.page) for page in pages] == [("funnel analysis", "https://example.com/funnels")]
+
class TestMarketingAnalyticsRecommendationsSourceDiscovery(BaseTest):
def _source(self, source_type: str, prefix: str, schemas: dict[str, bool]) -> None:
@@ -133,6 +157,7 @@ class TestMarketingAnalyticsRecommendationsSourceDiscovery(BaseTest):
{
"sourceType": "GoogleSearchConsole",
"queryTable": "googlesearchconsole.organic.search_analytics_by_query_page",
+ "queryPageTable": "googlesearchconsole.organic.search_analytics_by_query_page",
"sitesTable": "googlesearchconsole.organic.sites",
},
]
diff --git a/products/marketing_analytics/frontend/recommendations/RecommendationStepText.tsx b/products/marketing_analytics/frontend/recommendations/RecommendationStepText.tsx
index 22f26d981f27..360322c2f0d5 100644
--- a/products/marketing_analytics/frontend/recommendations/RecommendationStepText.tsx
+++ b/products/marketing_analytics/frontend/recommendations/RecommendationStepText.tsx
@@ -14,7 +14,11 @@ export function RecommendationStepText({ step }: { step: MarketingAnalyticsRecom
to={step.url}
target="_blank"
targetBlankIcon
- data-attr="marketing-recommendations-step-open-google-ads"
+ data-attr={
+ step.url.startsWith('https://ads.google.com/')
+ ? 'marketing-recommendations-step-open-google-ads'
+ : 'marketing-recommendations-step-open-link'
+ }
>
{step.linkText}
</Link>
diff --git a/products/marketing_analytics/frontend/recommendations/recommendations.ts b/products/marketing_analytics/frontend/recommendations/recommendations.ts
index a128dd90874c..e58aa7f22bf1 100644
--- a/products/marketing_analytics/frontend/recommendations/recommendations.ts
+++ b/products/marketing_analytics/frontend/recommendations/recommendations.ts
@@ -215,7 +215,12 @@ export function recommendationsSource(source: ExternalDataSource): MarketingAnal
if (!queryTable) {
return null
}
- return { sourceType: 'GoogleSearchConsole', queryTable, sitesTable: syncedTable(source, 'sites') }
+ return {
+ sourceType: 'GoogleSearchConsole',
+ queryTable,
+ queryPageTable: syncedTable(source, 'search_analytics_by_query_page'),
+ sitesTable: syncedTable(source, 'sites'),
+ }
}
return null
}
diff --git a/products/marketing_analytics/mcp/prompts/query-marketing-recommendations.md b/products/marketing_analytics/mcp/prompts/query-marketing-recommendations.md
index 047849aa7054..b450ca3d67b2 100644
--- a/products/marketing_analytics/mcp/prompts/query-marketing-recommendations.md
+++ b/products/marketing_analytics/mcp/prompts/query-marketing-recommendations.md
@@ -20,7 +20,7 @@ Each result has:
- `action` and `reason` — what to do and the numbers behind it. Quote them instead of inventing your own advice.
- `impact` — the monthly money impact in `currency`, or null. `impactDirection` says how to read it: `save` is spend to cut, `invest` is extra budget to add, `gain` is value to win, and `keep` is spend to protect.
- `impactType` — `measured` comes straight from the data. `estimated` is a projection, so present it as an estimate.
-- `steps` — how to apply the recommendation in the Google Ads interface, in order. A step's `copyValue` is the exact text to paste, such as a campaign name or a keyword in match type syntax (`[term]` is exact match, `"term"` is phrase match). A step's `url` opens the Google Ads section named by `linkText`, for the whole account. When the user asks how to make a change, walk them through these steps. Some rules have no steps yet.
+- `steps` — how to apply the recommendation, in order. A step's `copyValue` is the exact text to paste, such as a campaign name, a keyword in match type syntax (`[term]` is exact match, `"term"` is phrase match) or a page URL. A step's `url` opens what `linkText` names: a Google Ads section for the whole account, Google Search Console, or the page on the user's site that ranks for the search. When the user asks how to make a change, walk them through these steps. Some rules have no steps yet.
Totals in different currencies come from different ad accounts. Never add them together.
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index b7a537f2cd6c..51ad2d7d3afd 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -11955,7 +11955,7 @@
"system_prompt_hint": "Log filtering by severity/service/attribute"
},
"query-marketing-recommendations": {
- "description": "Get paid and organic search recommendations for the project's Google Ads accounts, built from synced Google Ads and Google Search Console warehouse tables. Mirrors the recommendations in the in-product **Marketing analytics** scene.\n\n# When to use\n\nUse this tool when the user asks where to cut ad spend, which campaigns to scale or review, which search terms waste money, or how paid and organic search overlap.\n\nDo not use it for attribution, conversion goals, or channel performance. Use `marketing-analytics-diagnose` when the data looks missing or wrong.\n\n# Inputs\n\n- `dateRange` — pass `{ \"date_from\": \"-30d\" }` unless the user asks for another period. Short ranges give few recommendations, because the rules need enough clicks and spend to compare.\n- Leave everything else out. The tool reads every synced Google Ads and Google Search Console source in the project.\n\n# Output\n\nEach result has:\n\n- `rule` — the check that produced it, for example `spend_without_conversions`, `brand_leak`, `budget_constrained`, `scale_campaign`, `review_campaign`, `brand_overlap`, `content_gap`, `keyword_gap`, `striking_distance` or `policy_limited`.\n- `level` — `campaign` or `search_term`. `subject` is the campaign name or the search term, and `campaign` is the campaign a search term belongs to. For `keyword_gap`, `campaign` is the campaign to add the keyword to, because the search is not bought yet.\n- `action` and `reason` — what to do and the numbers behind it. Quote them instead of inventing your own advice.\n- `impact` — the monthly money impact in `currency`, or null. `impactDirection` says how to read it: `save` is spend to cut, `invest` is extra budget to add, `gain` is value to win, and `keep` is spend to protect.\n- `impactType` — `measured` comes straight from the data. `estimated` is a projection, so present it as an estimate.\n- `steps` — how to apply the recommendation in the Google Ads interface, in order. A step's `copyValue` is the exact text to paste, such as a campaign name or a keyword in match type syntax (`[term]` is exact match, `\"term\"` is phrase match). A step's `url` opens the Google Ads section named by `linkText`, for the whole account. When the user asks how to make a change, walk them through these steps. Some rules have no steps yet.\n\nTotals in different currencies come from different ad accounts. Never add them together.\n\nPresent the results as suggestions for the user to evaluate, not as instructions. Always show the response's `disclaimer` text with them. Do not change campaigns, budgets, bids or keywords on the user's behalf.\n\nAn empty result means no rule fired, or the project has no synced Google Ads `campaign` and `campaign_stats` tables. Call `marketing-analytics-data-sources` to tell the two apart.\n\n# Example\n\n```json\n{\n \"kind\": \"MarketingAnalyticsRecommendationsQuery\",\n \"dateRange\": { \"date_from\": \"-30d\" }\n}\n```",
+ "description": "Get paid and organic search recommendations for the project's Google Ads accounts, built from synced Google Ads and Google Search Console warehouse tables. Mirrors the recommendations in the in-product **Marketing analytics** scene.\n\n# When to use\n\nUse this tool when the user asks where to cut ad spend, which campaigns to scale or review, which search terms waste money, or how paid and organic search overlap.\n\nDo not use it for attribution, conversion goals, or channel performance. Use `marketing-analytics-diagnose` when the data looks missing or wrong.\n\n# Inputs\n\n- `dateRange` — pass `{ \"date_from\": \"-30d\" }` unless the user asks for another period. Short ranges give few recommendations, because the rules need enough clicks and spend to compare.\n- Leave everything else out. The tool reads every synced Google Ads and Google Search Console source in the project.\n\n# Output\n\nEach result has:\n\n- `rule` — the check that produced it, for example `spend_without_conversions`, `brand_leak`, `budget_constrained`, `scale_campaign`, `review_campaign`, `brand_overlap`, `content_gap`, `keyword_gap`, `striking_distance` or `policy_limited`.\n- `level` — `campaign` or `search_term`. `subject` is the campaign name or the search term, and `campaign` is the campaign a search term belongs to. For `keyword_gap`, `campaign` is the campaign to add the keyword to, because the search is not bought yet.\n- `action` and `reason` — what to do and the numbers behind it. Quote them instead of inventing your own advice.\n- `impact` — the monthly money impact in `currency`, or null. `impactDirection` says how to read it: `save` is spend to cut, `invest` is extra budget to add, `gain` is value to win, and `keep` is spend to protect.\n- `impactType` — `measured` comes straight from the data. `estimated` is a projection, so present it as an estimate.\n- `steps` — how to apply the recommendation, in order. A step's `copyValue` is the exact text to paste, such as a campaign name, a keyword in match type syntax (`[term]` is exact match, `\"term\"` is phrase match) or a page URL. A step's `url` opens what `linkText` names: a Google Ads section for the whole account, Google Search Console, or the page on the user's site that ranks for the search. When the user asks how to make a change, walk them through these steps. Some rules have no steps yet.\n\nTotals in different currencies come from different ad accounts. Never add them together.\n\nPresent the results as suggestions for the user to evaluate, not as instructions. Always show the response's `disclaimer` text with them. Do not change campaigns, budgets, bids or keywords on the user's behalf.\n\nAn empty result means no rule fired, or the project has no synced Google Ads `campaign` and `campaign_stats` tables. Call `marketing-analytics-data-sources` to tell the two apart.\n\n# Example\n\n```json\n{\n \"kind\": \"MarketingAnalyticsRecommendationsQuery\",\n \"dateRange\": { \"date_from\": \"-30d\" }\n}\n```",
"category": "Marketing analytics",
"feature": "marketing_analytics",
"summary": "Get paid and organic search recommendations",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index fdcab781c8c5..6eedaa13a683 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -12641,7 +12641,7 @@
"system_prompt_hint": "Log filtering by severity/service/attribute"
},
"query-marketing-recommendations": {
- "description": "Get paid and organic search recommendations for the project's Google Ads accounts, built from synced Google Ads and Google Search Console warehouse tables. Mirrors the recommendations in the in-product **Marketing analytics** scene.\n\n# When to use\n\nUse this tool when the user asks where to cut ad spend, which campaigns to scale or review, which search terms waste money, or how paid and organic search overlap.\n\nDo not use it for attribution, conversion goals, or channel performance. Use `marketing-analytics-diagnose` when the data looks missing or wrong.\n\n# Inputs\n\n- `dateRange` — pass `{ \"date_from\": \"-30d\" }` unless the user asks for another period. Short ranges give few recommendations, because the rules need enough clicks and spend to compare.\n- Leave everything else out. The tool reads every synced Google Ads and Google Search Console source in the project.\n\n# Output\n\nEach result has:\n\n- `rule` — the check that produced it, for example `spend_without_conversions`, `brand_leak`, `budget_constrained`, `scale_campaign`, `review_campaign`, `brand_overlap`, `content_gap`, `keyword_gap`, `striking_distance` or `policy_limited`.\n- `level` — `campaign` or `search_term`. `subject` is the campaign name or the search term, and `campaign` is the campaign a search term belongs to. For `keyword_gap`, `campaign` is the campaign to add the keyword to, because the search is not bought yet.\n- `action` and `reason` — what to do and the numbers behind it. Quote them instead of inventing your own advice.\n- `impact` — the monthly money impact in `currency`, or null. `impactDirection` says how to read it: `save` is spend to cut, `invest` is extra budget to add, `gain` is value to win, and `keep` is spend to protect.\n- `impactType` — `measured` comes straight from the data. `estimated` is a projection, so present it as an estimate.\n- `steps` — how to apply the recommendation in the Google Ads interface, in order. A step's `copyValue` is the exact text to paste, such as a campaign name or a keyword in match type syntax (`[term]` is exact match, `\"term\"` is phrase match). A step's `url` opens the Google Ads section named by `linkText`, for the whole account. When the user asks how to make a change, walk them through these steps. Some rules have no steps yet.\n\nTotals in different currencies come from different ad accounts. Never add them together.\n\nPresent the results as suggestions for the user to evaluate, not as instructions. Always show the response's `disclaimer` text with them. Do not change campaigns, budgets, bids or keywords on the user's behalf.\n\nAn empty result means no rule fired, or the project has no synced Google Ads `campaign` and `campaign_stats` tables. Call `marketing-analytics-data-sources` to tell the two apart.\n\n# Example\n\n```json\n{\n \"kind\": \"MarketingAnalyticsRecommendationsQuery\",\n \"dateRange\": { \"date_from\": \"-30d\" }\n}\n```",
+ "description": "Get paid and organic search recommendations for the project's Google Ads accounts, built from synced Google Ads and Google Search Console warehouse tables. Mirrors the recommendations in the in-product **Marketing analytics** scene.\n\n# When to use\n\nUse this tool when the user asks where to cut ad spend, which campaigns to scale or review, which search terms waste money, or how paid and organic search overlap.\n\nDo not use it for attribution, conversion goals, or channel performance. Use `marketing-analytics-diagnose` when the data looks missing or wrong.\n\n# Inputs\n\n- `dateRange` — pass `{ \"date_from\": \"-30d\" }` unless the user asks for another period. Short ranges give few recommendations, because the rules need enough clicks and spend to compare.\n- Leave everything else out. The tool reads every synced Google Ads and Google Search Console source in the project.\n\n# Output\n\nEach result has:\n\n- `rule` — the check that produced it, for example `spend_without_conversions`, `brand_leak`, `budget_constrained`, `scale_campaign`, `review_campaign`, `brand_overlap`, `content_gap`, `keyword_gap`, `striking_distance` or `policy_limited`.\n- `level` — `campaign` or `search_term`. `subject` is the campaign name or the search term, and `campaign` is the campaign a search term belongs to. For `keyword_gap`, `campaign` is the campaign to add the keyword to, because the search is not bought yet.\n- `action` and `reason` — what to do and the numbers behind it. Quote them instead of inventing your own advice.\n- `impact` — the monthly money impact in `currency`, or null. `impactDirection` says how to read it: `save` is spend to cut, `invest` is extra budget to add, `gain` is value to win, and `keep` is spend to protect.\n- `impactType` — `measured` comes straight from the data. `estimated` is a projection, so present it as an estimate.\n- `steps` — how to apply the recommendation, in order. A step's `copyValue` is the exact text to paste, such as a campaign name, a keyword in match type syntax (`[term]` is exact match, `\"term\"` is phrase match) or a page URL. A step's `url` opens what `linkText` names: a Google Ads section for the whole account, Google Search Console, or the page on the user's site that ranks for the search. When the user asks how to make a change, walk them through these steps. Some rules have no steps yet.\n\nTotals in different currencies come from different ad accounts. Never add them together.\n\nPresent the results as suggestions for the user to evaluate, not as instructions. Always show the response's `disclaimer` text with them. Do not change campaigns, budgets, bids or keywords on the user's behalf.\n\nAn empty result means no rule fired, or the project has no synced Google Ads `campaign` and `campaign_stats` tables. Call `marketing-analytics-data-sources` to tell the two apart.\n\n# Example\n\n```json\n{\n \"kind\": \"MarketingAnalyticsRecommendationsQuery\",\n \"dateRange\": { \"date_from\": \"-30d\" }\n}\n```",
"category": "Marketing analytics",
"feature": "marketing_analytics",
"summary": "Get paid and organic search recommendations",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 5f4f32b28e0e..0a107e1f122b 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -53790,6 +53790,8 @@ export namespace Schemas {
customerTable?: string | null;
/** Google Ads search term table for Performance Max campaigns. */
performanceMaxSearchTermTable?: string | null;
+ /** Google Search Console table with one row per query and page, used to find the page that ranks for a search. */
+ queryPageTable?: string | null;
/** Google Search Console table with one row per query, or per query and page. */
queryTable?: string | null;
/** Google Ads search term table split by the keyword that matched each term. */