SEO priority report for ranking the next fixes to make.

Run this report from the CLI, an MCP client, or application code. Every surface uses the same report definition and returns the same evidence. JSON is the source of truth; Markdown makes it readable without hiding dates, limits, warnings, or skipped work.

What this report helps you decide

Which existing pages deserve refresh or investigation attention first?

• A content team needs one queue assembled from several first-party evidence types.
• You can inspect the live pages before deciding to edit.

Command facts

Report id

refresh-priorities

Execution

Local process

Outputs

JSON and Markdown

Example parameters

site, days, recentDays, limit, includeBrand, verifyContent, verifyLimit

Agent discovery

seo reports describe refresh-priorities --json

Interactive prompts

Human CLI commands only

When this report is not the right tool

These cases need a different report, more evidence, or a human decision. Do not force this report to answer a question its data cannot support.

• You only want technical crawl fixes and do not want content or Search Console opportunities mixed into the queue. Recommended report: Fix the most important technical SEO issues. Run top fixes against a saved crawl. It ranks crawl issue groups by rule evidence and affected scope, with sample URLs and verification guidance still attached.
• You need an exact content brief for one page already selected for review. Recommended report: Build a content optimization brief. Run content optimization for that URL. It adds the live page structure and returned query evidence needed for a focused brief. Refresh priorities orders candidates but cannot decide that a rewrite is required.

Data sources and inputs

• Search Console diagnosis and opportunity reports. Provides decay, position, CTR, query overlap, and property movement evidence with shared source details.
• Optional live-page verification. Checks a limited number of candidates before the workflow recommends deeper investigation.

What this report checks

• Collects eligible quick wins, second-page opportunities, decaying pages, cannibalisation rows, and crawl findings.
• Normalises shared evidence without counting the same underlying rows as independent proof.
• Ranks a limited queue consistently and keeps the source report, verification, caveats, and score factors attached.

How it works

• Normalizes supported candidates, preserves their source report and caveats, then ranks a limited queue consistently.

The JSON result keeps dates, thresholds, limits, skipped work, and source completeness beside the finding. Missing, partial, capped, filtered, and complete data remain different states.

Run the report from the CLI

Build a limited review queue from supported search signals. Agents and CI should inspect the live schema before their first run.

seo refresh-priorities --project example

seo reports describe refresh-priorities --json

seo reports run refresh-priorities --params '{"site":"sc-domain:example.com","days":90,"recentDays":7,"limit":10,"includeBrand":false,"verifyContent":true,"verifyLimit":5}' --json

Project profiles can fill supported property and analytics inputs for the human-facing commands. The catalog form shown here is explicit by design, so agents and CI jobs do not prompt or guess.

How an MCP agent should use it

Call seo_describe_report first so the agent sees when this report is useful and gets the current input schema. Then callseo_run_report with the validated parameters. Read the status, warnings, source limits, and skipped sections before acting on a finding.

{
  "id": "refresh-priorities"
}

{
  "id": "refresh-priorities",
  "params": {
    "site": "sc-domain:example.com",
    "days": 90,
    "recentDays": 7,
    "limit": 10,
    "includeBrand": false,
    "verifyContent": true,
    "verifyLimit": 5
  }
}

Use a follow-up report returned by the result instead of guessing the next tool. The local MCP server and CLI use the same report definition and evidence. Their outer transport envelopes differ.

Use the report in a TypeScript app

Install seo as a project dependency, then call the same report catalog used by the CLI and MCP. executeReportrejects an unknown report id or invalid parameters. Provider and runtime failures come back as structured results withisError set.

npm install seo

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'refresh-priorities',
  {
  "site": "sc-domain:example.com",
  "days": 90,
  "recentDays": 7,
  "limit": 10,
  "includeBrand": false,
  "verifyContent": true,
  "verifyLimit": 5
},
)

console.log(result)

The TypeScript library guide also covers direct core functions, schema discovery, and the difference betweenexecuteReport and runReport.

What comes back and how to read it

• A ranked priority list with the evidence, source report, confidence, and recommended investigation for each item.
• Follow-up commands for deeper page, crawl, or search opportunity evidence.
• Caveats that stop priority scores becoming traffic forecasts or automatic rewrite orders.
• Open the source evidence for each item. A page appearing in several reports can deserve review, but the signals may share the same underlying rows.

Start with dataStatus, source details, warnings, and caveats. Then inspect the observed evidence before derived findings or suggested actions.

What this report cannot tell you

• Combined signals are prioritisation evidence, not additive traffic forecasts or proof that a rewrite is needed.

What to do next

1. Audit the highest-supported page.
2. Record and measure any material change.

Related reports

• Audit one page. Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.
• Build a content optimization brief. Create a focused brief for one existing page from its own search queries and the content observed on the live URL.
• Measure an SEO change. Compare equal, finalised search windows around a recorded change and see what moved without claiming the change caused it.

Sources behind the guidance

These primary sources define the provider data or search controls used in the interpretation above.

• Search Console Search Analytics API guidance

Browse all reports in Multi-report workflows.