RevenueScope: revenue-first analytics for your EC site

Content actions (classify pages + playbook)

get_content_actions

Read-only

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, never a sort key). The deterministic action mapping and all (provisional) thresholds come back in criteria; the model does the narrative interpretation (mcp-first). Rows with confidence='low' carry caveats — 'geo_winning_suspect' (AI Overview/citations likely substitute the click: a GEO win, don't break the page; cross-check get_ai_traffic), 'zero_click_suspect' (SERP-feature occupation or intent-mismatch/polysemous query: verify the live SERP first), 'ai_cited' (decaying but the AI citation is alive) — verify before acting on low-confidence rows; definitions in criteria.caveat_flags. The response is summary-first (token-aware): bucket_summary always holds the FULL pre-limit distribution (per-bucket count/revenue/clicks) plus total_pages, while pages returns only the top rows in priority order (default limit 15, max 200); pass bucket='striking' etc. to drill into one bucket, and check truncated — when present it tells how many rows were cut and how to fetch them. GSC-driven and Google-search only; data lags 1-2 days so the current window's right edge sits a few days back. When narrating a bucket to the user, scope it to Google search — say 'search traffic to this page is declining', NOT 'this page is declining'; the classification is a search-trend diagnosis, not overall page health, so a page labeled 'decaying' can be thriving on Direct/social/AI. Before calling a negative bucket (decaying/dormant) a problem, cross-check the row's landing sessions/revenue_jpy and ai_sessions. site_id is OPTIONAL when OAuth-authenticated. Default window is the last 7 days vs the prior 7; pass period='30d'/'90d' or a raw day count (2-365). Window date bounds are INCLUSIVE on both ends, so period=Nd actually spans N+1 calendar dates (the real range is in window); both windows share the same length, so the comparison stays symmetric. This is the cross-page action snapshot; for one page's time series use get_page_trend, and for AI-citation gaps use get_ai_traffic(mode='gaps').

Input Schema

TableJSON Schema

Name	Required	Default
`limit`	No
`bucket`	No
`period`	No	7d
`site_id`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`basis`	Yes
`pages`	Yes
`period`	Yes
`window`	Yes
`site_id`	Yes
`warning`	No
`criteria`	Yes
`truncated`	No
`assumptions`	Yes
`limitations`	Yes
`total_pages`	Yes
`bucket_summary`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedJul 15, 2026

addedOutput schema / properties / criteria / properties / expected_revenue_gain
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / criteria / properties / expected_sessions_gain
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / criteria / properties / priority
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / properties / criteria / required

Previous value: -[
-  "provisional",
-  "comparison",
-  "significant_clicks_delta",
-  "position_worsening",
-  "striking_band",
-  "striking_clicks_below",
-  "dormant",
-  "landing_attribution",
-  "caveat_flags"
-]New value: +[
+  "provisional",
+  "comparison",
+  "significant_clicks_delta",
+  "position_worsening",
+  "striking_band",
+  "striking_clicks_below",
+  "dormant",
+  "landing_attribution",
+  "priority",
+  "expected_sessions_gain",
+  "expected_revenue_gain",
+  "caveat_flags"
+]

addedOutput schema / properties / pages / items / properties / expected_revenue_gain
```
Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}
```
addedOutput schema / properties / pages / items / properties / expected_sessions_gain
```
Added value: +{
+  "type": "number"
+}
```

changedOutput schema / properties / pages / items / required

Previous value: -[
-  "page",
-  "action",
-  "confidence",
-  "caveats",
-  "is_new",
-  "cur_clicks",
-  "cur_impressions",
-  "cur_position",
-  "prev_clicks",
-  "prev_impressions",
-  "prev_position",
-  "main_query_position",
-  "striking_uplift_clicks",
-  "striking_query_count",
-  "striking_queries",
-  "sessions",
-  "engaged",
-  "revenue_jpy",
-  "ai_sessions",
-  "ai_revenue_jpy",
-  "ai_sources",
-  "clicks_threshold"
-]New value: +[
+  "page",
+  "action",
+  "confidence",
+  "caveats",
+  "is_new",
+  "cur_clicks",
+  "cur_impressions",
+  "cur_position",
+  "prev_clicks",
+  "prev_impressions",
+  "prev_position",
+  "main_query_position",
+  "striking_uplift_clicks",
+  "striking_query_count",
+  "striking_queries",
+  "sessions",
+  "engaged",
+  "revenue_jpy",
+  "ai_sessions",
+  "ai_revenue_jpy",
+  "ai_sources",
+  "clicks_threshold",
+  "expected_sessions_gain",
+  "expected_revenue_gain"
+]

Changed10 schema fields changedJul 7, 2026

addedInput schema / properties / bucket

Added value: +{
+  "enum": [
+    "decaying",
+    "striking",
+    "rising",
+    "dormant",
+    "stable"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / bucket_summary

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "decaying": {
+      "additionalProperties": false,
+      "properties": {
+        "clicks": {
+          "type": "number"
+        },
+        "count": {
+          "type": "number"
+        },
+        "revenue_jpy": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "count",
+        "revenue_jpy",
+        "clicks"
+      ],
+      "type": "object"
+    },
+    "dormant": {
+      "$ref": "#/properties/bucket_summary/properties/decaying"
+    },
+    "rising": {
+      "$ref": "#/properties/bucket_summary/properties/decaying"
+    },
+    "stable": {
+      "$ref": "#/properties/bucket_summary/properties/decaying"
+    },
+    "striking": {
+      "$ref": "#/properties/bucket_summary/properties/decaying"
+    }
+  },
+  "required": [
+    "decaying",
+    "striking",
+    "rising",
+    "dormant",
+    "stable"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / criteria / properties / caveat_flags

Added value: +{
+  "additionalProperties": {
+    "type": "string"
+  },
+  "type": "object"
+}

changedOutput schema / properties / criteria / required

Previous value: -[
-  "provisional",
-  "comparison",
-  "significant_clicks_delta",
-  "position_worsening",
-  "striking_band",
-  "striking_clicks_below",
-  "dormant",
-  "landing_attribution"
-]New value: +[
+  "provisional",
+  "comparison",
+  "significant_clicks_delta",
+  "position_worsening",
+  "striking_band",
+  "striking_clicks_below",
+  "dormant",
+  "landing_attribution",
+  "caveat_flags"
+]

addedOutput schema / properties / pages / items / properties / caveats

Added value: +{
+  "items": {
+    "enum": [
+      "geo_winning_suspect",
+      "zero_click_suspect",
+      "ai_cited"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / pages / items / properties / confidence

Added value: +{
+  "enum": [
+    "high",
+    "low"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / pages / items / required

Previous value: -[
-  "page",
-  "action",
-  "is_new",
-  "cur_clicks",
-  "cur_impressions",
-  "cur_position",
-  "prev_clicks",
-  "prev_impressions",
-  "prev_position",
-  "main_query_position",
-  "striking_uplift_clicks",
-  "striking_query_count",
-  "striking_queries",
-  "sessions",
-  "engaged",
-  "revenue_jpy",
-  "ai_sessions",
-  "ai_revenue_jpy",
-  "ai_sources",
-  "clicks_threshold"
-]New value: +[
+  "page",
+  "action",
+  "confidence",
+  "caveats",
+  "is_new",
+  "cur_clicks",
+  "cur_impressions",
+  "cur_position",
+  "prev_clicks",
+  "prev_impressions",
+  "prev_position",
+  "main_query_position",
+  "striking_uplift_clicks",
+  "striking_query_count",
+  "striking_queries",
+  "sessions",
+  "engaged",
+  "revenue_jpy",
+  "ai_sessions",
+  "ai_revenue_jpy",
+  "ai_sources",
+  "clicks_threshold"
+]

addedOutput schema / properties / total_pages
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / truncated

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "guidance": {
+      "type": "string"
+    },
+    "omitted_pages": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "omitted_pages",
+    "guidance"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "site_id",
-  "period",
-  "window",
-  "basis",
-  "assumptions",
-  "limitations",
-  "criteria",
-  "pages"
-]New value: +[
+  "site_id",
+  "period",
+  "window",
+  "basis",
+  "assumptions",
+  "limitations",
+  "criteria",
+  "bucket_summary",
+  "total_pages",
+  "pages"
+]

AddedJul 3, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses data lag (1-2 days), window inclusivity semantics, inclusive date bounds, sorting rules within buckets, confidence caveats, truncation behavior, and non-obvious disclaimers (e.g., 'decaying' does not mean the page is failing overall). It also warns about 'geo_winning_suspect' and other caveats that require human verification.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with its core purpose and is exceptionally detailed, but it is very long. While nearly every sentence adds substantive guidance, the density approaches the limit of conciseness; a slight restructuring into bullet points would improve scannability without losing content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (five buckets, sorting nuances, caveats, response structure, period behavior), the description is impressively complete. It covers bucket semantics, sort criteria, expected metrics, window comparison rules, caveat flags, and notes return fields like bucket_summary and truncated. The output schema existence further reduces the need to document return types.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions are absent (0% coverage), so the description carries full burden. It compensates thoroughly: explains all five bucket values, period options ('7d', '30d', '90d' or raw day count 2-365), inclusive date interpretation, limit default/max values, and site_id optionality with OAuth. This is far beyond what the schema alone provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Return a content playbook for the site: every content page classified into ONE of five action buckets' – a specific verb and resource. It explicitly addresses scope ('cross-page action snapshot') and distinguishes from sibling tools by naming get_page_trend and get_ai_traffic as alternatives for different needs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states exactly when to use this tool (cross-page prioritization, telling the user which page to grow) and explicitly names alternatives for one-page time series and AI-citation gaps. It also provides clear exclusions, e.g., 'NOT CVR' and the instruction to cross-check landing metrics before calling a bucket a problem.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All RevenueScope: revenue-first analytics for your EC site tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?