DEV Community: AgentSEO-dev

How to Audit Title Tags and Meta Descriptions Without Chasing Character Counts

AgentSEO-dev — Thu, 27 Aug 2026 07:22:49 +0000

A title and meta description audit can produce hundreds of “issues” without finding one page worth changing.

The usual export flags every title over 60 characters and every description over 160. That catches obvious implementation defects. It does not tell you whether Google showed the title, whether the snippet matched the query, whether the page earned impressions, or whether a rewrite would improve the result.

This workflow separates three different jobs:

fix broken or ambiguous metadata;
align the title, visible heading, and page promise;
test search-result copy only where query-level evidence justifies it.

The output is a short action queue, not a spreadsheet full of red cells.

Start with the displayed result, not a universal length limit

Google does not document a fixed character limit for title links or meta descriptions. Title links are truncated as needed, usually to fit the device width. Snippets are also truncated to fit the result.

More importantly, your HTML is an input rather than a command.

Google can create a title link from the <title> element, visible page title, headings, og:title, prominent page text, and link text. It primarily creates snippets from page content and may use the meta description when that gives a better page summary for the search.

That changes the audit question.

Do not ask only:

Is this title under 60 characters?

Ask:

For an important query, does the displayed title and snippet describe the page
accurately, distinguish it from competing results, and set up the promise the
visitor sees after clicking?

Length is still useful as a risk signal. It is not a pass/fail standard.

Build the audit from four evidence sets

You need four inputs to make a defensible decision.

Evidence	What it tells you	What it cannot tell you
Crawl or rendered HTML	Missing, duplicate, empty, or conflicting signals	What Google displayed for a query
Page copy and headings	Whether the metadata matches the visible promise	Whether searchers found the result attractive
Search Console page/query data	Impressions, clicks, CTR, and average position	The exact causal effect of changing copy
A current SERP check	Displayed title, snippet, competitors, and result features	A stable result for every user, query, or device

Use the crawl to find defects. Use the page to judge accuracy. Use Search Console to prioritize. Use the live result to inspect what Google actually chose.

Do not use one evidence set as a substitute for the others.

Triage implementation defects before copy opportunities

Start with canonical, indexable pages that return a successful response. Metadata work on a blocked, redirected, or non-canonical URL is usually the wrong queue.

Then flag defects that prevent a clear page signal:

no HTML title element;
an empty or half-complete title that contains only a separator and brand name;
multiple templates producing the same title for different pages;
an obsolete year, price, availability claim, or product name;
no clear main heading;
a title, H1, and visible introduction that describe different jobs;
a missing description on a commercially or editorially important page;
a description copied across pages where the details should differ;
metadata present in a CMS field but missing from rendered HTML.

These are repair tasks. You do not need a CTR theory to fix them.

Google's title-link guidance specifically identifies half-empty, obsolete, inaccurate, and boilerplate titles, along with pages that have no clear main title. A generated replacement is often a symptom of ambiguous or stale page signals—not proof that Google has made an error.

Treat Google rewrites as a diagnostic clue

Practitioners regularly ask why Google ignored a supplied title or description. Recent r/TechSEO discussions show the same frustration: a CMS field looks correct, but the search result uses a heading or opening sentence instead.

That community evidence is directional, not a rewrite-rate benchmark. The useful pattern is the question itself.

When a displayed result differs from your metadata, record:

query;
URL;
device and country;
supplied title and description;
displayed title and snippet;
the on-page source Google appears to have used;
date checked.

Then classify the difference.

Rewrite pattern	Likely issue to inspect	First action
Google uses the H1	Title may be vague, boilerplate, or less descriptive	Compare the title with the H1 and query intent
Google uses an opening paragraph	Meta description may not summarize the visible page	Improve page copy before polishing the tag
Google removes the brand	Branding may be repetitive or unhelpful in this result	Keep branding concise; do not force repetition
Google changes a date or product detail	Metadata may be obsolete	Correct every conflicting page signal
Different queries show different snippets	The page answers multiple specific needs	Check whether each snippet is accurate; this may be normal

Do not promise to “stop Google rewriting” metadata. Google documents the generation as automated and query-dependent. You can make the signals clearer; you cannot force one exact result for every search.

Prioritize pages with query-level evidence

A metadata queue should begin with pages that matter, not pages that are easiest to export.

For each canonical URL, compare the latest 28 days with a useful prior period and keep the query dimension. Prioritize pages where:

impressions are meaningful enough to learn from;
average position is reasonably stable;
CTR fell for the same query cluster;
the displayed result is inaccurate, generic, or visibly misaligned;
the page still satisfies the intent after the click;
a business-relevant action happens on the page.

Deprioritize pages where demand collapsed, position changed materially, the SERP layout changed, or the page no longer satisfies the query. Those are not clean metadata tests.

Average CTR benchmarks are a poor substitute for this comparison. CTR varies with position, query type, brand familiarity, device, country, and SERP features. Compare the same page and query family under reasonably similar conditions.

Use a decision table instead of rewriting everything

This is the action model I would apply to the queue.

Condition	Decision
Missing, empty, obsolete, deceptive, or duplicate title	Fix now
Title, H1, and opening promise conflict	Fix the page-message system, then metadata
Description missing on a priority URL	Add a page-specific summary
Google rewrite is accurate and useful	Leave it alone; record the observation
Supplied metadata is accurate but displayed copy is weak for an important query	Test one aligned alternative
CTR fell because position or SERP features changed	Diagnose the ranking or result-layout change first
Page no longer fulfills the query	Refresh or reposition the page before testing snippet copy
Low-impression URL with no business value	Deprioritize

The hard part is accepting that “no change” is a valid audit result.

Generate options from the page promise, not a keyword list

Once a URL passes triage, create alternatives from the visible page.

The title should identify the topic and distinguish the page. The description should summarize what the visitor can actually get. Neither should promise a comparison, template, price, result, or feature that the page does not provide.

AgentSEO's /content/title-meta endpoint can turn a URL or Markdown page into three title options, three meta description options, current-signal checks, snippet risks, and an implementation checklist.

Here is a copy-paste request using Markdown so the input remains reproducible:

curl -X POST "https://www.agentseo.dev/api/v1/content/title-meta?sync=true" \
  -H "x-api-key: sk_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "SEO API for AI agents",
    "target": "AgentSEO",
    "page_type": "software",
    "current_title": "SEO API | AgentSEO",
    "current_meta_description": "The token-optimized SEO API for AI agents.",
    "page_markdown": "# SEO Intelligence API for AI Agents\n\nAgentSEO returns compact SERP metrics, content workflow recommendations, and strict JSON for MCP and REST integrations. Builders can test requests in the Playground before wiring scheduled production jobs.\n\n## Build with deterministic search intelligence\n\nUse documented endpoints for content briefs, rank tracking, internal links, and technical QA."
  }'

The current endpoint costs two credits and does not call a paid SERP provider. It uses the page you supply or retrieves the URL, then checks signal alignment and produces options. Confirm current behavior and pricing in the AgentSEO API reference before production use.

Treat the result as a review plan. The endpoint does not inspect a live Google result or forecast a CTR gain.

A useful output review looks like this:

1. Reject any option that changes the page's actual promise.
2. Resolve high-severity missing-title or missing-H1 findings first.
3. Check the title against the visible H1 and first screen of copy.
4. Choose one option for the target query family.
5. Record the exact old and new values before deployment.

If you prefer tools inside an agent workflow, the same job is available through the AgentSEO MCP server. Use REST when this is a scheduled batch or application backend; use MCP when an operator is reviewing pages interactively with an agent.

Test one controlled change

Metadata tests are noisy, so keep the release small.

Record:

URL and target query family;
deployment date and time;
old and new title and description;
reason for the change;
28-day and 90-day pre-change query metrics;
displayed result before the change;
any simultaneous content, template, or internal-link changes.

Verify the rendered HTML immediately. Then allow time for recrawling and reprocessing. Google's title-link documentation says this can take a few days to a few weeks.

Review recrawl and display behavior in 3–7 days, direction after 14 days, and the primary comparison after 28 days. Keep the query, device, country, position, and SERP layout in view.

Do not call a CTR change causal if rankings, demand, result features, or page content changed at the same time. The honest outcome may be “promising but confounded.”

Failure modes that make the audit look busier than it is

Rewriting every long title

A long title can be truncated, but Google does not publish a universal character ceiling. Fix verbosity and ambiguity; do not cut useful words only to make a crawler cell green.

Treating every generated snippet as a defect

Different searches can legitimately produce different snippets from the same page. Inspect whether the displayed text is accurate for that query.

Optimizing the tag while ignoring the page

If the H1, introduction, and body do not support the promise, the metadata is cosmetic. Fix the visible page first.

Changing titles on pages with unstable positions

A CTR change is hard to interpret when average position or the SERP layout is moving. Stabilize the comparison or label the result inconclusive.

Using schema to force ordinary titles or descriptions

Structured data can make a page eligible for supported search features. It does not provide a control panel for the ordinary title link and snippet.

Automating deployment from a generated option

Generation is reversible. Publishing is not. Keep a human review gate before a title or description reaches production, especially on revenue pages and large templates.

The finished queue should fit on one screen

The deliverable is not a sitewide list of lengths. It is a ranked decision queue:

Fix now: broken or misleading signals
Align first: title, H1, and page promise conflict
Test: important query with stable visibility and a weak displayed result
Observe: accurate Google rewrite with no clear user problem
Ignore: low-value page or confounded evidence

Start with ten priority URLs. Fix defects, test one aligned change at a time, and leave accurate generated results alone.

That is slower than bulk rewriting metadata. It is also an audit you can learn from.

AI assistance disclosure: Human topic selection, product context, source standards, and publication judgment guide this article. AI assisted with research organization and drafting. Daniel Martin must review the claims, examples, voice, and final recommendation before publication.

How to Do an Internal Linking Audit That Produces Useful Fixes

AgentSEO-dev — Thu, 27 Aug 2026 07:03:53 +0000

An internal linking audit can produce a clean spreadsheet and still fail to improve the site.

The usual report counts links, flags orphan pages, and lists crawl depth. That is necessary diagnostic work. It does not answer the harder editorial question:

Which page should link to this URL, in which section, with what anchor, and why would the link help the reader?

You need both layers. First, audit the site graph to find structural problems. Then review the page context before adding any link.

This tutorial gives you a repeatable workflow for doing that. It includes a spreadsheet-ready decision model and a copy-paste AgentSEO request for ranking supplied target pages against a source article.

The short answer

To audit internal links:

