Tools Reference

You don't call these tools yourself: your AI client picks them from your question. All 9 tools are read-only.

site_url is the property exactly as list_sites shows it: sc-domain:example.com for a domain property, or a URL prefix with its trailing slash, such as https://www.example.com/. You can just name the site in your question; the AI client looks it up.

Dates are YYYY-MM-DD, today, yesterday or NdaysAgo (e.g. 7daysAgo), in Pacific Time like Search Console itself. The default range is the 28 days ending 3 days ago (30daysAgo to 3daysAgo), the latest days with final data.

Connection tools

Your AI client uses these to connect the computer to your free Tag Pilot account and Google. You don't need a terminal: just say "connect my Search Console", or ask a data question.

connect

Starts connecting (or reuses a connect already in progress) and returns a clickable link and a code like ABCD-1234. Open the link in any browser, check the code, approve, and allow Google access. Clients that support MCP URL elicitation also offer to open the link for you. If the computer is already connected, it says so. No parameters.

connection_status

Whether this computer is connected:

Data tools called before the computer is connected return the same link and code, and the AI client retries your question once you've approved.

list_sites

Every property the signed-in Google account can see: domain properties (all subdomains and protocols) and URL-prefix properties, with the permission level: owner, full, restricted or unverified. Unverified properties are listed but their data can't be read. No parameters.

"Which Search Console properties do I have?"

search_analytics

The Search Analytics report: clicks, impressions, CTR (0–1) and average position.

discover and googleNews don't support grouping by query or aggregation_type: "byProperty".

Filters are a list of {"dimension", "operator", "expression"} that must all match:

[
  {"dimension": "query", "operator": "contains", "expression": "shoes"},
  {"dimension": "country", "expression": "pol"},
  {"dimension": "page", "operator": "excludingRegex", "expression": "/blog/"}
]

• Dimensions: query, page, country, device, searchAppearance.
• Operators: equals (default), contains, notEquals, notContains, includingRegex, excludingRegex (RE2 syntax).
• country uses lowercase ISO 3166-1 alpha-3 codes (pol, usa, deu); device is DESKTOP, MOBILE or TABLET; page is a full URL.

The result has the rows, next_start_row when there may be more, and notes on anonymised queries and incomplete data.

"Top 20 queries by clicks last month, with CTR and position."

compare_periods

Period-over-period change by query or page: clicks, impressions, CTR and position for both periods with the deltas, rows marked new or lost, and property totals for both periods (which include anonymised queries). Biggest movers first. Uses 4 Search Analytics queries.

A negative position_change means the page moved up.

"Which pages lost the most clicks in the last 28 days compared with the 28 days before?"

find_opportunities

A Tag Pilot SEO check over one period, by query or page:

• low_ctr: rows on page one (average position up to 10) with plenty of impressions but a CTR under half of a typical CTR for their position: the title or snippet probably underperforms.
• striking_distance: rows at average positions around 5–20 with enough impressions, where a small ranking gain pays off.

"Typical CTR" is a rough benchmark curve (position 1 ≈ 28%, 3 ≈ 10%, 10 ≈ 2%), not Google data. The potential_extra_clicks estimates are for ranking the list, not a forecast.

"Find SEO opportunities on example.com: pages with a low CTR for their position, and queries just off page one."

inspect_url

Google's indexed version of one URL (the URL Inspection API): verdict and coverage state, last crawl, robots.txt and fetch state, the canonical Google chose vs the one you declared (flagged when they differ), sitemaps and referring URLs, rich results and AMP. It's not a live test of the current page.

Google allows 2,000 inspections per day and 600 per minute per property, so use it for a handful of important URLs, not whole sitemaps.

"Is https://www.example.com/pricing indexed? Which canonical did Google pick?"

list_sitemaps and get_sitemap

Submitted sitemaps (or the ones in a sitemap index): type, whether it's an index, pending, last submitted and downloaded, errors, warnings, and submitted URL counts per content type. Google no longer reports indexed counts per sitemap; use inspect_url for single URLs.

"Do any of our sitemaps have errors? When did Google last download them?"

Things to know about Search Console data

• Lag: data typically arrives after 2–3 days, so the default range ends 3 days ago. Ask for fresher data and the tools use data_state: "all"; the result then says from which date data is incomplete.
• Pacific Time: Search Console's days start at midnight Pacific Time, and relative dates are computed in Pacific Time too.
• Anonymised queries: queries too rare to show (for privacy) are left out of rows grouped or filtered by query. Per-query rows therefore add up to less than the totals by date, country or device; compare_periods reports property totals separately for that reason.
• Row limits: one call returns up to 25,000 rows (page with start_row), and Google exposes at most 50,000 rows per day per search type, sorted by clicks.
• By page vs by property: grouping or filtering by page counts each URL separately, so totals differ from the property-level totals in the Search Console interface.
• Quotas: Search Analytics allows 1,200 queries per minute per site and per user, plus a load quota that long, query-and-page-level requests use up faster. URL Inspection allows 2,000 inspections per day per property.