Narrative SEO report for explaining crawl findings clearly.

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

How can the current evidence be explained clearly to a stakeholder?

• Structured reports already exist and need a readable decision summary.
• You need evidence, interpretation, and next actions in one format.

Command facts

Report id

narrative-report

Execution

Local process

Outputs

JSON and Markdown

Example parameters

site, days, recentDays, limit, includeBrand, changeLimit

Agent discovery

seo reports describe narrative-report --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 to discover what changed in Search Console rather than explain reports that already exist. Recommended report: Review SEO performance. Run the search performance overview first. It compares recent and earlier evidence, narrows movement by page, query, country, and device, and recommends focused follow-ups. Narrative report cannot create source evidence that was never collected.
• You need a factual explanation for why traffic or rankings changed. No automated report can prove the cause from a narrative. Review the underlying reports, known releases, tracking changes, demand, seasonality, and representative pages. Use the narrative only to communicate the conclusions that evidence supports.

Data sources and inputs

• Property diagnosis results. Provides supported movement, segments, decay, overlap, and opportunity evidence.
• Saved change and monitoring results. Adds measured changes, technical monitoring, skipped sections, and source caveats when available.

What this report checks

• Assembles structured findings in a stable order without generating explanations that are absent from the source reports.
• Carries source status, skipped work, failed measurements, warnings, and caveats into the narrative.

How it works

• Assembles structured outputs into a stable narrative order and preserves caveats rather than generating unsupported explanations.

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 structured evidence into a client-ready narrative. Agents and CI should inspect the live schema before their first run.

seo report-narrative --project example

seo reports describe narrative-report --json

seo reports run narrative-report --params '{"site":"sc-domain:example.com","days":90,"recentDays":7,"limit":10,"includeBrand":false,"changeLimit":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": "narrative-report"
}

{
  "id": "narrative-report",
  "params": {
    "site": "sc-domain:example.com",
    "days": 90,
    "recentDays": 7,
    "limit": 10,
    "includeBrand": false,
    "changeLimit": 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(
  'narrative-report',
  {
  "site": "sc-domain:example.com",
  "days": 90,
  "recentDays": 7,
  "limit": 10,
  "includeBrand": false,
  "changeLimit": 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 client-ready Markdown narrative with a headline, supported findings, priorities, and next actions.
• Structured sections and source details that let an agent trace every statement back to the underlying report evidence.
• Use the narrative as a reading layer. The structured reports remain the evidence contract for agents, exports, and verification.

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

• Clear writing cannot strengthen incomplete or partial source evidence.

What to do next

1. Run the focused report behind any unresolved headline.
2. Share the caveats with the actions so certainty is not overstated.

Related reports

• Review SEO performance. See where clicks and impressions changed, which pages or queries account for the movement, and what to inspect next.
• Monthly SEO report. Turn one calendar month of finalised search data into a clear report with changes, opportunities, gaps, and follow-up work.
• 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 Reporting.