Build an inventory of canonical, indexable URLs.
Crawl the site and join the crawl with sitemap, analytics, and Search Console exports.
Find orphan candidates, broken destinations, redirects, excessive depth, and important pages with weak relevant support.
Prioritize pages by business value and search role, not raw inlink count.
Choose contextually relevant source pages for each target.
Write concise, descriptive anchors inside useful body copy.
Verify the rendered HTML contains normal crawlable <a href> links.
Release a controlled batch and measure page-level outcomes.

Google's current link guidance supports the fundamentals behind this workflow: links help Google discover pages and understand relevance, crawlable links generally use an <a> element with an href, and anchor text should be descriptive, concise, and relevant. Google also says every page you care about should have a link from at least one other page on your site. Read Google's link best practices.

That guidance does not mean every page needs more links. The audit should improve routes through the site, not maximize a count.

Start with a page inventory, not an anchor-text brainstorm

Your crawler sees URLs it can reach. Your XML sitemap may contain URLs the crawler cannot reach. Search Console and analytics may contain historical URLs absent from both.

Combine at least these sources:

Source	What it can reveal	What it cannot prove alone
Site crawl	Current link paths, status codes, depth, inlinks, outlinks	Whether an uncrawled URL exists elsewhere
XML sitemap	URLs you intend search engines to discover	Whether each URL has internal support or deserves indexation
Search Console	Pages with Google Search impressions or clicks	A complete site architecture
Analytics	Pages people visit and paths they take	Search-engine crawlability
CMS export	Published pages and ownership metadata	What production actually renders

Normalize the URLs before comparing them. Remove fragments, handle trailing slashes consistently, and separate tracking parameters from canonical URLs. Keep the original values in another column so the cleanup stays reversible.

Your working inventory should include:

url
canonical_url
status_code
indexability
page_type
primary_topic
business_priority
inlinks
unique_linking_pages
crawl_depth
sitemap_present
search_impressions_90d
organic_clicks_90d
conversion_role

Do not call a page an orphan merely because one crawler missed it. A crawl limit, blocked resource, JavaScript rendering problem, or incomplete starting set can create false positives. Treat orphan status as a candidate finding until you reconcile the crawl with the sitemap, CMS, Search Console, and analytics.

Separate technical defects from editorial opportunities

One queue should not mix broken links with optional content improvements. The fixes have different risk and ownership.

Technical defects

These normally deserve the first pass:

internal links that resolve to 4xx or 5xx pages
links that pass through avoidable redirect chains
important URLs that have no confirmed crawlable internal link
links implemented as click handlers without a resolvable href
links to non-canonical, duplicate, or unintended noindex URLs
important pages buried behind pagination or excessive crawl depth

Editorial opportunities

These require judgment:

a strong source page mentions a concept but does not link to the best next resource
an important product or documentation page is supported only by navigation links
anchors such as “click here” or “read more” hide the destination's meaning
multiple links use forced exact-match phrasing that reads unnaturally
unrelated pages link to a target only because they have traffic or backlinks
a new or refreshed page does not connect to its surrounding topic cluster

The technical queue asks, “Can a crawler reach the right URL?” The editorial queue asks, “Does this link make sense in the reader's journey?”

Prioritize targets before choosing sources

Raw inlink count is a weak priority rule. Ten boilerplate links from tag pages are not equivalent to two relevant contextual links from pages that readers already use.

Score target pages with criteria your team can defend:

Criterion	Question	Example score
Business role	Does the page support evaluation, activation, or retention?	0–3
Search opportunity	Does the page already have impressions, useful rankings, or validated demand?	0–3
Structural need	Is it orphaned, deep, or weakly supported by relevant pages?	0–3
Content readiness	Is the destination accurate, useful, canonical, and fit to receive traffic?	0–3
Fix confidence	Can the team identify a genuinely relevant source and placement?	0–3

Prioritize high-value pages with structural need and a sound destination. Do not push more internal traffic to a thin, outdated, redirected, or conversion-hostile page. Fix the destination first.

This is also where you avoid a common audit failure: adding links to every orphan. Some orphan candidates should be merged, redirected, removed from the sitemap, or left out of the index rather than rescued.

Choose the source page and placement together

Once you have a target shortlist, search the content inventory for pages that discuss the same problem, task, entity, or next step.

A useful source page passes four checks:

Topical fit: The surrounding section naturally relates to the target.
Reader utility: The destination helps the reader continue, compare, implement, or verify.
Page quality: The source is canonical, indexable, and worth maintaining.
Placement clarity: You can point to an existing paragraph or heading where the link belongs.

If you cannot name the sentence-level reason for the link, do not add it yet.

Recent practitioner discussions make the same distinction. One r/TechSEO thread argues that a technically crawlable page can still lack meaningful support when it has few links from relevant pages or vague anchors. Another discussion notes that an inlink count misses where links come from and whether the anchor describes the destination. These are practitioner observations, not proof of a ranking effect, but they expose a real audit-quality problem. Read the first discussion and the follow-up discussion.

Use AgentSEO to rank supplied targets for one source page

AgentSEO's /content/internal-links endpoint handles the editorial layer of the workflow. You provide one source URL or its Markdown plus 1–50 candidate target pages. It returns ranked opportunities, suggested anchor text, a source section, placement instructions, confidence, anchor risk, and review guardrails.

It does not crawl the entire site graph in v1. Use a crawler, CMS export, sitemap audit, or Search Console data to build and prioritize the candidate set first.

Here is a copy-paste request using supplied Markdown, which makes the input reproducible:

curl -X POST "https://www.agentseo.dev/api/v1/content/internal-links?sync=true" \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "SEO API",
    "target": "AgentSEO",
    "max_suggestions": 4,
    "source_markdown": "# Build an SEO agent\n\nAn SEO agent needs stable search data, explicit workflow boundaries, and a review gate before changes reach production.\n\n## Choose the integration\n\nUse a tool protocol when the model should discover and call SEO capabilities during a conversation. Use REST when your application controls orchestration, retries, and storage.\n\n## Validate the result\n\nCheck the returned evidence, confidence, limitations, and next action before allowing an automated change.",
    "target_pages": [
      {
        "url": "https://www.agentseo.dev/seo-mcp-server",
        "title": "AgentSEO MCP Server",
        "description": "Connect SEO search intelligence tools to compatible AI clients.",
        "keywords": ["SEO MCP server", "MCP tools"]
      },
      {
        "url": "https://www.agentseo.dev/docs/api-reference",
        "title": "AgentSEO API Reference",
        "description": "REST endpoints, request fields, and response contracts.",
        "keywords": ["SEO API reference", "REST endpoints"]
      },
      {
        "url": "https://www.agentseo.dev/editorial-policy",
        "title": "AgentSEO Editorial and Evidence Policy",
        "description": "Evidence, review, disclosure, and publication standards.",
        "keywords": ["editorial review", "evidence policy"]
      }
    ]
  }'

Use your actual page descriptions and topic labels. Weak metadata creates weak matching.

I verified this exact request against the production endpoint on August 27, 2026. The short sync window returned a standard 202 job envelope, and polling the supplied poll_url returned a completed result with three opportunities:

Suggested target	Anchor	Relevance	Confidence
AgentSEO API Reference	`SEO API reference`	26/100	0.64
AgentSEO Editorial and Evidence Policy	`editorial review`	25/100	0.63
AgentSEO MCP Server	`SEO MCP server`	21/100	0.60

The output also flagged the 71-word sample as thin and recommended adding useful context before inserting several links. That is the right kind of resistance: all three matches are candidates for review, not automatic edits. This was one supplied-markdown test with three candidate targets, so it verifies the request and response contract rather than recommendation quality across a full site.

The endpoint currently costs two credits and does not call a paid SERP provider. See the current request contract in the AgentSEO API reference and test the workflow in the AgentSEO Playground.

Review the output as a recommendation, not an instruction

A returned opportunity should survive a human review before implementation.

For each suggestion, ask:

Is the target the canonical page for this intent?
Does the source paragraph actually introduce the target's topic?
Would a reader reasonably want the destination at this point?
Is the proposed anchor descriptive without sounding forced?
Does the source already link to this destination?
Will the link render in production as an <a> element with an href?
Are you creating too many links in one paragraph or section?

An automated relevance score cannot see every business constraint. It may not know that a product page is being retired, that two docs pages are about to merge, or that a legally required disclaimer changes the best placement.

Keep a rejection reason in the audit sheet. “Not relevant enough,” “target being consolidated,” and “destination not ready” are useful training data for the next review. Silent deletion is not.

Write anchors for comprehension

Google recommends anchor text that is descriptive, reasonably concise, and relevant to both the source and destination. That is a better rule than forcing the same target keyword every time.

Prefer:

AgentSEO API reference
content decay workflow
compare MCP and REST for SEO agents

Avoid:

click here
learn more
a long sentence linked in full
the same exact commercial phrase on every source page

Anchor diversity should come from natural language and different source contexts, not a spreadsheet quota. If the most accurate anchor repeats occasionally, that is less concerning than rewriting useful copy into awkward variants.

Ship the fixes in controlled batches

Do not rewrite the entire link graph in one release. Start with a small group of priority targets and record:

deployment date and changed URLs
source URL, target URL, anchor, and placement
reason for the change
pre-change crawl depth and unique linking pages
pre-change 28-day and 90-day Search Console page/query metrics
conversion or activation event tied to the target page

Verify the rendered pages immediately. Then review recrawl and indexation after 3–7 days, directional page/query movement after 14 days, primary performance after 28 days, and retain/iterate decisions after 56 days.

Do not claim that a ranking change came from one internal link unless you controlled the other variables. Search demand, page edits, external links, competitors, and Google systems can all move at the same time.

The audit is complete when every recommendation has an owner

A useful internal linking audit does not end with a severity score. It ends with a decision:

fix the broken or redirected link
add a relevant contextual link
improve the destination before linking
merge or redirect the target
leave the link graph unchanged
monitor because the evidence is incomplete

The practical next move is to choose five important target pages, reconcile their crawl and sitemap status, then review only the most relevant source pages. That small batch will teach you more than automatically inserting hundreds of links.

Disclosure: AI assisted with research organization, drafting, editing, and cover-image creation. Daniel Martin should review the claims, examples, recommendations, and final publication decision before this article is published.

How to Find and Fix Keyword Cannibalization With Google Search Console Data

AgentSEO-dev — Tue, 25 Aug 2026 15:31:29 +0000

Two pages receiving impressions for the same query is not enough evidence to merge them.

It is a reason to investigate.

That distinction matters because a rushed cannibalization cleanup can erase a useful page, redirect an audience to the wrong intent, or canonicalize two pages that are not actually duplicates. The site ends up tidier in a spreadsheet and less useful in search.

A safer workflow combines three things:

Google Search Console performance data
page-level intent and business value
a clear ownership decision for every affected query

