Understand a technical SEO issue and how to fix it

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

What does this crawler rule mean and how should it be checked?

• A crawl result contains a rule id that needs explanation before action.
• An agent needs the canonical guidance for a known rule.

Command facts

Report id

explain-crawl-issue

Execution

Local process

Outputs

JSON and Markdown

Example parameters

ruleId

Agent discovery

seo reports describe explain-crawl-issue --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 understand the rule and need the real URLs, evidence, and first-party metrics behind that finding in a saved crawl. Recommended report: Find URLs affected by a crawl issue. Run affected URLs with the rule id. It turns the catalog explanation into a limited list of actual pages and keeps the selection count and truncation visible.
• You need to know whether the observed condition is intentional for a particular page or template. No automated rule explanation can know site intent. Review the page purpose, template rules, canonical plan, robots policy, and release context with the owner. This report can explain the condition and verification method, but it cannot label an intentional control as a defect.

Data sources and inputs

• Crawler rule id. Selects one maintained technical rule from the installed SEO package.
• Versioned rule guidance. Provides the rule meaning, rationale, fix, impact context, and verification guidance.

What this report checks

• Resolves the exact rule id against the current local crawler catalog.
• Returns maintained guidance and fails clearly when the id is unknown.

How it works

• Looks up one exact rule id and returns its maintained guidance without rerunning a crawl.

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

Understand one crawler rule and how to verify the fix. Agents and CI should inspect the live schema before their first run.

seo explain --rule missing_title

seo reports describe explain-crawl-issue --json

seo reports run explain-crawl-issue --params '{"ruleId":"missing_title"}' --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": "explain-crawl-issue"
}

{
  "id": "explain-crawl-issue",
  "params": {
    "ruleId": "missing_title"
  }
}

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(
  'explain-crawl-issue',
  {
  "ruleId": "missing_title"
},
)

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 plain-English explanation of what the crawler observed and why the rule may matter.
• Practical fix, impact, and verification guidance that can be paired with affected URLs from a real crawl.
• Use the explanation to review the affected page in context. Severity helps triage, but page purpose and intent decide whether a change is appropriate.

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

• Rule guidance cannot replace the URL evidence or turn a heuristic into a search-engine requirement.

What to do next

1. Fetch the affected URL list for this rule.
2. Audit representative pages and verify the change with a fresh crawl.

Related reports

• 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.
• Audit one page. Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.
• Browse crawler rules. See every technical check built into the local crawler and find the right rule for a focused follow-up.

Browse all reports in Crawling and technical checks.