Tool Reference

All 70 VitalSentinel MCP tools across 15 modules, what each one answers, and the scope it requires. 55 are read-only and 15 need write or run.

70 tools across 15 modules. 55 are read-only; the other 15 need a write: or run: scope and only appear when your credential carries one. A browser sign-in requests every scope the server uses, so an approved OAuth connection reaches all 70. An API key reaches only what its own scopes cover.

You do not call these by name. Ask the assistant a question and it picks. The names are here so you can be specific when you want to be, and so you can tell what a connection can reach.

A tool you cannot use is not shown at all, rather than shown and failing. If something below is missing from your connection, your credential lacks the scope, or the workspace role of whoever created the credential strips it. See Scopes.

Start here

Tool	Scope	What it answers
`list_workspaces`	`read:workspaces`	Which workspaces this connection can reach, with plan and domain count
`list_domains`	`read:domains`	Turns a hostname someone mentioned into the `domain_id` every other tool needs
`get_domain_health`	`read:domains`	Cross-module snapshot: RUM, CrUX, synthetic, indexing, robots.txt, analytics, uptime, and Search Console, each against the preceding period
`get_domain_overview`	`read:overview`	Eight-module summary over a fixed 28-day window, with a previous-period comparison
`get_credit_balance`	none	Remaining API credits for one workspace, for the current billing cycle. Takes an optional `workspace_id`

get_credit_balance and list_credit_balances are the only tools with no scope requirement, so they are always available. A workspace that has run out of credits still has to be able to read the balance that explains why.

Credits are charged to the workspace whose data a tool read, so a connection covering several workspaces spends from a separate allowance for each. When a tool is refused, ask for the balance of the workspace that owns the domain in question: the connection's default workspace may still have plenty left while the one you were reading is empty.

get_domain_health is the right first call for "how is this domain doing". It compares every configured module against the prior period, and it is the only one of the two with a freshness control: it accepts freshness: "live" to bypass the cache and recompute, and it reports cache_age_seconds so the assistant can tell you how stale an answer is.

get_domain_overview has no freshness override, so it is the wrong tool for a time-sensitive question. For "is the site up right now", ask for get_domain_health with live freshness, or get_uptime_status, which is never cached.

Performance: Core Web Vitals

Tool	Scope	What it answers
`get_core_web_vitals`	`read:crux`	Current vitals from either Google's public CrUX dataset (`source: "crux"`) or your own real-user data (`source: "rum"`)
`get_vitals_timeline`	`read:crux`	Vitals over time. CrUX gives weekly buckets up to 36 months; RUM gives your chosen granularity up to 540 days
`get_crux_comparison`	`read:crux`	CrUX vitals across two date windows, with the percent change in each metric's 75th-percentile value. Lower is better here, so a negative change is an improvement
`manage_crux_urls`	`write:crux`	List, add, or remove URLs monitored for CrUX field data

CrUX and RUM are not directly comparable, and the assistant is instructed to say which one it is quoting whenever the two disagree. CrUX is what real Chrome users experienced across the web; RUM is what your own visitors experienced.

Performance: real user monitoring

Tool	Scope	What it answers
`get_rum_overview`	`read:rum`	Domain-wide aggregate: event, session, and error counts, average and 75th-percentile vitals, and the good, needs-improvement, and poor distribution
`get_rum_pages`	`read:rum`	Per-page 75th-percentile LCP, INP, and CLS. Pass `failed_only` to see just the pages failing a threshold
`get_rum_geography`	`read:rum`	Real-user vitals broken down by country, with session counts. The only vitals tool carrying a country dimension
`get_rum_errors`	`read:rum`	JavaScript errors: message, stack trace, filename, URL, and the DOM element involved
`get_rum_error_groups`	`read:rum`	The same errors grouped by message, with occurrence and affected-session counts per group, rather than one row per occurrence
`get_rum_error_breakdown`	`read:rum`	Every combination of error type, device type, and browser, with a ready-summed rollup for each of the three on its own
`get_rum_engagement`	`read:rum`	Total interactions, clicks, and the scroll depth reached by 50% and 90% of sessions
`check_rum_data`	`read:rum`	Whether the RUM script has ever reported anything for one domain. The reliable answer to "is tracking live here"
`check_rum_data_bulk`	`read:rum`	The same check for every domain in a workspace, in one query rather than one call per domain

RUM results here are redacted more strictly than the dashboard: no session identifiers, query strings stripped from URLs, and email-shaped and token-shaped substrings replaced in error text. See Conventions.

Availability: uptime and SSL