This tutorial shows how to turn those inputs into a review queue, use an agent to structure the evidence, and choose among differentiation, internal linking, consolidation, canonicalization, or no change.

Start with a conflict, not a duplicate keyword

Keyword overlap is normal.

A product page and a tutorial can both receive impressions for the same broad phrase. Two location pages can share service terms. A glossary page may appear for a query that usually belongs to a commercial page.

The useful question is not:

Do multiple URLs appear for this query?

It is:

Are multiple URLs serving the same intent, and is that overlap preventing the right page from performing its job?

Recent discussions in r/SEO keep returning to this distinction. Practitioners recommend starting with query-page exports, but they also warn that multiple ranking URLs can be normal and must be judged case by case. Treat that as directional community evidence, not a ranking rule. Discussion: checking cannibalization across a 200-page site · Discussion: different intents are not necessarily cannibalization

Google's own documentation gives us two important constraints:

Search Console lets you group and filter performance by query and page, but anonymized queries and data truncation mean the report is not a complete ledger. Search Console dimensions and data groupings
Canonicalization is Google's process for selecting a representative URL among duplicate or very similar pages. It is not a general-purpose fix for every pair of pages that shares a keyword. Google Search Central: canonicalization

Those constraints should make the audit more conservative, not less.

Build a query-to-page review table in Search Console

Use a date range long enough to reduce noise. Ninety days is a practical starting point for an established site, but compare it with the previous period and check seasonality before treating a movement as structural.

In the Search results Performance report:

Export query and page performance for Web search.
Keep clicks, impressions, CTR, and average position.
Group rows by query.
Flag queries associated with two or more indexable URLs.
Exclude navigational queries and obvious sitelink behaviour before prioritizing the queue.

Do not rely on a single filtered total. Google notes that query or URL filters can change report totals because of anonymized queries and truncation. Search Console filtering limitations

Your first table can be simple:

Query	URL	Clicks	Impressions	Avg. position	Intended page job
seo api for agents	/seo-api	126	3,900	7.4	commercial evaluation
seo api for agents	/blog/best-seo-api-agents	41	2,100	11.8	comparison and education
seo api for agents	/docs/api-reference	7	440	18.2	implementation reference

This example is illustrative. It shows why URL count alone is weak evidence. All three pages can legitimately mention the query, but only one should usually own its primary search job.

Separate harmless overlap from harmful competition

Review each flagged cluster against four tests.

The pages serve the same intent

Read the pages before changing them. Compare the promised outcome, page type, target reader, funnel stage, and likely next action.

If one page teaches and another sells, the overlap may be useful. If both pages make the same promise to the same reader, the conflict is more credible.

The wrong URL wins or the winner keeps changing

Look for repeated evidence across time:

the less useful URL receives most clicks for the target query
the ranking URL changes between periods
both pages remain in weak positions instead of one becoming the clear result
internal links use similar anchors for both pages
the preferred landing page loses qualified conversions while the other page gains impressions

No single signal proves cannibalization. Together, they justify review.

The overlap creates a user or business cost

An informational article outranking a product page is not automatically bad. It becomes a problem when the query has commercial intent and the article cannot help the visitor complete the job.

Measure the cost that matters: qualified clicks, sign-ups, assisted conversions, or support burden. Rankings without page purpose are not enough.

The evidence survives known Search Console limitations

Search Console assigns most performance data to canonical URLs, and some query data is omitted or truncated. A small sample of overlapping rows should not trigger a redirect. Check the live pages, inspect Google's selected canonical where relevant, and review the current SERP before deciding. How Search Console groups page data

Give the agent structured evidence, not a vague prompt

An agent can compare dozens of page clusters consistently, but only if the input preserves page role and performance context.

AgentSEO exposes agentseo_content_cannibalization for this job. The tool accepts page titles, headings, target and ranking queries, page type, canonical URL, indexability, performance, backlinks, and freshness signals. It returns conflicts, page signals, clusters, and a reviewable fix plan.

Use a prompt like this in an MCP client:

Use agentseo_content_cannibalization to review these pages for the focus query
"seo api for agents".

Use balanced sensitivity. Treat the supplied Search Console metrics as directional,
not proof of harm. Return:
1. the intended job of each page,
2. whether the pages share the same intent,
3. the preferred primary URL and why,
4. the safest fix,
5. evidence that still needs human verification.

Do not recommend a redirect or canonical solely because two URLs receive impressions.

For a REST workflow, the same review can be called directly:

curl -s -X POST "https://www.agentseo.dev/api/v1/content/cannibalization?sync=true" \
  -H "x-api-key: YOUR_AGENTSEO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "target": "example.com",
    "focus_keywords": ["seo api for agents"],
    "sensitivity": "balanced",
    "pages": [
      {
        "url": "https://example.com/seo-api",
        "title": "SEO API for AI Agents",
        "headings": ["Live search data for agent workflows"],
        "target_keywords": ["seo api for agents"],
        "ranking_queries": ["seo api for agents", "seo api"],
        "page_type": "product",
        "clicks": 126,
        "impressions": 3900,
        "avg_position": 7.4,
        "indexable": true
      },
      {
        "url": "https://example.com/blog/best-seo-api-agents",
        "title": "How to Evaluate an SEO API for AI Agents",
        "headings": ["The evaluation criteria", "Payload design"],
        "target_keywords": ["best seo api for ai agents"],
        "ranking_queries": ["seo api for agents", "best seo api for ai agents"],
        "page_type": "blog_post",
        "clicks": 41,
        "impressions": 2100,
        "avg_position": 11.8,
        "indexable": true
      }
    ]
  }' | jq '.result.content_cannibalization // .content_cannibalization'

Replace the illustrative values with a consistent Search Console period. Keep the source export beside the result so a reviewer can trace the recommendation.

Choose the fix that matches the page relationship

The audit should end in one of five decisions.

Relationship	Default action	What gets worse if misused
Same topic, different intent	Differentiate titles, headings, copy, and internal anchors	Forced separation can make both pages less complete
One clear primary page with useful support pages	Reinforce ownership through internal links and navigation	Over-optimized anchors can make the site feel mechanical
Two pages perform the same job and one adds little unique value	Consolidate useful material and redirect the weaker URL	You can lose long-tail coverage or backlinks if the merge is careless
Duplicate or very similar URL variants	Use canonicalization or redirects as appropriate	A canonical can hide a page that deserved separate indexing
Overlap without measurable harm	Leave the pages alone and monitor	Premature cleanup creates work without improving the search result

Google describes redirects as a strong canonical signal, rel="canonical" as another strong signal, and sitemap inclusion as weaker. Signals can reinforce one another, but Google still makes the final canonical choice. Google Search Central: specifying a canonical URL

That is why a canonical tag should express a genuine duplicate relationship. It should not substitute for deciding what two distinct pages are meant to do.

Make URL ownership visible before creating the next page

Fixing existing conflicts is only half the job. The content process must stop recreating them.

Maintain a keyword map with one primary URL per search intent. Before approving a new brief, check:

the primary query and close variants
the page type and intended reader
the existing URL that currently owns the intent
whether the new asset supports, differentiates, or replaces that URL
which internal links should point to the primary page

AgentSEO's agentseo_content_keyword_map can map supplied keywords to existing pages and flag weak matches, missing pages, and cannibalization risks before drafting begins. The important output is not another keyword cluster. It is an explicit ownership decision that downstream briefs and agents can follow.

The operator move: do not merge the first pair of pages that shares impressions. Assign the intended search job, verify actual harm, then make the smallest change that clarifies ownership.

Re-measure the query after the change

Record the change date, affected URLs, target query, and expected outcome. Then compare a meaningful post-change period against the baseline.

Look for:

the preferred URL receiving a more stable share of clicks and impressions
improved qualified conversions for the query cluster
fewer unwanted ranking-URL changes
preserved performance for distinct long-tail intents
Google's selected canonical matching the intended duplicate relationship, where applicable

Do not claim success from a ranking change alone. Seasonality, SERP changes, competitor updates, and demand shifts can move the same metrics.

The workflow is deliberately conservative: detect overlap, verify intent, estimate harm, choose a page owner, apply the smallest defensible fix, and monitor the result.

That is slower than bulk-merging URLs from a spreadsheet.

It is also much less likely to delete a useful part of your search system.

Try the workflow

Disclosure: AI tools assisted with research organization, drafting, and editing. Daniel Martin reviewed and approved the topic, claims, workflow, examples, and publication decision.

How to Do a Competitor Content Gap Analysis Without Copying Competitors

AgentSEO-dev — Tue, 25 Aug 2026 14:56:45 +0000

A competitor content gap export is not a content plan.

It is a list of things other sites rank for.

That distinction matters. If you send every missing keyword to a writer, you create a backlog shaped by somebody else's business. You also risk publishing new pages for queries an existing page already serves, copying formats that do not fit your audience, and spending weeks on traffic that will never reach the product.

A useful competitor content gap analysis makes three decisions:

which gaps deserve a new page
which gaps belong in an existing page
which gaps should be ignored

This tutorial shows how to make those decisions with search intent, buyer stage, page type, product fit, and current SERP evidence. It also includes a copy-paste AgentSEO request for turning supplied page exports into a prioritized matrix.

The short answer

Run the analysis in this order:

Define the audience, product boundary, and conversion you care about.
Select search competitors, not only business competitors.
Export your pages and competitor pages with queries and useful metrics.
Group gaps by topic, page type, and buyer stage.
Check whether each gap is missing coverage, weak coverage, a format gap, or a stage gap.
Validate the strongest candidates against the live SERP and your existing URLs.
Send accepted candidates to a new-page brief or refresh brief.

The final output should be a short action queue. A 4,000-row spreadsheet is research material, not a strategy.

Start with a boundary competitors cannot choose for you

Before collecting competitor keywords, write this sentence:

We want to attract [specific audience] who need to [specific job],
and the useful next step is [product-relevant conversion].

For AgentSEO, one version is:

We want to attract growth engineers and technical marketers who need to
turn search data into repeatable agent workflows, and the useful next step
is to run a workflow through the API or playground.

This boundary removes plenty of tempting but irrelevant gaps.

A large SEO platform may rank for social media calendars, email templates, or general marketing definitions. Those keywords may have demand. They are still poor candidates for an agent-native SEO intelligence API unless they support a credible workflow and conversion path.

Google's people-first content guidance asks whether a site has an intended audience, demonstrates first-hand expertise, and leaves readers feeling they learned enough to achieve their goal. It also warns against producing content across many topics merely in the hope that some of it performs. That makes audience and task fit useful filters before volume or difficulty enters the queue. Read Google's people-first content guidance.

Choose competitors from the SERP, not the sales deck

Your commercial competitors and search competitors are not always the same.

Use three groups:

