SEO workflows for AI agents

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.

New to the idea? How an SEO agent works walks the whole find, inspect, propose, verify, and measure loop with interactive examples before this page gets into specifics.

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.”
• “Find recurring search competitors for these product queries, then leave unknown site types unclassified.”
• “Compare these two competitors with our returned Search Console themes and existing provider ranks.”
• “Compare our indexed AI mentions with these three competitors in one market, then show the cited domains and repeated questions worth checking.”

“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

All three paths call the same report logic. The MCP setup guide works with any agent that supports local stdio MCP. It includes guided setup for 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 limited 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.

Ask the agent to design the HTML report

When the deliverable is for a client or stakeholder, the agent can turn the structured result into its own standalone HTML page. It should design for the actual findings and audience instead of copying the built-in layout.

The visual treatment is flexible. The evidence is not. Require the page to keep provider labels, reporting dates, data status, caveats, skipped sections, and verification steps visible. Missing or partial data must not become zero, and the agent must not invent forecasts, causes, scores, or conclusions.

The HTML report guide includes the JSON command, a complete agent request, and the built-in renderer for cases where a fixed layout is more useful.

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 returned 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. Google Analytics 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.

Research providers add a different kind of evidence. Keyword volume, difficulty, traffic, intent, visibility, domain footprint and ranking history are estimates. Keep them separate from Search Console measurements, current crawl evidence and live result snapshots. Read provider request filters, market, observation time, cache state, cost and coverage before using the finding. The research provider guide covers those boundaries and local spend controls.

Provider-indexed AI mention records need another boundary. They can show mentions, cited domains and question samples returned by the provider. They do not prove that the same answer appears now. Search Console overlap adds useful Search Console context, but it is still simple word matching across the rows returned.

Local search evidence needs the same separation. Query wording can show an explicit place, nearby phrase or postal code, but it does not establish the searcher’s physical location. Search Console position is averaged across impressions. A live result snapshot is exact only for its recorded query, canonical location, device and time. An observed local pack does not show that a particular business listing appeared unless the report retains that listing row. A returned row still does not prove ownership, complete Maps coverage or Google Business Profile performance. Recurring organic domains are search competitors for the observed queries until their business type and relevance are checked. Optional Analytics geography is joined only by an exact returned landing-page path. It can add location context for measured sessions, but it cannot assign a location to a Search Console query.

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 returned 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.

For competitor and programmatic research, use a separate narrow sequence:

1. Run serp-competitors for an explicit keyword set.
2. Classify unknown domains and remove publishers, directories or communities that do not match the decision.
3. Run competitor-keyword-gap with no more than three relevant domains.
4. Review Search Console overlap and existing provider ranks before opening a gap candidate.
5. Check current results, representative pages and the returned data-source brief before proposing a new programmatic template.

If no provider API is connected, describe the selected report and check its researchFiles schema. One to four local ranked-keyword exports from the same provider can feed ranked-keywords, ranking-pages, serp-competitors, competitor-keyword-gap and cannibalisation. Use the optional columns map when source headings do not match the recognised export fields. Never guess an ambiguous mapping. Read every evidence.imports entry first. The export date, file hash, fields, column mapping, filtered historical rows, rejected rows and caps define what the file can support. An absent imported row is not a zero.

For AI mention research, keep the surface and market fixed:

1. Describe ai-mention-research and use its current input schema.
2. Run one named target against no more than five relevant competitors.
3. Check coverage, cache state, cost, task ids, warnings and observation dates before comparing mention counts.
4. Read cited sources, question samples and optional Search Console overlap as separate evidence.
5. Describe and run ai-prompt-observations for only the fixed prompts where a current answer would change the decision.
6. Read coverage, cache state, requested and effective model, citations, exact returned cost, and comparison status before describing a mention or change.

The requested model is the exact model passed to the report. The effective model is the model the provider says actually ran. Treat a mismatch as a new baseline, not a measured change.

Do not choose an implicit latest model. Use an exact name from the provider’s free current catalog. If a saved name is stale, the preflight error lists current choices and confirms that no paid request started. Cached observations, changed models, partial answers, and truncated answers do not support a before-and-after claim.

For referring-link research, run link-evidence with one source. With DataForSEO, read provider summary and cost evidence before the representative rows. When the target is a site you own, add its Search Console property and a matching saved crawl. Use the combined evidence to shortlist linked targets with observed technical problems, then verify both the live target and the referring 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.