RevenueScope: revenue-first analytics for your EC site

Top priority insights

get_priority_insights

Read-only

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).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`period`	No		30d
`site_id`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`basis`	Yes
`period`	Yes
`site_id`	Yes
`insights`	Yes
`assumptions`	Yes
`limitations`	Yes
`data_freshness`	Yes
`previous_period`	Yes
`rules_evaluated`	Yes
`presentation_hints`	Yes
`period_boundary_definitions`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedSep 4, 2026

addedOutput schema / properties / data_freshness

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "bot_classification_delay_definitions": {
+      "additionalProperties": false,
+      "properties": {
+        "burst_cluster_fallback": {
+          "type": "string"
+        },
+        "burst_cluster_primary": {
+          "type": "string"
+        },
+        "single_page_zero_dwell": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "burst_cluster_primary",
+        "burst_cluster_fallback",
+        "single_page_zero_dwell"
+      ],
+      "type": "object"
+    },
+    "bot_classification_delay_minutes_max_by_rule": {
+      "additionalProperties": false,
+      "properties": {
+        "burst_cluster_fallback": {
+          "const": 480,
+          "type": "number"
+        },
+        "burst_cluster_primary": {
+          "const": 20,
+          "type": "number"
+        },
+        "single_page_zero_dwell": {
+          "const": 480,
+          "type": "number"
+        }
+      },
+      "required": [
+        "burst_cluster_primary",
+        "burst_cluster_fallback",
+        "single_page_zero_dwell"
+      ],
+      "type": "object"
+    },
+    "delay_bounds_assume_scheduled_jobs_operational": {
+      "const": true,
+      "type": "boolean"
+    },
+    "generated_at": {
+      "format": "date-time",
+      "type": "string"
+    },
+    "may_change_because": {
+      "items": {
+        "enum": [
+          "live_ingestion",
+          "open_window",
+          "moving_window",
+          "delayed_bot_classification"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "provisional": {
+      "const": true,
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "generated_at",
+    "provisional",
+    "may_change_because",
+    "bot_classification_delay_minutes_max_by_rule",
+    "bot_classification_delay_definitions",
+    "delay_bounds_assume_scheduled_jobs_operational"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / insights / items / properties / source_boundaries

Added value: +{
+  "items": {
+    "$ref": "#/properties/period/properties/source_boundaries/items"
+  },
+  "type": "array"
+}

changedOutput schema / properties / insights / items / required

Previous value: -[
-  "id",
-  "severity",
-  "title",
-  "detail",
-  "metric",
-  "value",
-  "change",
-  "recommended_action",
-  "impact_score",
-  "rank"
-]New value: +[
+  "id",
+  "severity",
+  "title",
+  "detail",
+  "metric",
+  "value",
+  "change",
+  "recommended_action",
+  "impact_score",
+  "rank",
+  "source_boundaries"
+]

addedOutput schema / properties / period / properties / calendar_dates_touched
```
Added value: +{
+  "minimum": 0,
+  "type": "integer"
+}
```
addedOutput schema / properties / period / properties / duration_hours
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / period / properties / reference_bounds

Added value: +{
+  "const": "start_inclusive_end_exclusive",
+  "type": "string"
+}

addedOutput schema / properties / period / properties / reference_end_at
```
Added value: +{
+  "format": "date-time",
+  "type": "string"
+}
```
addedOutput schema / properties / period / properties / reference_start_at
```
Added value: +{
+  "format": "date-time",
+  "type": "string"
+}
```

addedOutput schema / properties / period / properties / source_alignment

Added value: +{
+  "enum": [
+    "exact",
+    "mixed"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / period / properties / source_boundaries

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "applies_to": {
+        "items": {
+          "type": "string"
+        },
+        "minItems": 1,
+        "type": "array"
+      },
+      "boundary": {
+        "enum": [
+          "reference_timestamp_window",
+          "database_statement_time_window",
+          "jst_calendar_dates_from_reference_start",
+          "jst_calendar_dates_from_database_window_start",
+          "jst_calendar_dates_inclusive",
+          "account_registry_not_period_scoped",
+          "derived_previous_daily_window",
+          "derived_from_current_and_previous",
+          "defined_per_output_item"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "applies_to",
+      "boundary"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / period / properties / timezone

Added value: +{
+  "const": "Asia/Tokyo",
+  "type": "string"
+}

addedOutput schema / properties / period / properties / window_type

Added value: +{
+  "enum": [
+    "rolling",
+    "calendar_to_date",
+    "comparison"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / period / required

Previous value: -[
-  "start",
-  "end",
-  "days"
-]New value: +[
+  "start",
+  "end",
+  "days",
+  "reference_start_at",
+  "reference_end_at",
+  "window_type",
+  "reference_bounds",
+  "timezone",
+  "duration_hours",
+  "calendar_dates_touched",
+  "source_alignment",
+  "source_boundaries"
+]

addedOutput schema / properties / period_boundary_definitions

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "account_registry_not_period_scoped": {
+      "type": "string"
+    },
+    "database_statement_time_window": {
+      "type": "string"
+    },
+    "defined_per_output_item": {
+      "type": "string"
+    },
+    "derived_from_current_and_previous": {
+      "type": "string"
+    },
+    "derived_previous_daily_window": {
+      "type": "string"
+    },
+    "jst_calendar_dates_from_database_window_start": {
+      "type": "string"
+    },
+    "jst_calendar_dates_from_reference_start": {
+      "type": "string"
+    },
+    "jst_calendar_dates_inclusive": {
+      "type": "string"
+    },
+    "path_syntax": {
+      "const": "dot_path_with_array_wildcard",
+      "type": "string"
+    },
+    "reference_timestamp_window": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "path_syntax",
+    "reference_timestamp_window",
+    "database_statement_time_window",
+    "jst_calendar_dates_from_reference_start",
+    "jst_calendar_dates_from_database_window_start",
+    "jst_calendar_dates_inclusive",
+    "account_registry_not_period_scoped",
+    "derived_previous_daily_window",
+    "derived_from_current_and_previous",
+    "defined_per_output_item"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / previous_period

Added value: +{
+  "$ref": "#/properties/period"
+}

changedOutput schema / required

Previous value: -[
-  "site_id",
-  "period",
-  "basis",
-  "assumptions",
-  "limitations",
-  "rules_evaluated",
-  "insights",
-  "presentation_hints"
-]New value: +[
+  "site_id",
+  "period",
+  "previous_period",
+  "data_freshness",
+  "period_boundary_definitions",
+  "basis",
+  "assumptions",
+  "limitations",
+  "rules_evaluated",
+  "insights",
+  "presentation_hints"
+]

Changed2 schema fields changedSep 4, 2026

addedOutput schema / properties / presentation_hints

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "avoid_long_prose": {
+      "const": true,
+      "type": "boolean"
+    },
+    "prefer_compact_visual_summary": {
+      "const": true,
+      "type": "boolean"
+    },
+    "primary_metric": {
+      "type": "string"
+    },
+    "recommended_followup_tools": {
+      "items": {
+        "enum": [
+          "get_breakdown",
+          "get_priority_insights"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "recommended_sections": {
+      "items": {
+        "enum": [
+          "kpi_summary",
+          "trend",
+          "ad_spend_context",
+          "breakdown",
+          "priority_insights",
+          "recommended_actions"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "response_type": {
+      "enum": [
+        "analytics_summary",
+        "analytics_breakdown",
+        "priority_insights"
+      ],
+      "type": "string"
+    },
+    "show_breakdown": {
+      "type": "boolean"
+    },
+    "show_period_comparison": {
+      "type": "boolean"
+    },
+    "show_priority_insights": {
+      "type": "boolean"
+    },
+    "show_trend": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "response_type",
+    "primary_metric",
+    "show_period_comparison",
+    "show_trend",
+    "show_breakdown",
+    "show_priority_insights",
+    "prefer_compact_visual_summary",
+    "avoid_long_prose",
+    "recommended_followup_tools",
+    "recommended_sections"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "site_id",
-  "period",
-  "basis",
-  "assumptions",
-  "limitations",
-  "rules_evaluated",
-  "insights"
-]New value: +[
+  "site_id",
+  "period",
+  "basis",
+  "assumptions",
+  "limitations",
+  "rules_evaluated",
+  "insights",
+  "presentation_hints"
+]

Changed1 schema field changedJun 21, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "assumptions": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "basis": {
+      "type": "string"
+    },
+    "insights": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "change": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "detail": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          },
+          "impact_score": {
+            "type": "number"
+          },
+          "metric": {
+            "type": "string"
+          },
+          "rank": {
+            "type": "number"
+          },
+          "recommended_action": {
+            "type": "string"
+          },
+          "severity": {
+            "enum": [
+              "risk",
+              "opportunity",
+              "watch"
+            ],
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "value": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "id",
+          "severity",
+          "title",
+          "detail",
+          "metric",
+          "value",
+          "change",
+          "recommended_action",
+          "impact_score",
+          "rank"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "limitations": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "period": {
+      "additionalProperties": false,
+      "properties": {
+        "days": {
+          "type": "number"
+        },
+        "end": {
+          "type": "string"
+        },
+        "start": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "start",
+        "end",
+        "days"
+      ],
+      "type": "object"
+    },
+    "rules_evaluated": {
+      "type": "number"
+    },
+    "site_id": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "site_id",
+    "period",
+    "basis",
+    "assumptions",
+    "limitations",
+    "rules_evaluated",
+    "insights"
+  ],
+  "type": "object"
+}

AddedJun 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, and the description adds substantial behavioral detail beyond that: the judgment is deterministic and fixed in code, it returns fewer than 3 when fewer rules fire with no padding, and insights carry source_boundaries because signal windows can differ. There is no contradiction with the annotations.

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

Conciseness5/5

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

Though long, every sentence earns its place. The core purpose is front-loaded, sibling differentiation comes immediately after, and the remaining sentences compactly cover output semantics, period behavior, and source windows without fluff.

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

Completeness4/5

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

For a complex insights tool, the description is nearly complete: it covers return shape, severity, recommended action, no-padding behavior, period semantics, and source boundaries. The main gap is the exact handling of site_id across authentication modes; otherwise, an agent has enough to correctly select and invoke the tool.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does: period presets ('today'/'7d'/'30d'/'90d'), raw day count 1-365, default 30 days, and site_id optionality under OAuth. It loses a point for a slight ambiguity around whether site_id is required when not OAuth-authenticated, and for mentioning previous_period without clarifying it is not a directly settable input.

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 a specific verb and resource: 'Return the top 3 prioritized, pre-computed DIAGNOSES... ranked by revenue impact.' It also explicitly contrasts with get_summary / get_breakdown, which helps an agent distinguish this from its main data-returning siblings.

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?

It frames the tool as 'what should I act on this week', directly stating the decision-oriented use case. It also gives an explicit when-not: 'Unlike get_summary / get_breakdown (which return data)', this applies a rule engine and returns ranked findings, so the agent can route to the right sibling.

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?