Competitor type	What it reveals	Main risk
Direct product competitor	Commercial topics, comparisons, use cases	Copying their positioning instead of yours
SERP competitor	Formats and pages winning the target queries	Treating an unrelated publisher as a business model
Audience competitor	Questions your buyers ask before or after purchase	Expanding beyond the product's credible boundary

Start with two or three domains that repeatedly appear for queries your audience owns. Add a direct competitor when it provides a useful commercial comparison, even if it does not dominate the same informational results.

Do not select a competitor because its estimated traffic is large. A broad publisher can create thousands of apparent gaps that have no product fit.

Recent practitioner discussions show why this step causes trouble. One r/seogrowth thread asks how smaller sites should map competitor content without blindly following larger domains. Another discussion about crawling competitor sites focuses on turning page structure and query data into briefs, but questions how accurately automation can identify meaningful gaps. These are directional community observations, not evidence of a ranking factor. Read the competitor-selection discussion and the automation discussion.

Collect page-level inputs, not keywords in isolation

A keyword-only export hides the decision context.

For each owned and competitor page, collect what you can from this list:

URL and title
ranking queries or assigned keywords
likely page type
likely buyer stage
estimated traffic and search volume
average position
backlinks or referring-domain signal

Page type and buyer stage are especially useful. They expose gaps that a flat keyword comparison misses.

Imagine competitors cover SEO API template with an implementation template while your only matching asset is a high-level API guide. You do not have a completely missing topic. You may have a format or implementation-stage gap.

Now imagine you already have a guide ranking for the same query, but it is weaker than the competing pages. The likely action is to inspect and refresh that URL, not create another guide and manufacture cannibalization.

Treat third-party traffic, volume, difficulty, and backlink numbers as estimates. They help sort the work; they do not prove that a page will rank, convert, or deserve production.

Classify every gap before scoring it

Use four practical gap types.

Missing topic

Competitors cover a relevant topic and no supplied owned page clearly matches it.

Possible action: validate the SERP and create a new page only if the audience, intent, and conversion path fit.

Weak coverage

An owned page matches the topic, but the supplied performance or coverage signals are weaker.

Possible action: compare the live pages, check Search Console, and create a focused refresh brief.

Format gap

You cover the topic, but the useful competing format differs. Your article may face templates, tools, comparison pages, or documentation.

Possible action: decide whether the format genuinely helps the reader. Do not convert a guide into a tool merely because one tool ranks.

Buyer-stage gap

Your coverage serves awareness while competitors answer consideration, decision, or implementation questions.

Possible action: add the missing decision support when it belongs on an existing page, or brief a distinct asset when the search task and conversion are genuinely different.

This classification prevents the most expensive mistake in gap analysis: assuming that every difference requires another URL.

Build a matrix that forces an action decision

Create a table with one row per normalized topic.

Topic	Gap type	Page type	Buyer stage	Existing match	Product fit	SERP validated	Action
SEO API templates	Format gap	Template	Implementation	API guide	High	Pending	Validate
Generic marketing plan	Missing topic	Guide	Awareness	None	Low	No	Ignore
SEO API comparison	Weak coverage	Comparison	Consideration	Comparison page	High	Yes	Refresh

The important columns are near the end. A high gap score can still produce Ignore.

Use the following action rules:

New page: no same-intent page exists, product fit is clear, and the current SERP supports the proposed task and format.
Refresh: an existing URL serves substantially the same intent and can be made more complete, useful, or current.
Differentiate: the topic overlaps, but a different audience task or buyer stage deserves deliberate separation.
Ignore: the query lacks audience fit, product fit, a credible conversion, or a useful angle AgentSEO can support.

Google says its systems prioritize helpful, reliable content created to benefit people. Its guidance does not grant value to a page merely because competitors have one. Review Google's guidance.

Turn supplied exports into an AgentSEO gap matrix

AgentSEO's competitor gap matrix accepts owned pages and competitor pages, then groups the supplied evidence by topic, page type, and buyer stage.

Here is a minimal reproducible request:

curl -X POST "https://www.agentseo.dev/api/v1/content/competitor-gap-matrix?sync=true" \
  -H "x-api-key: sk_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "AgentSEO",
    "focus_topics": ["seo api templates"],
    "own_pages": [
      {
        "url": "https://www.agentseo.dev/docs/api-reference",
        "title": "AgentSEO API Reference",
        "keywords": ["seo api"],
        "ranking_queries": ["seo api docs"],
        "page_type": "docs",
        "buyer_stage": "implementation"
      }
    ],
    "competitors": [
      {
        "domain": "competitor.example",
        "pages": [
          {
            "url": "https://competitor.example/templates/seo-api-template",
            "title": "SEO API Template Library",
            "keywords": ["seo api templates", "seo workflow template"],
            "ranking_queries": ["seo api templates"],
            "page_type": "template",
            "buyer_stage": "implementation",
            "estimated_traffic": 500,
            "search_volume": 900,
            "avg_position": 4,
            "backlinks": 8
          }
        ]
      }
    ],
    "max_opportunities": 10
  }'

Replace the example domain and estimates with your own exports. The endpoint returns prioritized opportunities, matching owned URLs, competitor coverage, suggested page types, buyer stages, next endpoints, a matrix, and explicit limitations.

At the time of writing, the request costs three AgentSEO credits and does not call a paid SERP provider. Verify current behavior and pricing in the AgentSEO API reference before production use.

The result is a triage layer, not an instruction to publish. The endpoint uses the data you supply. It does not crawl the full web or verify current rankings, and its scores are sorting inputs rather than forecasts.

Validate the top candidates against current search reality

Do not validate every row. Validate the small group you might actually produce.

For each candidate, inspect the current SERP and answer:

Does the query mean what the export suggests?
Which page types are visible now?
Is intent mixed across guides, tools, products, videos, or discussions?
Does an existing owned URL already satisfy the task?
Can you add real proof, a working template, data, screenshots, or a better workflow?
Is there a natural next step into the product?

Search Console can then check owned-page reality. Filter the Performance report by query and page to see clicks, impressions, position, and the URLs currently receiving visibility. Google notes that Performance data is subject to processing and privacy limitations, so use it as observed site evidence rather than a complete record of every query. Read Google's Performance data guide.

If one owned page already receives impressions for the topic, investigate that page before approving a new URL.

Automate sorting, not editorial judgment

Automation is good at repetitive comparison:

owned page export + competitor page exports
                       ↓
normalize topics, page types, and buyer stages
                       ↓
classify and score gaps
                       ↓
human validates audience, intent, proof, and conversion
                       ↓
new-page brief, refresh brief, differentiate, or ignore
                       ↓
human edits and approves publication

Keep the human gate where context changes the decision.

An agent can identify that three competitors have template pages. It cannot infer that your team has original template data, implementation experience, permission to make a product claim, or capacity to maintain the asset. Those constraints determine whether the gap is real for your business.

Common failure modes

Chasing every competitor-exclusive keyword

Competitor exclusivity tells you only that another domain ranks and yours does not. Filter for audience, product, intent, and conversion fit.

Comparing only direct competitors

Direct competitors reveal commercial positioning. SERP competitors reveal what currently satisfies the query. You need both views.

Creating a new page when one already owns the intent

Check Search Console and the existing site before briefing. Refreshing a relevant URL is often cleaner than adding another overlapping page.

Copying the ranking format without checking its usefulness

A dominant format is evidence, not a command. Use a template, video, or tool only when it improves task completion and you can execute it credibly.

Treating a score as predicted traffic

Gap scores compress supplied signals for prioritization. They cannot establish ranking probability, click-through rate, conversion rate, or business value.

Asking an LLM to invent the missing expertise

If the accepted gap requires benchmark data, customer evidence, product screenshots, or implementation experience, collect it. Fluent text is not a substitute for proof.

The publication gate is deliberately small

Approve a gap only when you can answer yes to all five questions:

Does a named AgentSEO audience own this job?
Does the current SERP support the intended task and page type?
Is there no stronger same-intent owned URL to refresh?
Can the page add original proof, experience, or a better working asset?
Is the next product step useful rather than forced?

If one answer is no, the right decision may be to refresh, differentiate, or ignore.

That is the point of the workflow. Competitor research should reduce the content queue, not inflate it.

AgentSEO can turn supplied page exports into a buyer-stage gap matrix, then route accepted opportunities into a content brief or refresh workflow. Start with the API quickstart if you want to make the analysis repeatable through REST or an agent.

Disclosure: This draft was prepared with AI assistance for research organization, drafting, and editing. Daniel Martin should review the claims, examples, links, product details, and final publication decision.

How to Create an SEO Content Brief From Live SERP Data

AgentSEO-dev — Mon, 24 Aug 2026 10:37:53 +0000

A keyword, a word count, and a list of competitor headings is not an SEO content brief.

It is a request for the writer to reverse-engineer the strategy.

That usually produces one of two drafts: a generic article that covers everything around the topic, or a close imitation of the pages already ranking. Both can look complete in a document while failing the actual job of the page.

A useful brief makes five decisions before anyone drafts:

who the page is for
what the searcher needs to do or decide
which page type fits the current result set
what this page will add that competing pages do not
what evidence must exist before a claim can ship

This tutorial shows how to make those decisions from live SERP evidence, turn them into a writer-ready template, and preserve a human review gate when an AI agent helps with the research.

The short answer

Build the brief in this order:

Define the page job and target reader.
Inspect the live SERP for intent, format, features, and competing angles.
Separate required coverage from opportunities to differentiate.
Specify proof, sources, internal links, and the conversion path.
Give the writer an outline with decisions, not a keyword checklist.
Validate the finished draft against the brief and the current SERP.

The output should be specific enough that a writer does not need to repeat the SEO research, but open enough that they can still make the article useful and original.

Start with the page job, not the outline

The same keyword can support several superficially plausible pages.

Take SEO content brief template. You could publish a definition, a downloadable template, a step-by-step tutorial, a software landing page, or a comparison of briefing tools. Those formats do not serve the same reader or buyer stage.

Before opening the SERP, write one sentence:

This page helps [specific reader] do or decide [specific job]
after searching [target query], and the useful next step is [conversion].

For this article, that sentence is:

This page helps technical marketers build a repeatable SEO content brief
from current search evidence, and the useful next step is to run the workflow
manually or with an SEO agent.

This constraint prevents a common briefing failure: adding every related topic until a focused tutorial becomes an unfocused guide.

Google's people-first content guidance asks whether a site has an intended audience, whether a reader will learn enough to achieve their goal, and whether the content adds original information or analysis. It also states that Google does not have a preferred word count. That makes audience, task completion, and added value stronger briefing inputs than a copied competitor average. Read Google's people-first content guidance.

Read the live SERP as evidence, not as an outline to copy

