Content optimization report built from Search Console and page evidence.

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 evidence-backed improvements should this existing page be reviewed for?

• One page has Search Console visibility and needs a careful content or snippet review.
• You want technical conflicts separated from content ideas.

Command facts

Report id

content-optimization

Execution

Local process

Outputs

JSON and Markdown

Example parameters

site, url, days, limit, minImpressions, verifyContent

Agent discovery

seo reports describe content-optimization --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 need a technical check of one live URL before changing its metadata, canonical, directives, links, or schema. Recommended report: Audit one page. Run the page audit. It focuses on observed live-page evidence and does not build a content brief from query demand.
• You need to decide whether to rewrite the current page, create a new page, merge it with another page, or leave it alone. No automated report can make that editorial and information-architecture decision. Review search intent, the live SERP, conversions, backlinks, business goals, and overlapping pages. This report can still provide the page evidence and returned queries used in that decision.

Data sources and inputs

• Exact-page Search Console queries. Provides the returned demand, clicks, impressions, CTR, and position associated with the URL.
• Live page content and technical evidence. Provides current metadata, headings, text, links, canonical, and indexability observations.

What this report checks

• Ranks eligible query evidence and compares it with the fetched page within explicit limits.
• Separates technical conflicts, observed coverage, and heuristic content review ideas before building the brief.

How it works

• Classifies returned query wording with broad heuristics, verifies the live page when requested, and turns supported gaps into limited review actions.

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 brief from one page and its Search Console queries. Agents and CI should inspect the live schema before their first run.

seo content optimize --url https://example.com/page --project example

seo reports describe content-optimization --json

seo reports run content-optimization --params '{"site":"sc-domain:example.com","url":"https://example.com/guides/seo","days":90,"limit":20,"minImpressions":50,"verifyContent":true}' --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": "content-optimization"
}

{
  "id": "content-optimization",
  "params": {
    "site": "sc-domain:example.com",
    "url": "https://example.com/guides/seo",
    "days": 90,
    "limit": 20,
    "minImpressions": 50,
    "verifyContent": true
  }
}

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(
  'content-optimization',
  {
  "site": "sc-domain:example.com",
  "url": "https://example.com/guides/seo",
  "days": 90,
  "limit": 20,
  "minImpressions": 50,
  "verifyContent": true
},
)

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 edit brief with source queries, page observations, technical blockers, and supported review actions.
• Explicit heuristic labels, source completeness, failed verification, caveats, and a measurement follow-up.
• Resolve contradictory technical evidence first. Treat content gaps, intent labels, scores, and estimated lift as review heuristics rather than mandates or forecasts.

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

• Search queries do not prove why a page ranks, and a fetch may differ from the version Google indexed or a user saw.

What to do next

1. Make one clear, user-serving change and record it.
2. Measure the result after a complete comparison window.

Related reports

• Audit one page. Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.
• Find opportunities for one page. See which returned search queries are already associated with one URL and what deserves a closer look on the live page.
• 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
• Google JavaScript SEO guidance
• Google canonical URL guidance

Browse all reports in AI search evidence.