Tool	Scope	What it answers
`get_uptime_status`	`read:uptime`	Is this domain up right now. Always live, never cached
`get_uptime_availability`	`read:uptime`	Uptime percentage and mean response time over one window, as a single figure weighted by the number of checks
`get_uptime_timeline`	`read:uptime`	Check history over a range, bucketed from 30 seconds up to a month
`list_incidents`	`read:uptime`	Downtime incidents, newest first, filterable by error class (5xx, 4xx, timeout, DNS, TLS)
`get_ssl_status`	`read:ssl`	Certificate status, days until expiry, and any chain, HSTS, or OCSP issues
`list_expiring_certificates`	`read:ssl` and `read:domains`	Certificates expiring soon across a workspace, with a fleet-wide HSTS and chain-validity rollup. Slower than the others: it costs one to two API calls per domain scanned

Availability: synthetic monitoring

Tool	Scope	What it answers
`list_synthetic_tests`	`read:synthetic`	URLs configured for lab-based Lighthouse testing, with their latest mobile and desktop scores
`get_synthetic_results`	`read:synthetic`	Run history, or full audit and opportunity detail for one run when given a `test_id`
`get_synthetic_overview`	`read:synthetic`	Performance, accessibility, best-practices, and SEO scores plus Core Web Vitals, averaged over the trailing 28 complete days with a trend against the preceding 28
`get_synthetic_opportunities`	`read:synthetic`	The improvement opportunities that recur across recent runs, ordered by typical saving, rather than whatever one run happened to find
`compare_synthetic_periods`	`read:synthetic`	Average performance score across two windows you choose, with the percent change between them
`manage_synthetic_url`	`write:synthetic`	Add, remove, or reconfigure monitored URLs, including frequency and test locations

Search: Google Search Console

Tool	Scope	What it answers
`get_search_performance`	`read:gsc`	Total clicks, impressions, average click-through rate, and average position over a range
`get_search_pages`	`read:gsc`	Performance by page, ranked by clicks
`get_search_queries`	`read:gsc`	Performance by query, ranked by clicks
`get_search_devices`	`read:gsc`	The same four metrics split across desktop, mobile, and tablet in one call
`get_search_countries`	`read:gsc`	The same four metrics by country, ranked by clicks, so you can see which markets drive search traffic
`get_search_ctr_benchmark`	`read:gsc`	Actual click-through rate against the rate expected at this domain's own position distribution, and the gap between them
`run_search_report`	`run:gsc`	Runs a registered report by key: click-through-rate curve, cannibalization, content decay, traffic anomalies, opportunity scoring, topic clusters, and vitals versus rankings
`manage_search_experiment`	`write:gsc`	List, create, update, or delete a before-and-after experiment on control versus variant URLs

Search Console data typically lags two days, so end_date defaults to two days ago rather than today. An assistant asking for "yesterday" will correctly get nothing.

Search: indexing

Tool	Scope	What it answers
`get_indexing_status`	`read:indexing`	Coverage by submitted sitemap: submitted versus indexed counts, errors, warnings, and the coverage percentage
`list_indexing_issues`	`read:indexing`	URL-level inspection results, filterable by kind: canonical conflict, rich-result failure, noindex, page with redirect, crawled but not indexed, discovered but not indexed, or a stale crawl at 30, 60, or 90 days
`manage_priority_urls`	`write:indexing`	List, add, or remove priority URLs for inspection. Capped at 200 per domain

Both read tools need a linked Search Console property. If gsc_linked comes back false, the counts are zero because nothing is connected, not because nothing is indexed.

Traffic: web analytics

Tool	Scope	What it answers
`get_analytics_overview`	`read:analytics`	Visitors, sessions, pageviews, bounce rate, and the top five pages, sources, and countries, each against the preceding period
`get_top_pages`	`read:analytics`	Top pages by traffic, entry pages by session entries, or exit pages by session exits
`get_traffic_sources`	`read:analytics`	Breakdown by UTM source, medium, channel, and referring domain
`get_audience_breakdown`	`read:analytics`	Device type, browser, OS, and country
`search_events`	`read:analytics`	Custom events fired by your own instrumentation, with counts and property-key frequencies
`get_ecommerce_summary`	`read:analytics`	Revenue, orders, conversion rate, the product-view-to-purchase funnel, and top products
`run_analytics_report`	`run:analytics`	Runs a registered web analytics report by key
`manage_funnel`	`write:analytics`	Create, update, or delete a funnel of 2 to 5 pageview or event steps
`manage_experiment`	`write:analytics`	Create, update, or delete a before-and-after experiment
`evaluate_experiment`	`run:analytics`	Computes effect size and statistical significance for an experiment's windows