The result page helps answer four different questions.

SERP observation	Decision it supports
Dominant intent	What the searcher is trying to accomplish
Dominant page type	Whether the page should be a guide, comparison, tool, landing page, or something else
Repeated useful coverage	What a credible page probably needs to address
Weak or missing coverage	Where the new page can add something distinct

Review at least the leading relevant results, but do not treat every ranking URL as a model. A marketplace page, video, forum thread, product result, and editorial guide may coexist because the query has mixed intent.

Record what is visible:

result type and page format
likely audience and buyer stage
title promise
questions answered
proof used: examples, screenshots, data, templates, or expert review
freshness requirements
SERP features such as videos, discussions, snippets, or an AI Overview
obvious gaps or repeated weaknesses

The last two fields matter. A brief that only records what competitors include can produce a competent clone. The brief needs a reason for this page to exist.

Recent community discussions expose the same tension. One r/SEO commenter described useful brief fields such as goal, persona, pain point, target keyword, format, metadata, and outline. A newer discussion pushed back on keyword-checklist briefs and argued that writers also need the reader's problem, the decision the page should enable, what current results miss, and natural internal-link opportunities. Treat these as practitioner observations, not ranking factors. See the r/SEO production-framework discussion and the content-brief critique.

Turn observations into three buckets

Do not paste raw research into the writer's document. Classify it.

Required coverage

These are questions a reader reasonably expects the page to answer. Missing them would make the page incomplete for its stated job.

For an SEO content brief tutorial, required coverage might include:

audience and page goal
primary query and intent
page type
title and metadata direction
recommended sections
internal links
sources and proof
draft QA

Required does not mean “every competitor has an H2 with this phrase.” It means the information helps the intended reader complete the task.

Differentiation opportunities

These are useful additions that the current results handle weakly or not at all.

Examples:

a copy-paste brief template
a real API or MCP workflow
explicit failure modes
a proof-requirements field instead of vague E-E-A-T advice
a pre-publish validation gate
a decision rule for mixed-intent SERPs

Write one differentiation sentence in the brief:

Unlike generic templates, this page shows how to convert live SERP observations
into coverage, differentiation, and proof decisions, then validate the draft.

If you cannot complete that sentence without adjectives, the idea probably needs more research.

Exclusions

Good briefs also say what the page should not become.

For this topic:

do not promise rankings
do not prescribe keyword density
do not copy competitor headings
do not invent a universal word count
do not turn the tutorial into a list of content-optimization tools
do not let an agent publish without editorial review

Exclusions reduce revision time because they define the edges of the assignment.

Use a brief template that carries decisions

The following template is deliberately prose-first. It gives the writer context and constraints without writing the article for them.

# SEO content brief

## Assignment
- Working title:
- Primary query:
- Target location and device:
- Intended reader:
- Reader's job to be done:
- Business goal and next step:
- Page type:
- Search intent:

## SERP evidence
- Checked at:
- Dominant result types:
- Important SERP features:
- Repeated questions or expectations:
- Competing angles:
- Evidence used by current results:
- Mixed-intent or freshness risks:

## Editorial direction
- One-sentence angle:
- What this page must cover:
- What this page should add:
- What to exclude:
- Tone and assumed reader knowledge:

## Proof requirements
- Claims that need first-party evidence:
- Claims that need authoritative sources:
- Example, command, screenshot, or dataset required:
- Limitations or uncertainty to disclose:

## Structure
- H1:
- Opening tension:
- Recommended H2/H3 outline:
- Questions that need direct answers:
- Pattern interrupt or decision frame:
- Conclusion action:

## Page elements
- Meta-description direction:
- Internal links and suggested context:
- External sources:
- Image or diagram brief:
- Schema candidate, if supported by visible content:

## Review gate
- Does the draft satisfy the reader's job?
- Does it match the intended page type and current intent?
- Does it add value beyond the sampled results?
- Are material claims supported and limitations explicit?
- Are links useful and natural?
- Has a human reviewed the final judgment?

Notice what is missing: a mandatory keyword density and an arbitrary instruction to write 2,000 words. The writer has a job, evidence, and boundaries instead.

Let an agent collect evidence without handing it editorial control

An agent is useful for repetitive parts of the workflow: reading result patterns, grouping questions, formatting a brief, and checking whether a draft missed an agreed requirement.

It should not silently make irreversible editorial decisions.

A safe workflow looks like this:

target query + reader + page job
                ↓
live SERP evidence
                ↓
agent proposes intent, format, expectations, gaps, and brief
                ↓
human approves the angle, proof requirements, exclusions, and conversion path
                ↓
writer drafts
                ↓
agent checks the draft against the approved brief and current SERP
                ↓
human edits and publishes

With AgentSEO's REST API, a brief request can be expressed as one reproducible call:

curl -X POST "https://www.agentseo.dev/api/v1/content/brief?sync=true" \
  -H "x-api-key: sk_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "how to create an SEO content brief",
    "target": "AgentSEO",
    "audience": "technical marketers and growth engineers",
    "location": "United States",
    "device": "desktop",
    "brand_voice": "expert",
    "page_type": "guide",
    "brief_depth": "detailed",
    "include_serp_outline": true
  }'

The endpoint is designed to return audience guidance, metadata, SERP expectations, competitor patterns, differentiators, proof requirements, a conversion plan, a QA checklist, and an optional outline. It costs six AgentSEO credits at the time of writing. Verify current parameters and pricing in the AgentSEO API reference before building the call into production.

If you use MCP in Claude Code, Codex, or another compatible client, ask for the same boundaries explicitly:

Use AgentSEO to create a detailed content brief for
"how to create an SEO content brief" in the United States.

Audience: technical marketers and growth engineers.
Page type: guide.

Return:
1. dominant intent and page-format evidence,
2. required coverage,
3. differentiation opportunities,
4. proof requirements,
5. exclusions,
6. a writer-ready outline,
7. internal-link opportunities,
8. risks that need human review.

Do not draft or publish the article.

That last instruction matters. Brief creation and article approval are different permissions.

Review the brief before the writer sees it

An automatically generated brief can sound decisive while resting on weak evidence. Review it for four failure modes.

The SERP is mixed

If the result set contains several page types, do not average them into a hybrid page. Choose the reader and job that best fit your product, then record the competing intent as a risk.

The outline is a competitor collage

Repeated headings may reveal expected coverage. They do not justify copying another publisher's structure. Rebuild the outline around the reader's sequence: what they need to understand, decide, do, and verify.

The brief confuses coverage with proof

“Discuss how automation saves time” is coverage. It is not evidence.

A proof requirement would say:

If the article claims time savings, provide a dated test with the manual baseline,
automated workflow, sample size, measurement unit, and limitations.
Otherwise remove the quantitative claim.

The brief optimizes the snippet but forgets the page

Titles matter, but Google generates title links automatically from multiple signals, including the page title, prominent headings, and other page text. Write a descriptive title that matches the page; do not treat one suggested title as a guaranteed SERP output. See Google's title-link documentation.

Validate the draft against the agreement

The final check is not “Did the writer use every keyword?”

Use this review order:

Task completion: Can the intended reader now do or decide the promised job?
Intent and format: Does the draft still fit the target query's current result set?
Original value: Is the differentiating element present and useful?
Evidence: Are important claims sourced, demonstrated, or qualified?
Structure: Can a scanning reader find the direct answer and next step?
Links: Do internal links move the reader to a relevant deeper action?
Restraint: Did the draft avoid the exclusions in the approved brief?

An agent can flag gaps. A human still needs to decide whether the page is accurate, useful, appropriately differentiated, and ready to represent the company.

The brief is successful when the writer no longer has to guess at strategy—and still has room to write.

Start with one page you already plan to publish. Write the page-job sentence, inspect the live SERP, and fill only the fields you can support. If the angle or proof requirement is still vague, do more research before generating prose.

AgentSEO can supply the live SERP and structured briefing steps through REST or MCP. See the workflow guide, API reference, or SEO MCP server guide when you are ready to make the process repeatable.

Disclosure: AI assisted with research organization, drafting, and cover-image creation. Daniel Martin reviewed and approved the editorial direction and publication decision.

How to Catch MCP Tool Schema Drift Before an Agent Calls Production

AgentSEO-dev — Sat, 22 Aug 2026 17:04:06 +0000

Editorial illustration. It explains the concept; it is not experimental evidence.

An MCP server can pass a happy-path demo and still ship a contract change that makes an agent less predictable. A tool name gains a space. An inputSchema disappears during a refactor. A generated list comes back in a different order than the build you reviewed.

The hard part is not writing another unit test. It is deciding what must stay stable before an agent is allowed to discover tools that can touch a real system.

My recommendation is small: validate each tool declaration structurally, then keep a reviewed snapshot of the ordered tool surface. The snapshot is not a substitute for integration tests or human approval. It is a cheap tripwire for a class of deployment drift that ordinary handler tests often miss.

The current MCP tools specification says a tool has a unique name and an inputSchema, and it recommends a deterministic tool order so clients can cache tool lists reliably. It also calls for a human to be able to deny tool invocations. MCP Tools specification

The gate I would put before deployment

Run this after generating or assembling your server's tools/list output, not only against TypeScript types. It checks the payload an MCP client will actually see.

type Tool = {
  name: string;
  inputSchema?: { type?: string } | null;
};

const toolName = /^[A-Za-z0-9_.-]{1,128}$/;

export function assertToolContract(tools: Tool[], approvedNames: string[]) {
  for (const tool of tools) {
    if (!toolName.test(tool.name)) {
      throw new Error(`Invalid MCP tool name: ${tool.name}`);
    }
    if (!tool.inputSchema || tool.inputSchema.type !== "object") {
      throw new Error(`Tool ${tool.name} needs an object-root inputSchema`);
    }
  }

  const names = tools.map((tool) => tool.name);
  if (JSON.stringify(names) !== JSON.stringify(approvedNames)) {
    throw new Error("Tool surface changed: review the ordered tools/list snapshot");
  }
}

This deliberately does not decide whether a tool is safe. It only makes a declared interface change visible. Authorization, output validation, test data, rate limits, and human approval still need their own controls.

A controlled drift study

I generated 240 synthetic three-tool server surfaces, then applied five deliberate mutations to each one: a name containing a space, a missing schema, a null schema, an array-root schema, and a changed tool order. That produced 1,200 injected contract changes.

The study compares two checks:

Check	Caught	Missed	What it misses
Basic name + schema check	960 / 1,200 (80%)	240	Order-only drift
Basic check + ordered snapshot	1,200 / 1,200 (100%)	0 in this study	Semantic or runtime problems

Evidence image generated from the saved deterministic study output. It is a synthetic mutation study, not production telemetry.

