RevenueScope: revenue-first analytics for your EC site

Return AI-assistant (ChatGPT/Claude/Perplexity/Gemini/Copilot) traffic for the given period. mode='referred' (default) lists landing pages that received clicked AI traffic — per page × AI source: sessions, bounce rate (%, always computed; judge reliability via the sessions count), summed revenue, and last citation date (last_cited_at is JST ISO8601 with a +09:00 offset — the same basis as the dashboard, so dates line up when compared) (default limit 100); a view GA4/GSC cannot produce (GSC is Google-search only; GA4 lacks an AI-source breakdown). mode='gaps' returns where the site leaves AI value on the table as a ranked action list: (1) missed_citation_pages — content articles with real audience but ~0 AI traffic (push for AI citation / GEO), ranked by engagement-weighted reach; (2) under_monetized_ai_pages — pages WITH AI traffic engaging below the site's own AI norm (improve landing/CTA), ranked by AI arrivals lost below benchmark (default limit 10/list); methodology fixed in code. site_id is OPTIONAL when OAuth-authenticated. Default period is the last 30 days; pass period='today'/'7d'/'90d' or a raw day count (1-365). Scope is clicked citations only.

Consolidated breakdown tool. Pick `dimension`: 'channel' returns per-channel sessions/revenue/RPS plus engagement (visitors, avg dwell seconds, bounce rate) and bot_excluded_count (bot sessions removed from human metrics; a channel with sessions=0 but bot_excluded_count>0 is bot-only traffic, kept so it is not mistaken for 'no traffic') and — when ad spend is connected (Path B) — spend/ROAS/saturation; plus an 'Unattributed' row (is_unattributed=true) for purchase revenue not tied to any channel, with a revenue_breakdown summary (total_event_jpy/attributed_jpy/unattributed_jpy); pass attribution_model ('last_touch' default / 'first_touch' / 'linear' / 'time_decay') to switch how purchase revenue and orders are attributed across channels — same models as the dashboard's attribution selector; revenue_jpy/rps_jpy/orders/aov_jpy/cvr change, while sessions/engagement/bot/spend/ROAS are model-independent [ad-platform rows, is_ad_platform=true, are entirely model-independent, revenue_jpy and rps_jpy included — they are the spend-basis view, so on them revenue_jpy ÷ spend_jpy always equals roas, up to the rounding of roas to 2 decimals; under a non-default model their revenue_jpy/rps_jpy keep the database_statement_time_window boundary shown for roas rather than the reference_timestamp_window that presentation_hints lists for rows[*].revenue_jpy], so compare models to see e.g. how much an awareness channel gains under first_touch vs last_touch. each channel row also carries orders (purchase orders counted by our own tracker), aov_jpy and cvr derived from it — withheld as null below 10 orders, and always null on ad-platform / Unattributed rows; do NOT divide revenue_jpy by `conversions` to rebuild AOV, `conversions` is the ad platform's self-reported count, a different denominator. pass filter.channel to drill into that channel's campaigns (utm_campaign) with RPS/AOV/CVR — the value must be a channel name exactly as this tool returns it, case included (e.g. 'Google Ads', 'M…

Return the latest competitor SEO snapshot for the site (FD-041): which keywords each tracked competitor DOMAIN ranks for on Google (Japan/ja), at what position, with monthly search_volume, cpc and etv (estimated monthly traffic — a visit estimate, not a monetary value), plus how each rank moved vs the previous snapshot. READ-ONLY — this tool never runs a research (that costs money and is triggered separately from the dashboard, the competitor-research Edge Function); it only reads what was already fetched. The response is summary-first (token-aware): each domain carries a constant-size `summary` (total_keywords, total_etv, volume_bands and rank_bands histograms, and vs_previous new/lost/improved/declined/same counts) that always reflects the FULL keyword set, while `keywords` returns only the top rows ranked by `sort` (etv default | volume | rank; default limit 10 per domain, max 100) with a `truncated` block (shown/matching_total/lost_total). rank is a POSITION: smaller is better, so a NEGATIVE rank_delta means the competitor's ranking IMPROVED (change ∈ new/improved/declined/same/unknown). Keywords the competitor ranked for before but lost are disclosed in `lost_keywords` (top 10 by previous etv), never dropped silently. Pass `domain` to focus one competitor, `min_volume` to drop low-volume keywords. When the site has NO completed research yet the response is { researched:false } with a `guidance` string explaining a research must be triggered from the dashboard first — this tool cannot start one. site_id is OPTIONAL when OAuth-authenticated. This is the external competitor lens (third-party SERP data); for YOUR OWN search performance use get_keyword_performance, and for your content playbook use get_content_actions.

