Page Pulse

Adds specific page URLs to an existing PagePulse project so exactly those pages are tracked for changes. This is the tool for "watch these particular pages" — a hand-picked list of competitor pages, vendor profiles on a review platform, or any curated URL set — as opposed to crawling a site and discovering pages. Every URL must be on the project's own domain (create one project per domain first, with create-project-tool). Each added page gets an immediate first snapshot, and is then re-checked on the project's normal crawl schedule; change detection starts from the SECOND snapshot, so tell the user changes will appear after the next scheduled crawl, not within minutes. Pass tags to label every page added in this call (e.g. add all 9 HubSpot profile URLs tagged "hubspot" in one call, then the next vendor's URLs with their tag) — tags are how alerts and analytics scope to a subset later. Up to 200 URLs per call; returns a per-URL result (added / already_tracked / rejected with the reason) so a partial batch is usable. Already-tracked URLs get any new tags applied rather than erroring.

add-pages-tool

Creates an alert on a PagePulse project so the user is notified without checking the app. Templates: "page_changes" fires as soon as a meaningful page change is detected (works on EVERY project, no Google needed); "weekly_digest" sends a Monday summary; "monthly_digest" sends the same on the 1st. DELIVERY: email (emails), Slack (slack_channel — a channel name like "#seo-alerts"), or both. Slack requires the organization to have connected a workspace in the web app; if it has not, this tool returns the connect URL — offer to set up email instead rather than failing. SCOPE: alerts cover every page by default. Narrow with tag_names (PREFERRED — call list-project-tags-tool first to see what exists, e.g. a "Services" tag when the user says "service pages") or page_urls for exact pages. THRESHOLD ALERTS: pass metric (clicks, impressions, users, key_events, avg_position, ctr) with optional direction ("drop"/"gain"), threshold_percent and period_days to create "tell me when clicks drop 20%". These read Google data, so they REQUIRE traffic_connected=true — on a crawl-only project this tool refuses and explains why. They notify once when the condition starts and again when it recovers, not repeatedly while it persists. Creating the same template with the same scope twice returns the existing alert instead of duplicating — call list-alerts-tool FIRST to see what already exists. Use update-alert-tool to enable/disable an alert or change its delivery or schedule; deleting alerts or editing conditions requires the web app.

create-alert-tool

Creates a new PagePulse project that tracks content changes on a website. The first crawl is queued on creation but typically runs with the nightly crawl cycle — do NOT tell the user changes will appear within minutes or hours. TWO MODES. Discovery (default): pass url and the crawler starts at the DOMAIN ROOT and discovers pages breadth-first up to the plan cap (default 1,000) — any path in the url is IGNORED for crawling, and www/non-www is normalized. On a large or third-party site (a review platform, a marketplace, a competitor), discovery will fill the project with listing pages and likely never reach specific deep pages — do NOT use discovery for those. URL-list: pass urls (an array of exact page URLs, all on one domain) and ONLY those pages are tracked — no discovery at all. This is the mode for "watch these specific pages": competitor pages, vendor profiles on G2/Capterra, hand-picked URL sets. More pages can be added later with add-pages-tool (which also supports tagging per batch). SCOPING discovery: to track only part of an owned site ("just the service pages"), call discover-site-paths-tool FIRST to see the real paths the site publishes, confirm the selection with the user, then pass include_paths. Do not create a whole-site project when the user asked for a subset — scope it, use urls, or ask. Use this when the user asks to start tracking, monitoring, or watching a site for changes. IMPORTANT — what a new project can and cannot do: it is created CRAWL-ONLY, meaning it detects page changes (content, titles, meta descriptions, links) but has NO traffic data. Search Console and Analytics require a Google sign-in that can only be completed by the user in the PagePulse web app — it CANNOT be done through this API. So after creating a project, you can set up page-change alerts and digests, but NOT traffic-based alerts (clicks/impressions/rankings) until the user connects Google themselves. If a project for the same website already exists in the organization, this returns that project instead of creating a duplicate. Project creation is limited by the organization plan.

create-project-tool

Reads a website's sitemap and reports the URL paths it publishes, grouped by section (e.g. /services/, /blog/) with a count and sample URLs for each. Use this BEFORE create-project-tool whenever the user wants to track only part of a site — "track the service pages", "just the product pages", "our locations" — so you can find the real paths instead of guessing, show the user what you found, and then pass the confirmed paths to create-project-tool as include_paths. Returns both grouped sections AND the flat list of root-level pages, because many small-business sites put service pages at the root (/patio-installation/) with no /services/ prefix. Tries the usual sitemap locations automatically; pass sitemap_url if you already know it. Reads the public sitemap only — it does not create anything or require the site to be a project yet.

discover-site-paths-tool

Retrieves the full record for a single PagePulse entity (project or page) by its prefixed id. The id must be in the form "project:{uuid}" or "page:{id}" — the same format returned by the search tool. Returns a rich document-shaped payload ({id, title, text, url, metadata}) describing the entity, suitable for citation and for giving the model enough context to decide what specialized tool to call next. For deeper structured analytics (time series, changes, query-level breakdowns), use the dedicated tools (get_page_analytics_tool, get_project_analytics_tool, get_page_changes_tool, etc.) once you have the identifiers.

fetch-tool

Returns the MEASURED change→effect verdicts from the Page Pulse impact model: for change windows on a page, how clicks actually moved afterward versus the expected baseline, with a confidence band (possible / likely / high) and the evaluation horizon. THIS is the defensible "did that change help?" answer — prefer it over eyeballing time series yourself, because the model controls for the page's own baseline trajectory. Each row: the page, when the change window started, which fields dominated the change, clicks lift percent (negative = decline), confidence band and score, and the horizon in days. Rows exist only for changes the model judged meaningful AND that have completed an evaluation horizon — a recent change may not be evaluated yet (that is "still measuring", not "no effect"). Use search-changes-tool to see raw changes, this tool to see which ones mattered.

get-change-outcomes-tool

Returns the pages that MOVED the most — ranked by the change (delta) in a metric between the requested window and the prior window of the same length (or the same window last year). This is the triage tool for large projects: start here to find where traffic shifted, then use search-changes-tool / get-page-changes-tool to see what changed on those pages and get-change-outcomes-tool for measured change→effect verdicts. metric: clicks | impressions | position | ctr | key_events. Each row carries current and prior values, absolute and percent delta, and how many meaningful detected changes the page had in the window. POSITION SEMANTICS: position is lower-is-better, so a NEGATIVE position delta is an improvement; direction=up means "improved" for every metric (position falling). Use min_impressions to ignore pages with no real search presence.

get-movers-tool

Gets detailed SEO analytics for a single page over a date range. Returns aggregated metrics (clicks, impressions, average position, CTR, users, key events, page views, bounce rate, time on page), an optional daily time series, and a compact page_change_summary block showing which dates had changes (with counts by field and the strongest impact band per date — no raw diffs). Use this when the user asks how a specific page is performing ("is this page doing well", "how is [page] trending", "how is [page] doing this month"), whether traffic dropped, or to compare a recent period against a prior one. Pass comparison: previous-period or previous-year to get percent-change values automatically. The view_scope parameter controls whether you get page metrics or landing page metrics — default to "page" unless the user specifically asks about landing pages or session entries. Set include_time_series: false when you only need totals to save tokens. Position is "lower is better" — a position drop from 5 to 3 is an improvement. To investigate a drop: the page_change_summary in this response already tells you which dates had changes and how significant (via max_impact_band) — use that to pick a date, then call get_page_changes_tool or get_page_change_summary_tool for the details.

get-page-analytics-tool

Gets detected on-page changes for a specific page within a date range. Each change includes the field that changed (title, h1, meta_description, body_content, internal_links, schema, etc.), the old and new values, the change type (new/edit/removal), the detected timestamp, and its IMPACT BAND — noise, low, notable, high, or critical — from the Page Pulse impact model, plus the underlying impact_score (0-100). Use this when the user asks "what changed on this page" / "did anything change recently" / "what edits happened to [page]" / "show me the diff on [page]", or as a follow-up to get_page_analytics_tool when investigating why traffic moved. Pass min_band: notable to skip cosmetic noise; use high or critical when the user asks for the biggest or most important changes. About bands: impact_band is null when the impact model did not score that change — usually because it fell below the model's meaningfulness floor (trivial or repeated edits), which is itself a signal it is not worth surfacing. Separately, meta.impact_scored: false means the whole project has never been through the impact model, in which case NO change has a band, any min_band filter is ignored (see meta.band_filter_applied), and you should say the project has not been scored yet rather than reporting that nothing changed. Sorted newest first.

get-page-changes-tool

Gets aggregated SEO analytics across all pages in a project — or a filtered subset. Returns total clicks, impressions, users, key events, average position, plus an optional daily time series and a page change summary. Use this for project-wide questions like "how is the whole site doing" / "site overview" / "what's the trend on this site" / "are we losing traffic overall", "how did my blog perform last month" (filter by tag), or "what changed across the site". Filter to a subset of pages using search (URL substring), tag_ids (OR logic — pages with any of those tags), or has_page_change_on (pages with changes on specific dates). The pages_count in the response tells you how many pages matched the filters. Each date in the page change summary carries impact_bands (counts per band: noise, low, notable, high, critical); use min_band to restrict the summary to meaningful changes only (min_band: notable is the usual floor, high/critical for the biggest). impact_scored: false means the project has not been through the impact model yet, so bands are unavailable — say so rather than reporting nothing changed. Set include_time_series: false to save tokens when you only need totals.

get-project-analytics-tool