The result is not surprising once you define the test: the basic check was not designed to flag order changes. That is exactly the point. If order matters to your clients, deployment review needs to compare it. If it does not, omit that rule and say so explicitly.

The complete method, seed, rows, and limitations are included with this draft in research/mcp-contract-drift-2026-08-22/. Rerun it with:

node scripts/run-mcp-contract-drift-study.mjs

Why an ordered snapshot can be useful

MCP does not turn list order into a universal correctness rule. A client can choose its own behavior. But deterministic declarations reduce accidental churn in a few practical places:

build reviews become smaller because a real surface change is visible;
cached prompts or tool registries do not receive a different ordering for the same server build;
a generated tool list cannot quietly add, remove, or rename an operation without a reviewer seeing the diff.

The specification explicitly recommends deterministic ordering when the underlying set has not changed. Treat that as an operational affordance, not a security guarantee. MCP Tools specification

Keep structural drift separate from behavior drift

One common mistake is to call all of this “MCP testing.” It is only one layer.

Layer	Question	Example evidence
Contract	Did the client-facing declaration change?	`tools/list` snapshot and schema check
Handler	Does the tool reject invalid input safely?	unit tests with invalid payloads
Integration	Does the server negotiate and serve the intended tool?	protocol session test
Authorization	Can the caller perform only allowed actions?	scope and approval tests
Agent behavior	Does a model choose and interpret the tool correctly?	scoped evaluation set

The July 2026 MCP release candidate also describes the move to full JSON Schema 2020-12 for tool input and output schemas. That raises the value of testing the serialized declaration rather than assuming a source type tells the whole story. MCP release-candidate notes

Exact prompt, input, and observed output

For the review step, I use this prompt with a bounded task:

Given this tools/list JSON and the approved ordered-name snapshot, identify only contract drift. Return PASS or a list of changed names, missing schemas, invalid root types, and order changes. Do not recommend calling any tool.

Input: the candidate tools/list payload plus approvedNames from version control.

Observed output from the deterministic run: the structural checker detected 960 of 1,200 mutations; adding the ordered-name snapshot detected 1,200 of 1,200. The agent prompt is a review aid, not a source of truth—the code gate remains authoritative.

Where this approach fails

The study is intentionally narrow. It does not prove that a tool produces the right answer, that a client understands a complex schema, or that authorization is correct. It does not use live servers or real-model task completion. It also treats order drift as relevant by design; a team whose client does not care about order should not manufacture noise by enforcing it.

The more important failure mode is social: a green contract gate can create confidence that nobody has reviewed the action itself. Keep the human approval boundary close to consequential tool calls, as the protocol’s interaction guidance recommends.

Start with the tool surface you already have. Save one reviewed snapshot. Fail the build on unexpected drift. Then add behavior and authorization evaluations where the tool can change customer data, spend money, or ship code.

Disclosure: Human strategy, research design, code review, and editorial judgment led this article. AI assisted drafting and editing.

Google Search Console Content Decay: A Weekly Workflow That Does Not Rewrite the Wrong Pages

AgentSEO-dev — Thu, 20 Aug 2026 08:08:50 +0000

Google Search Console Content Decay: A Weekly Workflow That Does Not Rewrite the Wrong Pages

If a page loses organic clicks, do not immediately rewrite it.

That is the mistake behind most content-refresh backlogs. A decline in Google Search Console can mean the page is stale. It can also mean demand is seasonal, a competitor changed the SERP, another page on your site is competing, or people are getting the answer before they click.

Those are different problems. They need different actions.

This is the weekly workflow I would use to find genuine content decay, decide what is worth refreshing, and keep an AI agent useful without letting it turn every small fluctuation into a rewrite.

The short answer

Use Search Console to find pages with a meaningful decline in clicks, impressions, CTR, or average position. Then diagnose the loss at the page and query level before making a change.

Signal	Likely explanation	First move
Clicks down, impressions and position stable	CTR or SERP-layout change	Inspect title, snippet, and current SERP before rewriting
Impressions and clicks down for a small query set	Intent shift, stronger competitors, or stale coverage	Compare the page against the live SERP
Position down across most important queries	Ranking loss or page-quality gap	Create a focused refresh brief
One page down while a second owned page is up	Cannibalization	Investigate URL ownership before editing
Decline matches the same period last year	Seasonality or lower demand	Monitor; do not manufacture a refresh

The point is not to produce more edits. It is to make the next edit defensible.

Why Search Console is the right starting point

Search Console is first-party evidence of how Google Search exposed your pages. Its Search Analytics data can be grouped by page, query, country, device, and date, with clicks, impressions, CTR, and average position in each row. Google's Search Analytics API documentation is also clear about a limitation worth remembering: results are sorted by clicks and the API does not guarantee every possible row.

That makes it excellent for prioritization, not a substitute for judgment.

Google's own traffic-drop guide makes the same practical point: break a decline down by query, page, country, and device before deciding what changed. It specifically calls out the possibility that higher-ranking pages are newer or better. Read the guide.

The useful unit of work is therefore not:

This URL lost 23% of clicks. Refresh it.

It is:

This URL lost clicks from three non-seasonal commercial queries.
Position declined while impressions stayed useful.
The current SERP now emphasizes comparison tables and implementation detail that the page lacks.

Now you have an actual assignment.

Step 1: Build a small candidate set

Start weekly, not daily. Search data moves, reporting is delayed, and a short time window creates noise.

For a small site, compare the last 28 days against the prior 28 days. For a seasonal business, compare against the matching period last year as well. Keep the first shortlist to 10–20 pages.

I use four filters:

The page had enough prior clicks to matter.
The decline is large enough to be more than routine variance.
At least one important query still has meaningful impressions.
The page is a page we would actually want to improve—not an expired campaign, obsolete documentation, or thin archive page.

This avoids the classic bad backlog: 200 URLs that technically declined, none of which deserves a writer's week.

Step 2: Split the loss into four diagnoses

This is the step most automation skips.

The page still ranks, but clicks fell

If average position is broadly stable while clicks fall, do not assume the content went bad. Check CTR by query and device first.

Possible explanations include a worse title match, a new SERP feature, an AI Overview, ads pushing results down, or a demand shift. A refresh may still help, but rewriting body copy is not the default answer.

The page lost position for a narrow query cluster

This is the best content-refresh candidate. The page has proven that it can earn impressions, but it no longer satisfies the current SERP as well as it used to.

Compare the live results for the lost queries. Look for changes in page format, definitions, proof, freshness, product detail, comparisons, or the questions competitors now answer directly.

The page lost position everywhere

Do not edit until you rule out broader causes: technical changes, indexability, canonical changes, internal-link loss, a major SERP shift, or a domain-level quality problem.

If a page is weak everywhere, a new H2 is unlikely to save it.

Another owned page gained at the same time

That is a cannibalization warning. Two pages may be competing for the same intent, or Google may be reassigning the query to a more suitable URL. Choose the URL that should own the job before changing either one.

Step 3: Give the agent evidence, not a vague command

An AI agent can make this weekly review faster. It should not decide to rewrite pages from a top-level traffic chart.

Give it the comparison export, the candidate URL, the affected queries, and the business context. Then ask it to classify the decline and recommend the smallest useful next action.

Here is a prompt worth saving in your project:

You are reviewing a possible content-decay event.

Inputs:
- URL: {{url}}
- Last 28 days vs previous 28 days: {{gsc_page_metrics}}
- Top declining queries: {{query_comparison}}
- Same period last year: {{seasonality_comparison}}
- Current page summary: {{page_summary}}
- Live SERP notes for the three highest-value declining queries: {{serp_notes}}

First, classify the event as exactly one of:
1. refresh_candidate
2. ctr_or_serp_layout_change
3. seasonality_or_demand_change
4. cannibalization_risk
5. technical_or_indexing_risk
6. insufficient_evidence

Then return:
- evidence for the classification
- the smallest safe next action
- what must be reviewed by a human
- what would falsify the recommendation

Do not recommend a rewrite unless the evidence points to a page-specific
content or intent gap.

The last line is the guardrail. It turns the agent from an eager copy generator into an analyst.

Step 4: Use live SERP evidence only for the winners

Pulling SERP data for every declining URL is a waste of time and credits. Use your Search Console shortlist first, then investigate only the pages that have an actionable query cluster.

A tight workflow looks like this:

Search Console comparison
        ↓
candidate page and query shortlist
        ↓
live SERP + competitor pattern check
        ↓
refresh, consolidate, fix, or monitor
        ↓
human review before any publication
        ↓
same query/page monitoring after the change

With AgentSEO, the first agent call can identify declining or stalled pages, then a narrower workflow can use ranked-keyword, cannibalization, refresh-brief, technical-QA, and SERP-volatility checks only where they are needed. That keeps the model grounded in current search context instead of treating every GSC export as an editorial instruction.

For a tracked keyword and URL, the content-decay endpoint can also make the threshold explicit:

curl -X POST "https://www.agentseo.dev/api/v1/content-decay/detect" \
  -H "Authorization: Bearer $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/seo-api",
    "keyword": "seo api",
    "lookback_days": 30,
    "threshold": 3
  }'

That should create a review candidate, not an automatic publish task. The API's job is to return a consistent signal; the operator's job is to decide whether the signal deserves action.

Step 5: Make a narrow refresh brief

The best refresh briefs do not say "improve the article." They name the delta.

For example:

Keep the existing URL and primary intent.

Add a short comparison table near the top because the current top results
all answer the selection question before explaining implementation.

Replace the 2024 examples with verified 2026 examples.

Add the two missing implementation questions that appear in the current SERP.

Do not expand into a broader beginner guide; that would dilute the commercial intent.

That is an assignment a writer, marketer, or coding agent can execute and review.

What not to automate

Reddit discussions about content decay often collapse into a single rule: declining pages should be refreshed. The better operator question is why did this page decline?

Do not automate these decisions without evidence and approval:

publishing or rewriting a page;
changing canonical tags, redirects, or URL ownership;
treating lower CTR as proof of lower quality;
deleting pages because a short comparison window looks bad;
assuming that an AI-result click loss can be fixed with extra word count.

The agent can detect, compare, summarize, and draft a proposal. A person should approve actions that affect a live URL, brand claim, spend, or measurement history.

A simple weekly operating rhythm

Day	Action	Output
Monday	Compare 28-day page and query data	10–20 candidate URLs
Tuesday	Classify candidates and inspect live SERPs for the best five	Refresh, monitor, consolidate, or technical-investigation decisions
Wednesday	Create narrow refresh briefs	Reviewed work queue
Thursday	Ship approved changes	Before-state record
Following weeks	Monitor the same URL/query/location/device set	Evidence of recovery, no change, or a new diagnosis

