Tool Reference
All 123 VitalSentinel MCP tools across 18 modules, what each one answers, and the scope it requires. 105 are read-only and 18 need write or run.
123 tools across 18 modules. 105 are read-only; the other 18 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 123. 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, Search Console, and Site Health Monitoring, each against the preceding period |
get_domain_overview | read:overview | Cross-module summary over a fixed 28-day window, with a previous-period comparison. It includes Page Monitoring and Site Health Monitoring |
get_url_overview | Any module read: scope, or read:overview | Everything VitalSentinel knows about one URL, right now, from every module the connection can read. 5 credits, and a cached answer costs 0 |
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.
A module block in either result is null when the module is not set up for the domain. Null does not mean healthy.
get_url_overview answers "tell me everything about /pricing". Each section of the result has a status, so a module that the connection cannot read shows not_in_scope, not empty data. See URL Overview.
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 16 months; RUM gives your chosen granularity up to 496 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_timeline | read:gsc | The same four metrics as a daily series, one point per calendar day, for answering when a change happened |
get_search_new_rankings | read:gsc | Queries or pages that picked up impressions in the range and had none in the preceding range of the same length |
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_top_authors | read:analytics | The authors credited on your pages ranked by reads, with readers, articles, active time, scroll depth, and read rate |
get_author_articles | read:analytics | The articles one author is credited on, most read first, with the co-authors each one is shared with |
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 | The number of URLs in the sitemaps now, the latest daily check, and when the next check is due |
list_sitemap_urls | read:sitemap | Full paginated export of the sitemap URLs: the URLs in the sitemaps now, the removed URLs, or all |
get_sitemap_scan_summary | read:sitemap | One daily check: URLs listed, new, removed, back, and changed lastmod, and whether the check was complete |
list_sitemap_checks | read:sitemap | The history of the daily checks |
list_sitemap_changes | read:sitemap | The URLs that changed between checks. 5 credits |
get_sitemap_change_summary | read:sitemap | Net changes over the last 7 days, or between two checks (5 credits) |
list_sitemap_files | read:sitemap | The sitemap files and the result of each download |
get_sitemap_file | read:sitemap | One sitemap file, with its downloads and URL count over time |
list_sitemap_hosts | read:sitemap | The hosts in the sitemap URLs, up to 200 |
get_sitemap_url_history | read:sitemap | One URL: whether it is in the sitemaps, which files list it, and its history |
list_sitemap_sources | read:sitemap | Where each sitemap was found: robots.txt, Search Console, /sitemap.xml, or a sitemap index |
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. 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 sitemap check. Sitemap Monitoring reads the sitemaps again every 24 hours.
VitalSentinel checks sitemaps automatically every 24 hours. No tool can start a check. See Sitemap Monitoring.
Technical SEO: site health
These tools answer for a domain with Site Health Monitoring. The first four tools also work for Page Monitoring, because the two modules share issues and stored page versions.
| Tool | Scope | What it answers |
|---|---|---|
get_crawl_overview | read:pages or read:site_health | Summary for Site Health Monitoring or Page Monitoring: status, open issues, coverage, and recent site changes |
list_crawl_issues | read:pages or read:site_health | Issues by module, status, and date. It also gives one issue with its evidence (5 credits), and the pages a Site Health issue affects |
get_page_version | read:pages or read:site_health | The stored versions of a page, one version, a comparison of two versions, or the stored HTML (5 credits for the first part) |
manage_crawl_issue | write:pages or write:site_health | Act on an issue: acknowledge (Mark as seen), ignore (Snooze…), accept_baseline (This is normal…) or reopen. Owner or admin only |
get_site_health_sample | read:site_health | The pages Site Health Monitoring checks, and why a page is checked or not |
get_crawler_access | read:site_health | Whether the crawler can reach the site, AI bot access, and what AI crawlers can read. Server log figures need read:logs |
get_site_health_settings | read:site_health | The settings, pinned URLs, ignore rules, and detected site changes |
No tool can change the Site Health Monitoring settings or start a check. Your plan sets how often pages are checked. To change the settings, use the dashboard.
Technical SEO: page monitoring
These tools answer for a domain with Page Monitoring. The shared tools in Technical SEO: site health also work with read:pages.
| Tool | Scope | What it answers |
|---|---|---|
list_watched_pages | read:pages | The watched pages, with status, last change, and changes in the last 7 days. Search Console clicks need read:gsc |
list_page_changes | read:pages | The changes found on watched pages, one change in full, and its search impact |
get_page_monitoring_settings | read:pages | Plan limits, ignore rules, custom page elements, and the migration check summary |
manage_watchlist | write:pages | Watch one page or up to 500 pages, change a watched page, stop watching it, or resume it. Owner or admin only |
run_page_check | run:pages | Check a watched page now. 25 credits. Owner or admin only |
run_page_check uses the same hourly allowance as the Check now button in the dashboard. A retry in the same two-minute period returns the same check and does not spend again.
Technical SEO: server logs
All 27 need read:logs and only answer for a domain with Server Log Monitoring connected. None can connect a log source or start a collection run.
| Tool | Scope | What it answers |
|---|---|---|
get_log_overview | read:logs | Hits over time by bot category, the HTTP status mix and totals |
get_bot_activity | read:logs | Per-bot table: hits, share, verification rate, response time and status breakdown |
get_bot_categories | read:logs | The same activity rolled up by bot category |
get_crawled_pages | read:logs | URLs any collected crawler fetched, most Googlebot hits first |
get_urls_to_fix | read:logs | Every URL crawlers got an error or a redirect for, one row per URL |
get_site_sections | read:logs | Bot activity grouped by your section rules |
get_bot_status_codes | read:logs | Which status codes bots get, as a bot-by-status matrix and an error explorer |
get_status_timeline | read:logs | Status codes over time, one series per exact code |
explore_log_requests | read:logs | Which crawler and which pages got a given status |
get_crawl_budget | read:logs | Where bot crawl effort went and how much was wasted |
get_ai_crawler_activity | read:logs | Per-AI-bot hits, share, bytes served, verification and robots.txt compliance |
get_crawl_coverage_gaps | read:logs | Pages verified Googlebot crawled that no AI crawler fetched |
list_spoofed_bots | read:logs | Which bot identities are being impersonated, and from which networks |
get_log_source_status | read:logs | The domain's log source, its health and the workspace's hit usage |
get_crawl_to_click_funnel | read:logs | Every URL placed on the crawled, indexed, impression, click funnel |
get_crawl_budget_roi | read:logs | Crawl effort against clicks earned, per section |
get_stale_money_pages | read:logs | Highest-impression pages verified Googlebot has not fetched recently |
list_orphan_pages | read:logs | Pages Google crawls that are missing from your sitemap |
list_uncrawled_sitemap_urls | read:logs | Sitemap URLs Googlebot has not fetched within a threshold |
list_new_urls_found | read:logs | New URLs Googlebot found this week, split by sitemap membership |
get_incident_seo_cost | read:logs | Per downtime incident, the search and AI crawler requests that hit errors |
get_bot_traffic_share | read:logs | Bot vs human share of traffic, using Web Analytics for the human side |
get_ai_visibility_funnel | read:logs | Pages AI crawlers fetched, and whether they later got AI search visits |
get_robots_compliance | read:logs | How closely each bot honors your robots.txt |
get_ai_bot_policy_reality | read:logs | What robots.txt declares for each AI bot, next to what it actually did |
get_bot_vs_human_ttfb | read:logs | Bot vs real-user response time for the same page |
get_cwv_crawl_priority | read:logs | Core Web Vitals work prioritized by how much Google crawls each page |
Ask in plain terms: "Is Googlebot getting errors on example.com?", "Which AI crawlers read my site, and do they respect robots.txt?", or "Which pages with impressions has Google stopped crawling?"
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 |
list_alert_rules and manage_alert_rule also cover Page Monitoring, Site Health Monitoring, and Sitemap Monitoring rules. See Alert types.
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.
Concurrency
A connection may run five tool calls at once. Beyond that they queue. An assistant fanning out across many domains will finish, just not all at the same instant.
