Give an AI agent reliable SEO evidence

An agent is useful here when it can choose a narrow report, inspect the data status, and explain the evidence in plain language. It is much less useful when it receives thousands of crawl rows and starts inventing priorities.

Start the agent with a specific job

Good requests name the site and the decision you need to make:

• “Find page-one queries with weak CTR evidence and show the pages to inspect.”
• “Compare the latest two crawls and list high-severity regressions introduced in the new one.”
• “Audit this pricing page before I change its canonical and internal links.”
• “Check whether this traffic decline is present in a complete Search Console window.”

“Do all my SEO” gives the agent no useful stopping point. Start with seo report when the request really is broad, then let its recommendations narrow the next call.

Give the agent access that fits the workflow

Path	Best for
CLI with --json	Scripts, CI, and agents that can run shell commands
Local stdio MCP	Interactive agents that select and call tools
The seo skill	Teaching an agent when a report helps and how to act on it

All three paths call the same report logic. The MCP setup guide connects Codex, Claude Code, Claude Desktop, and Cursor. The skill guide explains global and project installation. For the best agent results, install the runtime or MCP tools and the skill: one runs the reports, the other teaches the agent how to use them.

Use explicit JSON from the CLI

seo report --project example --json
seo crawl https://example.com --json --output crawl.json
seo reports describe quick-wins --json
seo reports run quick-wins --params '{"site":"sc-domain:example.com"}' --json

JSON mode never prompts. An unattended run must pass its project, property, URL, output path, and other required inputs explicitly.

seo report --json returns a compact summary, action queue, and bounded crawl evidence. Add --full only when the agent needs every report section.

Use seo reports describe <id> --json before constructing params. The schema is the current contract. A command copied from an old prompt is not.

Keep MCP discovery compact

The local MCP server exposes three tools:

1. seo_list_reports returns compact report ids and descriptions.
2. seo_describe_report returns the selected report’s parameter schema.
3. seo_run_report validates the parameters and runs the report.

An agent should list by category when it can, describe one report, then run it. This keeps dozens of unused schemas out of the first tool selection.

For example, an agent investigating a single URL can discover audit-page, load that schema, and run it with the URL. It should not request a site crawl and a search performance overview as a warm-up.

Read status before recommendations

Ask the agent to check these fields and concepts before it reaches a verdict:

• the analysis date and source date windows;
• complete, partial, capped, filtered, missing, and unavailable states;
• warnings, skipped sections, failed subqueries, and retained row limits;
• the observed page or provider evidence behind each finding;
• whether the action is a rule, a heuristic, or a verification step.

Search Console can omit anonymized queries. GA4 can process recent data later or withhold rows. A crawl can stop at its page cap. Those states are reasons to bound a conclusion, not reasons to fill the gap with a guess. The Google data guide covers the provider-specific limits.

Ask for a small follow-up

The first result should identify the affected set. The next call should inspect that set rather than rerunning everything.

A sensible sequence looks like this:

1. Run quick-wins for the retained opportunity list.
2. Pick one query and page using the evidence in the result.
3. Run audit-page for current on-page and technical evidence.
4. Check the live result and intended page purpose before proposing a change.
5. Save the baseline needed to measure or verify that change.

This is slower than a made-up answer and much faster than fixing the wrong page.

Treat agent output as analysis, not provider truth

An agent can summarize a canonical conflict, index status snapshot, estimated title width, or traffic change. It cannot prove ranking causation, future clicks, index inclusion, or an AI citation unless the source returned that exact evidence.

Keep the final answer traceable to URLs, queries, dates, rule IDs, and provider states. The report accuracy guide explains the result contract, while AI search evidence covers the claims those reports deliberately avoid.

Keep private inputs out of public prompts

Reports run on your machine and their files stay local, but the agent client may send tool results to its model provider. Review that client’s data controls before sharing private URLs or analytics. Keep OAuth tokens, account identifiers, and raw client exports out of prompts and public issues.