Do not mistake consistency for bureaucracy. The point of a weekly rhythm is to create enough history to distinguish a trend from a bad Tuesday.

The practical takeaway

Content decay is not a content-production problem first. It is a diagnosis problem.

Google Search Console gives you the first-party signals. Live SERP intelligence tells you whether the page, the result page, or the market changed. An agent can turn that evidence into a small, repeatable review loop—but it should be designed to recommend the next safe move, not to rewrite everything that turns red.

If you are building this into an agent workflow, start with one page type and one review cadence. Then make the loop reliable before you make it autonomous.

AgentSEO provides the LLM-ready SERP, content-refresh, cannibalization, QA, and monitoring steps for that loop. Start with the workflow guide or the quickstart.

MCP vs REST APIs for SEO Agents: A Practical Decision Framework

AgentSEO-dev — Tue, 18 Aug 2026 16:07:37 +0000

MCP vs REST APIs for SEO Agents: A Practical Decision Framework

If you are building an SEO agent, do not start with the question: “Should this use MCP or REST?”

That framing makes the decision sound like a protocol fight.

It is not.

REST and MCP usually belong in the same system. They serve different callers and different moments in a workflow.

Use REST when your application already knows the operation it needs to run. Use MCP when an AI client needs to discover the available operations and choose among them while working.

For SEO agents, that distinction is practical. A nightly rank-monitoring job is normally a REST job. A Claude Code session that needs to inspect a SERP, find a content gap, and decide what to do next is a good MCP job.

This is the decision framework I use when exposing search intelligence to agents.

The short answer

If your system needs to…	Start with
Run a known job on a schedule	REST
Process a high-volume batch predictably	REST
Power a dashboard, web app, or internal backend	REST
Let Claude Code, Codex, or Cursor discover tools	MCP
Let an agent choose the next SEO action from live context	MCP
Make one capability work across multiple MCP clients	MCP
Support both scripted automation and interactive agents	Both

The useful architecture is not “MCP instead of API.”

It is:

SEO data providers → REST API / job layer → MCP tools → AI clients
                                      └→ scheduled automation / product backend

The API is the dependable execution layer. MCP is the agent-facing interface on top.

What changes when an agent is the caller

A developer calling a REST API has already made most of the decisions.

They know which endpoint to use, which parameters it accepts, what authentication is required, and what the response should look like. Their code can retry, paginate, and branch on an error explicitly.

An AI agent starts somewhere else.

It is often given a job such as:

Find the highest-impact organic growth opportunity for this page.

That is not one API request. The right next action could be SERP analysis, a content-gap check, backlink research, local visibility analysis, or a page QA pass.

MCP gives the client a structured way to ask what tools exist and then call one with typed inputs. The MCP specification defines tools/list for tool discovery and uses JSON-RPC for messages. Its current standard transports are local stdio and Streamable HTTP. MCP tools specification · MCP transport specification

That does not make REST less useful. It means the interface is optimized for a different caller.

A real SEO example: one goal, two interfaces

Say you want to monitor a set of pages for content decay.

REST is better for the scheduled workflow

Your system knows the pages, check frequency, target country, and alert threshold before the job begins.

Every Monday at 08:00:
  for each tracked page
    request the current SERP and ranking data
    compare against the saved baseline
    create an alert only if the threshold is crossed

This needs predictable input, idempotency, job status, retries, and a clean audit trail. A REST API or asynchronous job endpoint is a natural fit.

The model can still be involved later—perhaps to summarize an alert—but it does not need to choose the underlying operation at every step.

MCP is better for the investigative workflow

Now imagine a growth operator in Claude Code sees the alert and asks:

Our /seo-api page lost clicks. Use live search data to find the likely cause,
identify the most defensible page update, and flag anything that needs human review.

The order of operations is not known in advance. The agent may need to inspect the SERP, compare competing page formats, check whether an AI Overview is present, review the target page, then create a content brief.

That is where a focused tool catalog helps.

With AgentSEO, those jobs are exposed through MCP tools for SERP analysis, content gaps, local audits, rank tracking, backlinks, page QA, and AI Overview checks. The client can discover the available tools rather than relying on a human to paste reports between products.

The four questions that make the choice clear

1. Is the next operation known before the workflow runs?

If yes, choose REST first.

A known operation has a stable request shape:

Check keyword positions for these 200 URLs in the United States.

The program already knows the action, parameters, and success condition. An MCP layer adds little by itself.

If no, MCP is a stronger candidate:

Investigate why this page stopped earning qualified organic traffic.

The agent needs to reason over the available tools before it can decide what to call.

2. Does a human need to use the same capability inside an AI client?

If the capability must work interactively in Claude Code, Codex, Cursor, or another MCP client, MCP makes the integration reusable.

Without it, each client tends to need a bespoke wrapper, prompt convention, or function definition. MCP does not remove authentication or product design work, but it does give clients a common discovery and invocation pattern.

3. Do you need high-volume, deterministic execution?

Use REST for the hot path.

Batch keyword collection, large crawls, scheduled refreshes, and usage-sensitive background jobs should remain explicit and observable. Give them ordinary API contracts, queueing, rate limits, retries, and cost controls.

An agent can trigger one of those workflows, but it should not become the scheduler by accident.

4. Is the tool list small enough for an agent to choose well?

This is the MCP question teams skip.

More exposed tools are not automatically better. Every tool name, description, and input schema becomes part of the agent’s choice problem. A long, overlapping catalog makes the agent slower and less reliable.

Before exposing an API operation as an MCP tool, ask:

Is this a complete user job, not merely an internal endpoint?
Can I explain when to use it in one sentence?
Does its input schema prevent common mistakes?
Is it meaningfully different from the other tools?
Would a user recognize its result as actionable?

If the answer is no, keep the operation behind the REST layer for now.

The trap: auto-generating an MCP tool for every endpoint

It is tempting to put an OpenAPI file through a generator and call the result an agent integration.

You may get a working server. You may also get a tool catalog full of low-level actions such as:

create-serp-task
get-serp-task
list-serp-task-results
normalize-serp-result

Those operations can be right inside your backend. They are rarely the right mental model for an agent user.

An agent-facing tool should name the job:

analyze_serp
find_content_gap
audit_local_visibility
create_content_brief

The difference is not cosmetic.

The first list asks the model to understand your internal plumbing. The second list lets it select a meaningful piece of work.

A compact design pattern that works

Start with a REST-backed service layer, then expose a smaller MCP surface for interactive workflows.

Provider APIs
  ↓
Normalization, caching, billing, async jobs, and audit logs
  ↓
REST endpoints for product and scheduled workflows
  ↓
MCP tools designed around user jobs
  ↓
Claude Code, Codex, Cursor, and other AI clients

This gives you a few useful boundaries:

One source of truth for data and billing. Your MCP server should not become a second business backend.
One job model for expensive work. Long-running crawls and bulk checks still need status, retries, and cancellation.
A smaller agent contract. You can improve tool descriptions and schemas without exposing every implementation detail.
A safe place for review. The agent can research and recommend; a person or explicit policy gate can approve external changes.

That last boundary matters. Search workflows can create side effects: publishing pages, modifying metadata, spending API credits, or changing tracking configurations. Make the action that changes the outside world explicit.

The operator checklist

Use this before adding an MCP layer to an SEO API:

Keep your REST API as the stable execution contract.
Pick three to five repeated, interactive jobs for the first MCP release.
Give each tool a clear description, narrow inputs, and an actionable result.
Test the server with a real prompt in the target client—not only an inspector.
Add workflow identifiers and logging before usage grows.
Put approval gates in front of publishing, spending, deletion, and permission changes.
Review tool usage monthly and merge or retire overlapping tools.

For remote servers, follow the MCP transport security guidance: validate origins, use authentication, and avoid exposing a local server broadly by default. MCP Streamable HTTP security guidance

The decision is not MCP or REST

If you are building a product that agents use, REST remains your system contract.

MCP is how you make the useful parts of that contract discoverable and usable when the caller is an AI client.

For SEO work, that usually means:

REST for monitoring, batches, jobs, dashboards, and product backends.
MCP for investigation, tool discovery, interactive research, and agent-assisted decisions.

Use both where they fit.

That is how you avoid building a brittle agent wrapper—and avoid forcing every automation through a conversational interface.

Try the workflow

AgentSEO provides both an API layer and a hosted MCP server for Claude Code, Codex, Cursor, and other compatible clients. Start with one live workflow: inspect a SERP, find the content gap, and decide what to change before you write another page.

How to Add an SEO MCP Server to Claude Code

AgentSEO-dev — Sat, 25 Jul 2026 15:23:20 +0000

How to add an SEO MCP server to Claude Code

Claude Code can already edit files, run commands, and reason through a codebase.

The gap shows up when the work depends on a live external system.

SEO is a good example. If you ask Claude Code to improve a landing page, it can inspect the page and suggest better copy. But it cannot know the current SERP, the competing page formats, the AI Overview behavior, or the backlink context unless you paste that data in.

That is exactly the job MCP is built for.

Claude Code’s MCP docs describe MCP servers as a way to connect Claude Code to external tools, databases, and APIs so Claude can read and act on those systems directly instead of working from copied data.

In this guide, we will add an SEO MCP server to Claude Code and run the first useful prompts.

I will use AgentSEO as the example server because it exposes a hosted Streamable HTTP MCP endpoint and a local npm package. The setup pattern is the important part.

What you get from an SEO MCP server

An SEO MCP server gives Claude Code tool access to live search workflows.

Instead of asking:

Here is a SERP export. Can you summarize it?

you can ask:

Use the SEO MCP server to analyze the SERP for "best seo api" in the United States.
Then identify the search intent and draft a content brief for a comparison page.

The difference is small in wording and large in workflow.

The first prompt makes you the data pipeline.

The second prompt lets Claude Code call the tool directly.

For AgentSEO, the live server card currently lists 45 MCP tools, including SERP analysis, keyword ideas, content briefs, local SEO checks, backlink analysis, rank tracking, and AI Overview extraction.

You can verify that yourself:

curl https://www.agentseo.dev/.well-known/mcp/server-card.json

The hosted endpoint is:

https://www.agentseo.dev/mcp

Before you start

You need three things:

Claude Code installed.
An AgentSEO API key.
A project where you want the MCP server available.

Use a server-side API key. Do not use a browser-restricted key for local agent tooling.

Option 1: add the hosted SEO MCP server

Claude Code supports remote HTTP MCP servers with:

claude mcp add --transport http <name> <url>

For AgentSEO:

claude mcp add --transport http agentseo https://www.agentseo.dev/mcp \
  --header "Authorization: Bearer sk_live_your_key" \
  --header "x-project-id: client-alpha" \
  --header "x-workflow-id: seo-mcp-test"

