MCP Tool Reference

Twenty-five tools in four groups: orientation, data reads, keyword research, and Edge SEO authoring. Most take a websiteId from list_websites.

Shared arguments

The data and keyword research tools share these scope, window, and crawl arguments, and list_reports and get_report use the window and crawl ones. list_websites, list_crawls, list_issue_catalog, query_alerts, and the Edge SEO tools take only their own arguments.

Argument	Meaning
websiteId	Required. The website to read, from list_websites.
segmentId	Optional. A saved segment from get_schema. It applies the segment's own URL rules, so numbers match what the dashboard shows for that segment.
days	Optional. A rolling window ending today. Default 90, maximum 90.
from + to	Optional. An absolute window, YYYY-MM-DD. Pass both or neither, never with days. The span cannot exceed 90 days.
crawl	Optional. Which Evergreen Crawl snapshot the crawl data reads: "latest" (default), "previous", or a crawl ID from list_crawls.
window	Optional. Pass "crawl" to take the span from the selected crawl, so search numbers cover the days the crawl covered. Never with days or from / to.
vs	Optional. The crawl to compare the selected one against: "previous" or a crawl ID. Only crawls with the same bot scope, target dimension, and window length compare.

A result states the span each source actually read in source_window. Search Console publishes with a lag of a few days, so its span can end earlier than the one you asked for. A result that read a crawl names it in resolved_crawl.

Orientation

Start here on an unfamiliar site. These tools return the numbers the dashboard already computes. Rebuilding the same numbers from query aggregations costs more calls and can land on different values.

list_websites

Lists the websites your account can access, with their IDs and domains.

list_crawls

Every readable Evergreen Crawl snapshot of the site, newest first, and which one a call without a crawl argument reads. Each row carries its kind (current, monthly, or custom), status, window, bot scope, stored totals, whether it holds page, link, and redirect data, and comparableTo: the crawl IDs that vs accepts for it. Takes only websiteId.

list_reports

The catalog of reports the dashboard draws, addressable by key. Without a report argument it returns one line per report and a starter list of provider keys that orient you on a new site in one get_report call. With report, it returns that report's providers in full: the question each one answers, its payload shape, what the site needs for it to run, and where a naive reading of it goes wrong. A report the site cannot answer is listed with the reason.

get_report

Runs up to 20 report providers in one call and returns their computed payloads, the same numbers from the same cache the dashboard uses. Pass providers as exact "<report>.<provider>" keys from list_reports.

Argument	Meaning
providers	Required. 1 to 20 provider keys.
bot	For bot-scoped reports: googlebots, bing, or ai_bots.
url	For page-level reports: the page they answer about.
maxResultBytes	Per-result size cap, up to 100,000 bytes.
deadlineMs	Time budget for the whole batch, up to 30,000 ms.

It also takes segmentId and the window and crawl arguments above.

Each result comes back with a status: ok, unavailable (the site cannot answer this yet, with the reason), failed, not_run (the deadline hit first), or too_large (read the rows through query or export instead). Each result also carries its own window, crawl, and scope.

list_issue_catalog

The crawl issue checks with their definitions: ID, title, severity, category, what each check needs to run, and the checks it takes pages from. Narrow with ids, category, or severity (P0 to P3); naming ids returns their evidence columns and fix guidance in full. These are checks, not findings. What fired on a crawl comes from get_report on crawl_issues.catalog.

site_configuration

How the site is configured to serve bots: which dimension answers a request and whether it renders or bypasses, which query parameters are stripped before the cache key is computed, the cache TTLs, and the date range the event log covers. Read it before explaining cache hits, cache misses, or duplicate URLs, since those depend on settings the event rows do not carry.

Data reads

get_schema

The site's data catalog: the complete query grammar with worked examples, the grains, the exact field names and types per grain, the site's custom extraction fields with coverage and sample values, its saved segments, the named query classes, and the resolved date window and crawl. Pass grain (a name, a list, or "all") for full per-field descriptions. Call it before authoring queries: clients may truncate tool descriptions, but the grammar key is always complete.

query

The one structured read. Takes a JSON relation tree (ir) over bot requests, the per-page SEO digest, Evergreen Crawl pages, links, redirects, issues and crawl-to-crawl changes, sitemap URLs, and Search Console, with filters, aggregation, derived columns, and joins between them. See the query guide.

Argument	Meaning
ir	Required. The relation tree.
limit	Rows per page: up to 50 for a row listing, up to 200 for a group listing. Default 50.
cursor	The cursor from the previous page of a row listing.
count_only	Return only the total, no rows.

export

