CTR optimization report for search snippets losing clicks.

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 visible query rows may warrant a search-result presentation review?

• You need a limited list of high-impression rows for title and snippet investigation.
• Brand filtering and the selected impression floor match the task.

Command facts

Report id

ctr-underperformers

Execution

Local process

Outputs

JSON and Markdown

Example parameters

site, minImpressions, includeBrand

Agent discovery

seo reports describe ctr-underperformers --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.

• The main opportunity is queries averaging positions 11 to 20 rather than weak CTR at an existing position. Recommended report: Find pages close to page one. Run second-page opportunities. It groups the returned page and query evidence near page one without treating the average position as a fixed rank.
• You need to know whether changing a title or snippet actually improved clicks or CTR. Recommended report: Measure an SEO change. Record and measure the change across matched Search Console windows. It adds before-and-after evidence, but it still cannot isolate the edit from demand, ranking, SERP, or seasonality changes.

Data sources and inputs

• Returned Search Console query rows. Provides impressions, clicks, CTR, average position, dates, and property scope.
• Documented CTR expectation. Defines the position-aware benchmark and minimum evidence used to create the review set.

What this report checks

• Filters eligible high-impression queries and compares observed CTR with the documented expectation.
• Ranks the shortfall consistently while keeping position, returned-row coverage, thresholds, and limits visible.

How it works

• Filters by evidence and compares each eligible row with an explicit benchmark while preserving source limits.

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

Find high-impression queries with weaker CTR evidence. Agents and CI should inspect the live schema before their first run.

seo ctr-underperformers --project example

seo reports describe ctr-underperformers --json

seo reports run ctr-underperformers --params '{"site":"sc-domain:example.com","minImpressions":250,"includeBrand":false}' --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": "ctr-underperformers"
}

{
  "id": "ctr-underperformers",
  "params": {
    "site": "sc-domain:example.com",
    "minImpressions": 250,
    "includeBrand": false
  }
}

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(
  'ctr-underperformers',
  {
  "site": "sc-domain:example.com",
  "minImpressions": 250,
  "includeBrand": false
},
)

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 query review list with observed CTR, expected CTR, position, impressions, clicks, and estimated shortfall.
• Methodology and caveats that prevent the expectation or shortfall being read as a requirement or traffic promise.
• A gap is a review signal. Inspect search intent, result features, title rendering, snippet text, and device mix before proposing a test.

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

• CTR varies by query and search appearance. The report cannot see every SERP context that shaped the metric.

What to do next

1. Use content optimization for a supported page-level brief.
2. Record and measure any title or snippet change instead of forecasting clicks.

Related reports

• 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.
• Find SEO quick wins. Find page-one rankings with weak CTR where title or snippet work may earn more clicks.
• 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 Search opportunities.