Technical SEO: robots.txt

Tool	Scope	What it answers
`get_robots_status`	`read:robots`	When robots.txt was last fetched, its HTTP status and size, and the fetch success rate over seven days
`get_robots_txt`	`read:robots`	The full raw body most recently fetched, plus rule-set errors and warnings
`test_robots_url`	`read:robots`	Whether one URL is allowed for one user agent, and which rule line matched
`list_robots_changes`	`read:robots`	Change history, newest first, with lines added, removed, and modified. Defaults to the last 90 days
`list_ai_bot_rules`	`read:robots`	What robots.txt currently does to each known AI crawler, with the vendor, what the bot is for, and which rule decided. It also returns ready-made snippets for common policies
`manage_robots_annotation`	`write:robots`	Add, update, or remove a note on a change, for example "intentional block of /staging"

manage_robots_annotation annotates changes inside VitalSentinel. Neither it nor the snippets from list_ai_bot_rules can edit the robots.txt file on your server.

Technical SEO: sitemaps

Tool	Scope	What it answers
`get_sitemap_status`	`read:sitemap`	Total URLs discovered, when the last scan ran and how it went, and whether a new scan can start
`list_sitemap_urls`	`read:sitemap`	Full paginated export of every discovered URL
`get_sitemap_conflicts`	`read:robots`	Sitemap URLs that robots.txt currently blocks
`recompute_sitemap_conflicts`	`write:robots`	Forces a fresh conflict check. Always asynchronous: returns a job identifier, not the conflicts

get_sitemap_conflicts reads a stored result, which the backend is meant to recompute whenever robots.txt or the sitemap changes, though that has not always fired. recompute_sitemap_conflicts forces that check to run again, so read get_sitemap_conflicts a few minutes later for the outcome. It takes write:robots rather than a run: scope because repeating it is harmless: each run fully overwrites the stored result, so a retried or duplicate call cannot corrupt or duplicate anything, and the server sends an idempotency key so a retry does not queue a second recompute.

It re-diffs the sitemap URLs already stored against the current robots.txt, and it does not fetch a fresh sitemap. So it clears a check that lagged behind a sitemap already on file, but not staleness caused by an old underlying scan.

Operations: alerts and notifications

Tool	Scope	What it answers
`list_alert_rules`	`read:alerts`	Configured rules for one domain, or for every domain this connection can reach: metric, condition, threshold, and current evaluation state
`list_alerts`	`read:alerts`	Fired alert notifications, newest first, for one domain or across every domain this connection can reach
`get_alert_trend`	`read:notifications`	The metric trend around one fired alert: data points, unit, threshold, and the exact breach point
`manage_alert_rule`	`write:alerts`	Create, update, or delete a rule
`mark_notification_read`	`write:notifications`	Marks one notification as read

Workspace members keep write:alerts and write:notifications, because an alert rule and your own read state belong to you rather than to shared workspace configuration.

Operations: reports and credits

Tool	Scope	What it answers
`list_report_templates`	`read:reports`	Templates configured for a domain
`manage_report_template`	`write:reports`	Create, update, or delete a template of 1 to 20 sections. Admin or owner only
`generate_report`	`run:reports`	Starts rendering a PDF. Always asynchronous: returns a job identifier, not a file
`get_credit_balance`	none	Remaining credits for one workspace, for the current cycle
`list_credit_balances`	none	One balance per workspace this connection can reach, each on its own cycle, plus an account-wide total

Report templates are shared domain configuration, so they need admin or owner, unlike alert rules.

Every run: tool sends a deterministic idempotency key, so a retry maps to the same record instead of spending twice.

How results are shaped

Three rules apply to every tool result, and they are worth knowing because they change what you can trust:

Truncation is always announced. A tool result is capped at 15,000 tokens. When a list is cut, the result says so explicitly, in the form showing 50 of 1,240 pages, along with what to do about it: the cursor to continue where the tool has one, and otherwise the date range or filter to narrow before asking again. This is the opposite of the dashboard's rule, and deliberately so: a person can scroll a report and see there is more, but a model handed 50 of 1,240 rows with no notice will state a wrong total with complete confidence.

Dates and units are absolute, never relative. Every timestamp is full ISO-8601 UTC or YYYY-MM-DD. An assistant asked to reason about "three days ago" would misdate it against its own idea of now.

Percentiles are spelled out. Any prose the server writes says "75th percentile" rather than "p75", so it cannot be misread as a field name or a typo.