# Google Search Console with Fig

> v1 ships skill support for a User-brought Google Search Console (GSC) connector. Fig-hosted GSC OAuth and MCP read tools are specified here for a follow-up PR and are not implemented.

Fig MCP remains read-only SEO/AEO research. Search Console is separate evidence. Prefer read-only scopes. Never invent clicks, impressions, CTR, position, or coverage counts. When GSC is not connected, mark Search Console measurement unavailable and continue with Fig tools plus page inspection.

Writing to GSC (URL Inspection request indexing, sitemap submit, property changes) is out of scope. Bing Webmaster is out of scope.

## v1 path

- **Shipped now:** User-brought connector. The consuming Agent connects GSC (or Google) with the host's tools, a Search Console MCP, the Search Console API, or a User-provided export, then folds returned rows into audit, research, strategy, and validation.
- **Specified, not shipped:** Fig-hosted GSC. The User OAuths Search Console into Fig; Fig MCP later exposes read tools. Do not call `gsc_status`, `gsc_sites`, `gsc_search_analytics`, `gsc_url_inspect`, or `gsc_sitemaps` today — those names are the follow-up contract.
- Fig Google sign-in for the Fig account is `openid email` only. That is not a Search Console grant.

## User-brought connector

1. Ask the User to authorize a **read-only** Search Console connection the Agent can query, or to provide an export. Scope: `https://www.googleapis.com/auth/webmasters.readonly`. Do not request write scopes.
2. Confirm the property (`sc-domain:example.com` or a URL-prefix property) and the date range before pulling data. Use the last 28 days versus the prior 28 days when traffic is steady; use up to 16 months only when the shorter window is too sparse.
3. Pull Search Analytics with dimensions `page`, `query`, and `page`+`query` (and `country`/`device` only when the market is local or the User names a device split). Keep `searchType` web unless the request is Discover/News/Google/image specific.
4. Treat empty or tiny result sets as insufficient evidence, not as zeros you can trend. Cite the property, date range, filter, and row count with every GSC claim.
5. Recheck the same property, pages, queries, and date-range length after the observation window.

Hosts differ. Use whichever read path the host already has: a Google or Search Console MCP, a Google connector, `gcloud`/REST against the Search Console API, or a CSV/export the User pastes. v1 GSC connect happens in that host or export, not through Fig-hosted OAuth.

## Evidence slices (only from returned rows)

- **Low-CTR pages:** high impressions in the window, average position typically 1–8, CTR materially below other URLs on the same property at a similar position in the same window. Compare to that same-site cohort. Do not apply a made-up CTR-by-position curve as if it were GSC.
- **Striking distance:** queries or pages with meaningful impressions and observed average position roughly 8–20 (include 4–8 when CTR is already strong and the User wants page-one gains). Name the GSC position and impressions.
- **Wrong-query / cannibalization:** one query with two or more URLs each taking meaningful impressions; or a URL whose top queries do not match its visible intent, title, or H1. Use the page+query dimension.
- **Index issues:** URL Inspection fields that were actually returned (`coverageState`, `indexingState`, `robotsTxtState`, `pageFetchState`, crawled canonical, `lastCrawlTime`); submitted sitemaps when that API or UI export exists; Coverage UI/export only when the User provided it. There is no complete Index Coverage API — do not invent indexed/excluded counts.

Fig keyword volumes, live SERPs, and AI-visibility scores are not Search Console metrics. Do not present them as clicks, CTR, or average position.

## Measurement handoff

Every audit, research table, brief, and validation report must include one of:

- **Connected:** Search Console property, date range, search type, and the baseline metrics actually returned for the in-scope pages/queries (clicks, impressions, CTR, position, and any index/inspection fields).
- **Not connected:** `Search Console measurement unavailable.` Immediate implementation checks (HTTP, HTML, schema, Fig rechecks) still run; longitudinal click/CTR/position outcomes wait until GSC exists.

## Follow-up: Fig-hosted MCP read tools

Ship these only after a dedicated OAuth connect flow. The human approves connect. Do not reuse Fig account Google login tokens.

### OAuth and privacy

- Extra Google OAuth, separate from Fig `openid email`. Production needs an updated [Privacy Policy](https://figaeo.com/privacy) and [Terms](https://figaeo.com/terms) that describe Search Console access, storage, and Limited Use.
- Scope: `https://www.googleapis.com/auth/webmasters.readonly` only.
- Store refresh tokens per Fig account (verified email), encrypted at rest. Do not sell GSC rows or use them for advertising.
- Tools fail closed: if the User has not connected GSC, return the existing `authentication` error category with a message that Search Console is not connected. Empty windows use `no_data`. Never pad missing rows.
- Quota: Search Analytics and URL Inspection are Google-quota bound; compact responses; do not scrape the GSC UI.

### Proposed tools (not in the live Fig catalog)

| Tool | Purpose |
| --- | --- |
| `gsc_status` | Whether GSC is connected; selected property; granted scopes. |
| `gsc_sites` | List verified properties the token can read. |
| `gsc_search_analytics` | Search Analytics rows: keys plus clicks, impressions, CTR, position. Inputs: `site_url`, `start_date`, `end_date`, `dimensions`, filters, `row_limit`, `search_type`. |
| `gsc_url_inspect` | URL Inspection index status for one URL under a property. Quota-aware. |
| `gsc_sitemaps` | List submitted sitemaps for a property. |

Not in this design: request indexing, inspect-URL submit, sitemap submit, property add/delete, Bing Webmaster.

Skills should treat a future connected `gsc_status` the same as a User-brought connector: name baselines when rows exist, mark measurement unavailable when `authentication` says GSC is not connected.