Technical SEO issues ranked by evidence, reach, and effort.

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 supported technical findings should be reviewed first?

• A broad crawl is too large to act on directly.
• You need a limited queue by category or severity.

Command facts

Report id

top-fixes

Execution

Local process

Outputs

JSON and Markdown

Example parameters

reportId, category, limit

Agent discovery

seo reports describe top-fixes --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 need every URL affected by one known crawl rule rather than a ranked list of issue groups. Recommended report: Find URLs affected by a crawl issue. Run affected URLs with the saved crawl and rule id. It returns the matching URL inventory and issue evidence for that rule, which is the right input for estimating scope and planning a template-level fix.
• You need to confirm that a release fixed the selected technical issue. Recommended report: Monitor crawl changes. Run a comparable crawl diff after the release. It separates new, resolved, and persistent findings while keeping fetch and scope changes visible. A priority score cannot verify implementation.

Data sources and inputs

• Saved or fresh crawl findings. Provides issue instances, affected pages, rule severity, and technical evidence.
• Joined Search Console and GA4 page metrics. Adds available search visibility, sessions, users, and conversions for affected pages.

What this report checks

• Groups eligible findings by rule and calculates a repeatable score from severity, affected count, available first-party value, and estimated effort.
• Attaches the exact score factors, rule explanation, fix guidance, and a repeatable verification command.

How it works

• Ranks eligible issue groups consistently and returns a compact limit without discarding source references.

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

Turn a crawl into a short technical implementation queue. Agents and CI should inspect the live schema before their first run.

seo crawl-queue https://example.com

seo reports describe top-fixes --json

seo reports run top-fixes --params '{"reportId":"crawl_example_20260710","category":"metadata","limit":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": "top-fixes"
}

{
  "id": "top-fixes",
  "params": {
    "reportId": "crawl_example_20260710",
    "category": "metadata",
    "limit": 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(
  'top-fixes',
  {
  "reportId": "crawl_example_20260710",
  "category": "metadata",
  "limit": 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 limited technical fix queue with score, severity, affected count, sample URLs, effort, and first-party evidence.
• Plain-language reasons for the order plus how to fix and verify each selected rule.
• Validate the first item on representative pages. A lower-severity repeated template issue may deserve attention before one isolated high-severity URL.

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

• The queue reflects the crawl scope and rule priorities, not business value or guaranteed search impact.

What to do next

1. Explain the selected rule.
2. Open its affected URLs and verify a fix with another crawl.

Related reports

• Understand a crawler issue. Turn one crawler rule id into plain-English meaning, practical fixes, impact context, and a repeatable verification step.
• Find URLs affected by a crawl issue. Open the exact URLs behind a crawl finding and turn a summary count into a limited review or fix list.
• Compare two saved crawls. See which pages and technical issues appeared, disappeared, or changed between two saved crawl snapshots.

Browse all reports in Crawling and technical checks.