# Tool Reference
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](/api/scopes#a-credential-is-a-ceiling-not-a-grant).
## Start here [#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](/api/credits#which-workspace-is-charged), 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 [#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 [#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](/api/conventions#rum-is-stricter-here-than-the-dashboard).
## Availability: uptime and SSL [#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 [#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 [#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 [#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 [#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 [#technical-seo-robotstxt]
| 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 [#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 [#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 [#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 [#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 [#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.
## Next [#next]
Four guided investigations that chain these tools for you.
How untrusted content from monitored sites is handled.