Research one page and write an SEO optimization brief

Create an English on-page optimization brief for TARGET_URL. This is research only: do not publish or modify the site.

The page's canonical intent is: CANONICAL_INTENT.

Use these first-party Google Search Console facts exactly as supplied and do not invent any others: GSC_FACTS_OR_NONE.

Read the live page. Load the built-in SEO research tools with tool_search, then make no more than these three SEO calls:
1. seo_ranked_keywords for the exact URL, limit 20.
2. seo_serp_results for PRIMARY_QUERY, max_results 5.
3. seo_keyword_metrics for [PRIMARY_QUERY, SUPPORTING_QUERY], with include_monthly_trends false.

Do not call keyword expansion, backlinks, domain overview, general web search, or any other research tool. If one of the three calls fails, record that once and continue without retrying it.

Keep provider estimates separate from the supplied Search Console facts. Do not treat search volume, difficulty, CPC, rank, or traffic estimates as Google Search Console data. If a provider omits a query, report it as not returned, not zero.

The brief must include:
- the canonical intent and evidence limits;
- current-page strengths and gaps;
- one primary query and only distinct supporting intents;
- a title under 60 characters, meta description under 155 characters, and one H1;
- a question-shaped H2 outline;
- three common questions answered only from verified page or product behavior;
- descriptive internal links to existing pages on the site;
- evidence-backed edits separated from hypotheses to measure.

Do not recommend keyword stuffing, llms.txt, extra schema, or a duplicate landing page as growth tactics. Save the complete brief to seo/PAGE_BRIEF.md and summarize the result in the conversation.

Why does the prompt limit the research?

Page optimization needs a focused evidence set. An exact-page ranking read tells you what the URL already ranks for. One live SERP shows the current result types and competitors for the primary query. Metrics for two named queries add provider estimates without opening a 150-row expansion.

The limit also makes a failed call easy to spot. If one provider call fails, the brief records the missing source and continues. It does not repeat the entire research phase or hide the gap behind another provider's number.

Run broader domain research, backlink analysis, and keyword expansion as separate jobs. They answer different questions and can return much larger results. Give each one a new session and its own brief rather than adding it to this page-level pass.

Which source answers which question?

Source	What it can support	What it cannot support
Live page	Current title, headings, claims, links, and visible answers	Search demand or Google performance
Google Search Console	First-party impressions, clicks, and average position for the verified property	Queries Google anonymized or filtered out
Ranked-keyword tool	A provider's estimated ranking rows for the exact URL	A complete copy of GSC or proof that an omitted query has zero demand
Keyword-metrics tool	Estimated volume, difficulty, CPC, and intent for named queries	Your page's clicks, conversions, or future rank
Live SERP tool	The result types and pages visible for one query at that moment	Stable rankings across locations, devices, or future dates

A useful brief can say “GSC did not expose enough query data to diagnose the snippet” and still use a provider estimate to frame a hypothesis.

What did the real run prove?

We ran the prompt on 30 August 2026 against the existing AI agent hosting page. The supplied GSC window was 30 July through 26 August: 127 impressions, 0 clicks, and average position 11.6. Only five disclosed impressions came from the category queries “host ai agent” and “ai agent hosting”, both near position 60. The rest of the query intent was anonymized, so the run did not label the page a snippet problem.

The agent made exactly three SEO research calls, read one webpage, and saved one Markdown file. The run completed in 2 minutes 9 seconds and displayed 76,064 tokens. It did not retry a call or modify the site.

The exact-page ranking call returned no rows. The provider returned an estimated monthly volume of 40 and keyword difficulty of 4 for “ai agent hosting”; it did not return the second named query. The live top five contained community discussion, hosting guides, framework documentation, and a cloud-runtime page. plori was not in those five results. The brief reported each finding under its source instead of blending the numbers.

That proves the bounded research and file handoff work. It does not prove the estimates are exact, that the proposed copy will rank, or that one date's top five will stay fixed.

What should be in the saved brief?

The saved file should begin with the page's intent and the limits of the evidence. Next come the current strengths and gaps, followed by proposed title, description, H1, and question-shaped section outline. The final action list has two parts:

1. Evidence-backed edits. Examples include naming the canonical question in the H1, making a verified answer easier to find, or adding a descriptive link to a relevant existing guide.
2. Hypotheses to measure. These are changes that might improve relevance or clicks, but the current evidence cannot prove them. Give each one a GSC query-by-page metric and a review window.

For the live run, the agent proposed clearer “where to host” framing and links to existing pages rather than another landing page. That preserves the canonical intent of the hosting page and avoids competing with the cloud AI agent field guide or the platform comparison.

How do you review the brief before changing the page?

1. Check that every metric names its source and date range.
2. Confirm that “not returned” and “anonymized” have not become zero.
3. Read each proposed product answer against the live product and docs. Remove any claim the research provider introduced.
4. Keep one canonical page for the intent. Improve it instead of publishing a near-copy.
5. Choose a small set of edits, record the before state, and monitor the same GSC query-by-page rows after the page is recrawled.
6. Start a fresh session for another URL. Do not let raw research from several pages accumulate in one agent conversation.

What are the limits?

SEO provider data is modeled and can differ from Google Search Console. A live SERP is a snapshot, not a durable ranking record. Search Console also protects privacy by omitting some queries, so its disclosed rows may not add up to the page total.

Research results can be large even when the call count is small. This verified run stayed inside the three-call boundary but still used 76,064 displayed tokens. Keep the scope narrow, set include_monthly_trends false, and use a new session per page. For a first pass, do not add keyword expansion simply because the tool is available.

Common questions about AI agents for SEO research

Can an AI agent research SEO without my own provider account? Yes. plori (plori.ai) is a cloud AI agent with its own persistent environment: durable disk, real CLI tools, and memory. Its managed SEO tools cover ranked keywords, keyword metrics, live SERPs, domain overviews, backlink summaries, and keyword expansion. The calls use your plori credits; you do not paste a provider key into chat.

What is the difference between Search Console facts and SEO provider estimates? Search Console reports first-party performance for a property you control, including impressions, clicks, and average position. SEO providers model demand and rankings from their own datasets. Both can inform a brief, but a provider's volume or rank estimate is not a Search Console fact.

Should the agent publish its SEO changes automatically? No. This prompt is research-only. It saves a brief, labels facts and hypotheses, and leaves the site untouched. Review product claims, intent overlap, internal links, and the measurement plan before authorizing a code or CMS change.

Why use only three SEO calls? The three calls answer the page-level questions: what this URL appears to rank for, what the live primary-query results look like, and what the provider estimates for two named queries. Expansion, backlinks, and domain-wide analysis answer broader questions and deserve separate sessions with their own budgets.