Replace sk_live_your_key with your AgentSEO API key.

The x-project-id and x-workflow-id headers are optional, but I like adding them early. Once an agent workflow starts making real API calls, traceability matters.

Option 2: add the local npm MCP server

If you prefer a local stdio server, use the npm package:

{
  "mcpServers": {
    "agentseo": {
      "command": "npx",
      "args": ["-y", "@agentseo/mcp-server"],
      "env": {
        "AGENTSEO_API_KEY": "sk_live_your_key",
        "AGENTSEO_API_URL": "https://www.agentseo.dev/api/v1"
      }
    }
  }
}

This is useful when your MCP client expects a local subprocess instead of a hosted HTTP endpoint.

For Claude Code, I would start with the hosted HTTP version unless you have a reason to keep everything local.

Verify the server in Claude Code

After adding the server, open Claude Code and run:

/mcp

Claude Code’s /mcp panel lets you inspect connected MCP servers. It should show the server and its tools.

If the server does not appear:

restart Claude Code
check the API key header
confirm the endpoint URL is exactly https://www.agentseo.dev/mcp
run claude mcp list
run claude mcp get agentseo

The setup is not done until Claude Code can see the tools.

First prompt: analyze a live SERP

Start with one bounded workflow.

Use AgentSEO to analyze the SERP for "best seo api" in the United States.

Return:
1. the dominant search intent
2. the common page formats
3. the SERP features that matter
4. what kind of page I should build
5. three risks before publishing

This is better than asking for “SEO advice.” The prompt names the keyword, location, output shape, and decision you need.

Second prompt: create a content brief

Once the SERP analysis works, ask for something closer to production.

Use AgentSEO to create a content brief for the keyword "seo api for ai agents".

Audience: developers building agent workflows.
Page type: educational comparison page.
Goal: explain when an SEO API should be exposed as MCP tools.

Include:
- search intent
- suggested H2 structure
- entities and subtopics to cover
- internal link ideas
- title and meta options
- what not to claim

The phrase “what not to claim” is important. Agent-generated SEO content gets risky when it turns every tool output into marketing confidence.

Ask Claude Code to preserve the review step.

Third prompt: check AI Overview visibility

If your SEO work touches AI search, use a narrower prompt:

Use AgentSEO to check AI Overview visibility for "best seo api".

Tell me:
1. whether an AI Overview appears
2. what source patterns show up
3. whether AgentSEO or competing pages are citation candidates
4. what page changes would improve citation likelihood

Treat this as directional research, not a magic ranking button.

AI Overview behavior changes. The point is to create a repeatable check, not a one-time screenshot.

Common setup mistakes

The annoying MCP failures are usually small.

Wrong header format

Use:

--header "Authorization: Bearer sk_live_your_key"

Do not paste the header as JSON into the CLI command.

Wrong transport

For the hosted AgentSEO endpoint, use:

--transport http

The MCP spec calls the current HTTP transport Streamable HTTP. Claude Code accepts http in the CLI and also recognizes streamable-http in JSON configuration.

No restart after configuration

If Claude Code was already open, restart it or check /mcp again after adding the server.

Prompt is too vague

This is a bad first prompt:

Improve my SEO.

This is a better first prompt:

Use AgentSEO to analyze the SERP for "best seo api" in the United States and tell me what page type I should build.

MCP gives Claude Code tools. You still need to give it a job.

When not to use an SEO MCP server

Do not use an SEO MCP server for every writing task.

You probably do not need live SEO tools when:

you are editing brand voice
you are cleaning grammar
you are writing internal docs
you already have the source data in the repo
the page is not search-led

Use the server when the decision depends on current search context.

That includes SERP intent, competitor page shape, keyword opportunities, AI Overview visibility, rank tracking, local visibility, or backlink signals.

The operator checklist

Before you call the setup done:

Add the MCP server.
Confirm it appears in /mcp.
Run one live SERP prompt.
Run one production-shaped content brief prompt.
Save the working prompt in your repo or team docs.
Add project/workflow metadata if multiple people will use it.
Decide who reviews the SEO recommendation before it ships.

The last step matters.

An SEO MCP server gives Claude Code fresher context. It does not remove judgment.

The best workflow is not “agent writes, human publishes.”

The better workflow is:

agent gathers live SEO context
agent drafts the recommendation
human checks the tradeoffs
agent helps implement the approved changes

That is where MCP starts to feel useful.

Not as another dashboard.

As a tool layer inside the place where the work is already happening.

Building an SEO MCP server for Claude Code and Codex

AgentSEO-dev — Mon, 20 Jul 2026 16:18:18 +0000

Building an SEO MCP server for Claude Code and Codex

Most SEO APIs were built for dashboards.

That is not a criticism. Dashboards are useful. A marketer opens a report, checks rankings, reviews keywords, exports a CSV, and decides what to do next.

But that is not how work feels inside Claude Code, Codex, Cursor, or a custom AI agent.

Inside an agent workflow, the shape is different. You do not want to stop, open a separate SEO tool, copy data into the chat, ask the model to reason over it, then move back to your editor.

You want the agent to ask for live search data directly.

That is why we shipped AgentSEO as an MCP server.

This post is a practical breakdown of what changed, how the server is installed, and why I think SEO APIs are going to move from dashboard-first products to agent-native workflow tools.

The buyer problem is not only data access

SEO teams already have data.

They have rank trackers, backlink tools, keyword databases, crawl reports, and a growing pile of AI visibility screenshots. The problem is that the data often stops one step before the work.

A typical SEO API gives you a payload.

Then your team still has to answer:

Which result matters?
Which page should we update first?
What is the intent behind this SERP?
What should the writer or developer actually change?
Is this useful for an agent, or does it need another parser layer?

That last question is the one more API teams should ask.

If the output still needs a parser layer, a polling layer, and a summarization layer before an agent can act, the API is not finished for agent workflows.

What an SEO MCP server should do

MCP gives clients a standard way to discover and call tools. The official MCP registry describes itself as a list of MCP servers for clients, like an app store for MCP servers.

That matters because the install surface is moving closer to the place where developers already work.

For SEO, I do not think the best MCP server is just a thin wrapper around raw endpoints. That is a start, but it misses the point.

A useful SEO MCP server should expose workflow-shaped tools.

Instead of only returning raw SERP data, it should help an agent do jobs like:

analyze SERP intent
find content gaps
draft a content brief
check local visibility
review title and meta opportunities
inspect AI Overview presence
identify backlink opportunities
QA a draft before publishing

The agent should be able to move from question to action without making the user become the integration layer.

What we built into AgentSEO

AgentSEO now exposes 45 MCP tools for live SEO workflows.

The tools cover:

SERP analysis
keyword research
content briefs
content refresh briefs
backlink analysis
rank tracking
local SEO checks
sitemap and technical QA
AI Overview extraction
AI search visibility monitoring

The important part is not the number. A big tool count can become noise fast.

The important part is that the tools map to repeatable SEO jobs. A developer, growth engineer, or technical SEO should be able to give the agent a real task and get back something useful enough to act on.

Example:

Use AgentSEO to analyze the SERP for "best seo api" in the United States.
Identify the dominant intent, list the strongest competing angles,
and create a content brief for a comparison page.

That is different from:

Fetch the SERP payload and make me figure out the rest.

The second version is data access. The first version is closer to workflow infrastructure.

Install path: hosted MCP

For clients that support remote MCP servers, AgentSEO can run over hosted Streamable HTTP.

claude mcp add --transport http agentseo https://www.agentseo.dev/mcp \
  --header "Authorization: Bearer sk_live_your_key" \
  --header "x-project-id: client-alpha" \
  --header "x-workflow-id: nightly-refresh"

The extra headers are optional workflow metadata. I like keeping them in the example because production agent workflows need traceability. When an agent calls a paid or rate-limited API, you eventually want to know which project and workflow made the call.

Install path: local stdio MCP

For local MCP clients, the npm package works through stdio.

{
  "mcpServers": {
    "agentseo": {
      "command": "npx",
      "args": ["-y", "@agentseo/mcp-server"],
      "env": {
        "AGENTSEO_API_KEY": "sk_live_your_key",
        "AGENTSEO_API_URL": "https://www.agentseo.dev/api/v1"
      }
    }
  }
}

That gives teams a clean local path without forcing every client through the hosted endpoint.

The GTM lesson: MCP directories are becoming agent app stores

The product work was only half the launch.

The other half was distribution.

If you ship an MCP server and only mention it in your docs, you are making discovery too hard. Developers are already browsing MCP directories to find tools their agents can use.

For AgentSEO, we published or submitted to:

Surface	Status
Official MCP Registry	Live as `dev.agentseo.www/agentseo-mcp`
npm	Live as `@agentseo/mcp-server`
Smithery	Live, 45 tools detected
Glama	Hosted connector live, 45 tools verified
mcp.so	Submitted
awesome-mcp-servers	PR submitted
PulseMCP	Waiting on official registry sync
MCP Market	Submitted
MCP Server Spot	Submitted

This is the new shelf space.

Not all of it will convert. Some directories will send little traffic. Some will take weeks to index. Some will matter mostly as trust signals.

But the intent is unusually clean.

Someone browsing an MCP directory is not vaguely interested in AI. They are looking for a tool their agent can install.

That is a better starting point than most launch traffic.

The product lesson: expose jobs, not endpoints

This is the part I would underline for any API company.

Do not start by asking, "How do we expose every endpoint through MCP?"

Start with a smaller question:

What are the 5 jobs an agent should be able to complete without leaving the workflow?

For an SEO API, those jobs might be:

Analyze a live SERP.
Find keyword or content gaps.
Create an implementation-ready brief.
QA a draft before publishing.
Track whether visibility moved.

That is enough for a useful first version.

The raw endpoint map can come later. If you start with the endpoint map, you risk shipping a server that is technically complete and practically annoying.

A simple checklist for API teams

If you are thinking about turning your API into an MCP server, I would start here:

Pick one user: developer, agency operator, growth engineer, analyst.
Pick one repeatable workflow.
Expose the few tools needed to complete that workflow.
Make the install command copy-pasteable.
Publish to the official MCP registry.
Add one directory listing where your buyers already browse.
Test with a real prompt, not only a protocol inspector.

The inspector can tell you the server works.

A real prompt tells you whether the product works.

The larger shift

APIs used to feed dashboards.

Now they can feed agents.

That does not make dashboards obsolete. It does mean API products need a second interface: one designed for software agents that can plan, call tools, inspect results, and continue the workflow.

For AgentSEO, MCP is that interface.

The bet is simple: if AI agents are where more technical SEO and growth work happens, then SEO infrastructure should be available inside those agents.

Not as a pasted export.

As a tool the agent can actually use.