fetch-tool
ChatGPTRetrieves 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.
get-page-analytics-tool
ChatGPTGets 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 max importance score 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_importance_score) — use that to pick a date, then call get_page_changes_tool or get_page_change_summary_tool for the details.
get-page-changes-tool
ChatGPTGets 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 an importance score from 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. ALMOST ALWAYS pass min_importance: 30 or higher to filter out cosmetic noise — scores below 30 are typically nav reshuffles, repeated edits, or trivial formatting. Scores above 60 represent meaningful SEO levers (title rewrites, content additions, schema changes). Sorted newest first. This tool is the preferred way to understand changes when the number of field-level changes for a given day is small (roughly under 25). For days with 25+ field-level changes, the raw list can become noisy — in that case, use get_page_change_summary_tool instead, which returns a pre-digested human-readable narrative for a specific date.
get-project-analytics-tool
ChatGPTGets 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. Use min_importance to filter the page change summary to meaningful changes only. Set include_time_series: false to save tokens when you only need totals.
get-project-pages-tool
ChatGPTLists tracked pages within a PagePulse project. Use this to find a specific page (by URL substring via the search param), to browse pages by tag, or to find pages that had changes on specific dates. Returns paginated results with each page's URL, path, title, tags, and aggregated clicks/impressions/position for the requested date range. Pages can number in the thousands per project — always use search/tag filters when possible, and rely on pagination. Returns total count in meta so you can tell the user if there's more data. Use this when the user asks for "top pages" / "best pages" / "highest-traffic pages" / "biggest pages by clicks" (the default sort handles ranking — clicks descending), "what pages do I have", "find the page about X", "show me pages tagged Y", "pages that changed on [date]", or before drilling into a specific page with the analytics or changes tools. Results are sorted by clicks descending by default (pages with the most traffic in the date range first); pass order_by (clicks, impressions, url, id) and order_by_dir (asc, desc) to change this. Sort ties are always broken by page id ascending so pagination is stable.
get-search-queries-tool
ChatGPTGets Google Search Console query performance data for a specific page over a date range. Returns the search queries (keywords) that drove impressions or clicks to this page, each with totals for clicks, impressions, average position, and CTR. Use this when the user asks "what keywords does this page rank for", "what queries are bringing traffic here", or to understand what search intent a page is capturing. Sort by clicks (default) to see top performers, or by impressions to see queries with high visibility but low clicks (potential CTR optimization opportunities). Use the search param to look for queries containing specific terms. Pages can have hundreds of queries — pagination is supported. A query with high impressions but very low clicks/CTR may indicate a title or meta description that doesn't match search intent.
list-project-tags-tool
ChatGPTLists all tags defined in a PagePulse project, with each tag's ID, name, and the number of pages assigned to it. Tags are user-defined labels applied to pages, scoped per project. Use this tool when you need to filter pages by tag in get_project_pages_tool or get_project_analytics_tool — those tools accept tag_ids, and this is how you discover what IDs are available. The page_count on each tag helps you judge how broad or narrow a filter will be (e.g., a tag with 50 pages vs 2 pages). Many users organize their pages heavily by tag (e.g., "money pages", "blog", "service pages"), so checking tags is often a good first step when scoping a project-wide question. Tag filtering uses OR logic — passing multiple tag_ids returns pages with ANY of those tags.
list-projects-tool
ChatGPTLists all active SEO monitoring projects the authenticated user has access to within their organization. Returns each project's UUID, name, and URL. CALL THIS FIRST before any other PagePulse tool — every other tool requires a project_uuid that you can only get from this tool. If the user mentions a website or project by name, use this tool to find the matching UUID. If the user has multiple projects and the request is ambiguous, ask which one they mean.
search-tool
ChatGPTSearches across PagePulse projects and pages by a keyword/phrase. Returns a mixed list of matching projects and pages in the search/fetch retrieval shape (id, title, url). Matches against project name/url and page url/path/title. Each result id is prefixed with the entity type (project:{uuid} or page:{id}) so the fetch tool can route by prefix. Use this when the user issues a broad query like "find pages about pricing" or when you need a quick way to locate an entity without knowing project UUIDs in advance. For deeper structured analytics on a project or page, use the specialized tools (list_projects_tool, get_project_pages_tool, get_page_analytics_tool, etc.) once you have the IDs.