The same ir, written to a CSV file instead of bounded rows. query's row caps protect the conversation; export hands over a full result set, up to 1,000,000 rows (maxRows). The top-level node must be a select or an aggregate, and its fields become the CSV columns. order and limit nodes work at every grain here. Returns a temporary signed downloadUrl that needs no sign-in, with its expiry in expiresAt. One export runs per account at a time; repeating an identical call joins the export already running.

path_tree

Orientation on the site's URL hierarchy: path sections with distinct URL counts, bot fetch volume, and Search Console clicks and impressions. Drill down with parent_path (for example "/blog/") and depth (1 to 5). The tree is built from the event log, so a URL no bot requested in the window is absent.

cannibalization_detail

Keywords where several of your URLs compete, grouped into clusters. Each cluster gets a severity score from 0 to 100 and a pattern: Simultaneous (the URLs rank together), Blinking (they alternate day to day), or Mixed. Clusters that look like regional or hreflang variants are flagged. Narrow with url_pattern (an SQL LIKE pattern such as "%/blog/%"), min_severity, type_filter, and include_regional.

query_alerts

The site's alert rules (scope: "rules") or the history of fired alerts (scope: "history").

read_page

The one live read. It works in two modes:

• Body mode (no selectors): the page content as markdown or html, for any domain, so competitor pages work too. For your own pages, the page comes back as EdgeComet serves it to bots, with the status code, how it was served, cache age, and redirect target. Pass extract with a short instruction to get a focused extraction instead of the full body.
• Element mode (selectors): the elements matching CSS selectors, for your own pages only. It returns the runtime DOM with the site's active Edge SEO rules applied, which is the markup to write new selectors against.

For a page's stored SEO data as bots received it, use query on the events_page grain instead.

Keyword research

Tool	Returns
serp_check	The live Google organic results for one keyword, SERP features, People Also Ask questions, related searches, and optionally the AI overview with the domains it cites.
ranked_keywords	The keywords a domain or URL ranks for, with position, search volume, and estimated traffic value.
keyword_expand	New keywords from seed terms, in ideas, suggestions, or related mode, with volume, difficulty, and intent.
keyword_metrics	Volume, CPC, competition, difficulty, intent, and monthly trend for up to 300 keywords in one call.
keyword_gap	Keywords a competitor ranks for that your site does not, or the ones you share (mode: "shared").
find_competitors	Domains that compete with you in Google, found from seed keywords or from a domain.
backlink_summary	A domain's or URL's backlink profile: backlinks, referring domains, dofollow split, spam score, broken backlinks.

Results default to the United States and English; pass location_code and language_code for other markets. ranked_keywords, keyword_expand, keyword_gap, and find_competitors return a 25-row sample.

These tools buy live third-party data and draw on a daily per-site budget. Use them deliberately rather than in loops. When the budget is exhausted, the tools say so and reset the next day.

Edge SEO authoring

Author on-page changes as draft rules from the conversation. The Edge SEO tools need the Edge SEO module on your account. The intended order:

1. read_page with selectors (or format: "html"): write CSS selectors against the page's real markup, not from memory.
2. preview_edge_seo_changes: dry-run the changes for one URL on top of the site's active ruleset and get back a diff of what changed and which rules did not apply.
3. save_edge_seo_drafts: store drafts for up to 20 URLs in one call. Each saved URL returns a ruleId and a previewUrl that renders the draft as a full page for a human to review, and the call returns the batchId they were grouped under.

Each URL takes up to 20 modifications. A modification selects elements with a CSS selector and applies one action:

Action	What it does
modify	Edits an element's text, an attribute, or its HTML, through steps: set, prepend, append, find_replace, regex_replace, truncate.
entries	Manages a set of link[rel="alternate"][hreflang] or link[rel] tags, replacing or merging them.
insert	Adds an HTML fragment before, after, or inside the selected element.
remove	Deletes the selected elements.
remove_attr	Deletes an attribute.

Values can use variables such as {title}, {h1}, and {url_path}. Rules that write raw markup, the insert action and the html / outer_html targets of modify, work only on sites where raw HTML editing is enabled.

Read back with list_edge_seo_rules (the ruleset with status counts, or only the drafts of one batchId) or get_edge_seo_draft_status (one rule by ID, including its deploy time once deployed). Discard a draft you authored with delete_edge_seo_draft; it cannot remove active or archived rules, or rules a person created.

Drafts never go live from this surface: a human reviews and deploys them in the dashboard. There is deliberately no publish tool.

Read-only tools

Twelve tools carry MCP's read-only hint, so a client can run them without asking you each time: the six orientation tools, get_schema, query, path_tree, cannibalization_detail, query_alerts, and list_edge_seo_rules. The rest do not:

• export, which writes a file.
• read_page, which fetches a live page and can pay for an extraction.
• The keyword research tools, which spend the site's budget.
• The Edge SEO tools other than list_edge_seo_rules.

How a client uses the hint depends on the client and your settings.