Return a content 'playbook' for the site: every content page classified into ONE of five action buckets over a weekly-style window comparison (current window vs the immediately preceding window of equal length), ranked by search-opportunity × session gain so you can tell the user which page to GROW next and what to do: within the 'striking' bucket rows are ordered by expected_sessions_gain DESC (the band-CTR headroom that is the actionable lever there), while the other buckets keep real landing revenue DESC (largest revenue at stake first). This surfaces search intent to add sessions (grow the traffic denominator), NOT CVR — a page already winning on sessions/revenue but with zero clicks still shows up. Buckets: 'decaying' (search clicks actually fell, OR the page had real traffic (previous clicks ≥3) and its rank slid ≥2 positions from within the click zone while clicks did NOT grow → refresh/rewrite; a rank slide alone with growing/negligible clicks is NOT decay — search clicks are the primary signal, position only a leading indicator), 'striking' (has striking-distance queries at positions 4-20 with click upside but clicks still low → push those queries up; top 3 listed in striking_queries), 'rising' (clicks grew significantly → produce more of this, strengthen CTA), 'dormant' (has impressions but ~0 clicks and its main query is far below the click zone → big rewrite or consolidate; zero-pageview pure-rank pages surface here), 'stable' (none of the above → watch). Each page also carries current/previous clicks·impressions·avg_position, is_new, landing sessions/engaged/revenue_jpy, AI-referred sessions/revenue/sources, expected_sessions_gain (the window's expected incremental sessions from striking-band queries — a search click is ~1 session, so it is NOT re-converted via CTR; normalize to a monthly figure with the window length), and expected_revenue_gain (expected_sessions_gain × page RPS, returned ONLY when revenue>0 and sessions>=5 — display-only projection,…

Return search-query performance from Google Search Console for the given period. band='all' (default) returns per-query metrics — clicks/impressions/CTR/avg position/top landing page plus an estimated revenue per query (= 検索 organic RPS × clicks, a conservative estimate, 0 until the site has 検索 organic revenue), ranked by clicks (default limit 100). Each row also carries the period-over-period change vs the previous equal-length window: clicks_change (traffic) and est_revenue_change (money), both % deltas (null = the query is NEW, i.e. had no clicks/revenue last period — render as '新規', not 0%). Comparing the two surfaces RS's signature insight — e.g. clicks +74% but est_revenue −21% means traffic grew while money fell, something GA4/GSC cannot show side by side. band='striking' returns the SEO action list: queries 'striking distance' from the top (ranking ~4-20 with real impressions) where improving a few positions yields the biggest click/revenue gain, ranked by estimated revenue opportunity (incremental clicks × search-organic RPS, default limit 10); the methodology is fixed in code. site_id is OPTIONAL when OAuth-authenticated. Default period is the last 30 days; pass period='today'/'7d'/'90d' or a raw day count (1-365). Google-search only.

Return how ONE page's Google Search performance changed over time (FD-040) — the time-axis drill-down for a page surfaced by get_breakdown(dimension='page'). Given a `page` (a normalized path like '/news/rps-revenue-per-session-guide' or a full URL — both resolve), returns a `series` of day or week buckets, each with clicks, impressions, and impression-weighted avg_position, plus a `summary` (first/last/best/worst position, position_delta, click & impression totals). avg_position is a RANK: smaller is better, so a NEGATIVE position_delta means the page's ranking IMPROVED over the window (e.g. 12.0 → 9.0 = delta −3.0). Use this to verify whether SEO work on a page paid off (rank rose / clicks grew) or slipped. Buckets where the page never appeared in search are omitted (gaps), so the series can be shorter than the period. `granularity` defaults to 'day' for windows up to ~35 days and 'week' for longer (weekly smooths daily noise); pass it to override. site_id is OPTIONAL when OAuth-authenticated. Default period is the last 30 days; pass period='today'/'7d'/'90d' or a raw day count (1-365). Google-search only; data lags 1-2 days. This is per-page; for the cross-page snapshot use get_breakdown(dimension='page'), and for per-query (keyword) trends use get_keyword_performance.

Return the top 3 prioritized, pre-computed DIAGNOSES for the site over the given period — 'what should I act on this week', ranked by revenue impact. Unlike get_summary / get_breakdown (which return data), this applies a deterministic rule engine over KPI period-over-period changes, per-channel RPS/ROAS/saturation, and AI-assistant referral growth, and returns ranked findings (revenue-trend swings, high-efficiency channels to scale, over-allocated low-efficiency channels, loss-making/saturated ad channels, revenue concentration risk, emerging AI traffic) — each with a severity (risk/opportunity/watch), the numbers, and a recommended action. The priority judgment is fixed in code (not LLM-generated). site_id is OPTIONAL when OAuth-authenticated. Default period is 30 days; pass period='today'/'7d'/'90d' or a raw day count (1-365). period and previous_period describe the KPI engine's current and previous windows; each returned insight carries source_boundaries because channel, ad-spend, and AI signals can use different source windows. Returns fewer than 3 when fewer rules fire (no padding).

Return the full headline summary for a site and period in ONE call: the 5 KPIs (revenue, sessions, RPS, AOV, CVR) PLUS two engagement KPIs (avg_duration = average dwell time in seconds, bounce_rate = % single-page-exit sessions) each with value AND the period-over-period change vs the previous equal-length window, PLUS a daily revenue/sessions/conversions trend, PLUS ad-spend availability (connected_channels, ad_spend_data_status, ad_spend_channels_in_period) and the Path A/B recommendation. avg_duration/bounce_rate are useful for sites with no revenue yet (engagement view). scroll_depth is the average scroll depth (%), taken per session as its deepest point then averaged; its change is a percentage-point delta. IMPORTANT: its denominator differs from avg_duration/bounce_rate — depth only covers sessions whose exit beacon landed, and sessions without one are excluded rather than counted as 0. scroll_depth is null when the window holds no depth signal at all (0% would read as 'read shallowly' when the truth is 'not measured'); depth has only been collected since 2026-06-15, so longer windows are partial. Pass optional country (ISO2, e.g. 'JP') and/or device ('mobile'/'desktop'/'tablet') to scope the session-derived KPIs and trend to that segment (omit = all); ROAS stays site-wide (ad spend has no country/device dimension). This is what the dashboard's KPI cards + revenue-trend chart show, merged with the site's ad-spend context. Call this first when a user asks 'how is my site doing?'. site_id is OPTIONAL when OAuth-authenticated (server falls back to the primary site). Default period is the last 30 days; pass period='today'/'7d'/'90d' or a raw day count (1-365). change is a percentage for revenue/sessions/RPS/AOV/avg_duration and an absolute percentage-point delta for CVR and bounce_rate. For period='today' the comparison is today-so-far vs the SAME elapsed window yesterday (e.g. midnight→now vs midnight→same-time-yesterday), so 'previous' can read below yesterday'…

List the sites this caller can analyze, in two groups. my_sites = the sites connected to the signed-in account (each with its display name + domain, so you can match phrases like "the production site" or "revenuescope.jp" without the user pasting a UUID); empty when the caller is not signed in. demo_sites = ready-made sample sites for trying RevenueScope before connecting your own — each is a fictional site with sample data, not a real customer. When signed in (OAuth), prefer my_sites and, if site_id is omitted, default analytics tools to the is_primary=true site. When NOT signed in, my_sites is empty: use a demo_sites site_id and tell the user the numbers come from a sample site, not their own.

Return a proposed monthly budget split across paid ad channels (Google Ads / Meta / TikTok Ads / Yahoo! Ads / LINE Ads etc.). site_id is OPTIONAL when the request is OAuth-authenticated. Path B (ad spend connected — any channel with spend>0 in the period): weight = ROAS × (1 − saturation) where ROAS is RS-measured revenue ÷ spend (FD-030 A-1, same as the dashboard — NOT platform-reported conversion_value). saturation は RS 自身では推定せず、広告データとして供給された場合のみ使用する (推定エンジンは W17+)。値が無いチャネルは ROAS のみで加重し効率投下上限をかけない — limitations に明記する。⚠ 配分候補は広告プラットフォーム単位 (Meta / Google Ads …) で、Instagram と Facebook のようにセッション側の粒度が細かいチャネルは所属プラットフォームへ畳んで扱う (FD-055)。 Path A (no ad spend): RPS-weighted proportional split with explicit ±20-30% caveats and a connect_incentive_message. Default period for the underlying ROAS/RPS data is 30 days; pass period='today' / '7d' / '90d' or a raw day count (1-365) to override. LLMs should pass `assumptions`, `limitations`, and `connect_incentive_message` through verbatim — they are hardcoded honest axis.