insights/products/web_analytics/mcp/tools.yaml

# MCP tool definition — tool entries are scaffolded from the OpenAPI schema.
# The tool list and operation IDs are kept in sync automatically:
#   pnpm --filter=@hanzo/mcp run scaffold-yaml -- --sync-all
#
# To enable a tool, set enabled: true and add required scopes + annotations.
# All other fields (title, description, enrich_url, etc.) are yours to configure.
category: Web analytics
feature: web_analytics
url_prefix: /web
ui_apps: {}
tools:
    heatmap-screenshots-content-retrieve:
        operation: heatmap_screenshots_content_retrieve
        enabled: false
    heatmaps-events:
        operation: heatmaps_events_retrieve
        enabled: true
        scopes:
            - heatmap:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get sessions behind heatmap coordinates
        description: >
            Drill into the individual session interactions behind one or more heatmap coordinates. Pass `points` as a
            JSON array of the spots you want to inspect (the `pointer_relative_x` / `pointer_y` values from
            `heatmaps-list`), plus the same page/date filters. Returns the underlying per-session interactions so you
            can open the session recordings that produced a hotspot.
        feature_flag: heatmaps-mcp
    heatmaps-list:
        operation: heatmaps_list
        enabled: true
        scopes:
            - heatmap:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        list: true
        title: List heatmap interactions for a page
        description: >
            Aggregated heatmap interactions captured on a page. Filter by `url_exact` (one page) or `url_pattern` (regex
            across pages), a date window (`date_from`/`date_to`, data is retained 90 days), and optionally a viewport
            range (`viewport_width_min`/`viewport_width_max`, CSS px) to isolate a device class. Set `type` to 'click'
            (default), 'rageclick', 'mousemove', or 'scrolldepth'. For clicks each result is a point —
            `pointer_relative_x` (0..1 across the viewport), `pointer_y` (absolute pixels down the page), and a `count`;
            'scrolldepth' returns reach buckets instead. For the click types the response also includes a `fold` summary
            — `pct_below_fold` (share of non-fixed interactions that landed below the user's initial viewport, i.e.
            required scrolling), `below_fold_count`, `total_count`, and the `median_viewport_height` (the typical fold
            line in CSS px) — so a high `pct_below_fold` flags engaged content sitting off the first screen. `rageclick`
            hotspots and shallow scroll depth are the strongest signals that something on the page is confusing or
            buried. Heatmaps only know coordinates, not what was clicked — cross-reference autocapture events on the
            same URL to name the elements, and use `heatmaps-events` to jump to the sessions behind a hotspot. Click
            results are returned hottest-first and capped at `limit` (default 500); busy pages have thousands of
            distinct coordinates, so the default page plus the `fold` summary is usually enough for analysis — raise
            `limit` or page with `offset` only if you need more, and check `has_more` to know when the list is
            truncated.
        feature_flag: heatmaps-mcp
    heatmaps-saved-create:
        operation: saved_create
        enabled: true
        scopes:
            - heatmap:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        title: Create a saved heatmap
        description: >
            Create a saved heatmap for a page URL. For type 'screenshot' (the default) this enqueues a headless render
            of the page at each target width — poll `heatmaps-saved-get` until `status` is 'completed'; the rendered
            page (with data overlaid) is then viewable by the user in the Insights UI. Provide `widths` (CSS px,
            100-3000) to control which viewports are rendered, or omit it for sensible defaults. The URL must be exact —
            wildcards are not allowed.
        exclude_params:
            - deleted
        feature_flag: heatmaps-mcp
    heatmaps-saved-get:
        operation: saved_retrieve
        enabled: true
        scopes:
            - heatmap:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get a saved heatmap
        description: >
            Get a single saved heatmap by its `short_id`, including per-width render `status`. Poll this after
            `heatmaps-saved-create` until `status` is 'completed'; the rendered page is then viewable by the user in the
            Insights UI.
        feature_flag: heatmaps-mcp
    heatmaps-saved-list:
        operation: saved_list
        enabled: true
        scopes:
            - heatmap:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        list: true
        title: List saved heatmaps
        description: >
            List saved heatmaps for the project. A saved heatmap pins a page URL plus a set of viewport widths and (for
            type 'screenshot') renders the page so heatmap data can be overlaid on it. Filter by `type`, `status`,
            `created_by`, or a `search` substring on URL/name. The rendered page (screenshot with data overlaid) is
            viewable by the user in the Insights UI.
        feature_flag: heatmaps-mcp
    heatmaps-saved-regenerate:
        operation: saved_regenerate_create
        enabled: true
        scopes:
            - heatmap:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: false
        title: Regenerate a saved heatmap screenshot
        description: >
            Re-run screenshot generation for a saved heatmap of type 'screenshot' by its `short_id`. Clears the existing
            renders and re-renders at every target width; `status` returns to 'processing'. Use when a page has changed
            or a render failed.
        feature_flag: heatmaps-mcp
    heatmaps-saved-update:
        operation: saved_partial_update
        enabled: true
        scopes:
            - heatmap:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: true
        title: Update a saved heatmap
        description: >
            Update a saved heatmap by its `short_id`. Send only the fields to change — rename via `name`, change
            `widths`, or soft-delete by setting `deleted: true` (deletion goes through this update, not a destroy call).
            Changing the `url` of a 'screenshot' heatmap triggers a fresh render.
        feature_flag: heatmaps-mcp
    saved-destroy:
        operation: saved_destroy
        enabled: false
    saved-preflight-create:
        operation: saved_preflight_create
        enabled: false
    saved-prewarm-create:
        operation: saved_prewarm_create
        enabled: false
    web-analytics-achievements-acknowledge-celebration:
        operation: web_analytics_achievements_acknowledge_celebration
        enabled: false
    web-analytics-achievements-overview:
        operation: web_analytics_achievements_overview
        enabled: false
    web-analytics-achievements-preferences:
        operation: web_analytics_achievements_preferences
        enabled: false
    web-analytics-achievements-record-interaction:
        operation: web_analytics_achievements_record_interaction
        enabled: false
    web-analytics-achievements-record-visit:
        operation: web_analytics_achievements_record_visit
        enabled: false
    web-analytics-achievements-update-preferences:
        operation: web_analytics_achievements_update_preferences
        enabled: false
    web-analytics-filter-presets-create:
        operation: web_analytics_filter_presets_create
        enabled: false
    web-analytics-filter-presets-destroy:
        operation: web_analytics_filter_presets_destroy
        enabled: false
    web-analytics-filter-presets-list:
        operation: web_analytics_filter_presets_list
        enabled: false
    web-analytics-filter-presets-partial-update:
        operation: web_analytics_filter_presets_partial_update
        enabled: false
    web-analytics-filter-presets-retrieve:
        operation: web_analytics_filter_presets_retrieve
        enabled: false
    web-analytics-filter-presets-update:
        operation: web_analytics_filter_presets_update
        enabled: false
    web-analytics-path-cleaning-suggestions-apply:
        operation: web_analytics_path_cleaning_suggestions_apply
        enabled: true
        scopes:
            - web_analytics:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: false
        title: Apply a path-cleaning suggestion
        description: >
            Apply a suggested set of path-cleaning rules by its health-issue `id`, merging them into the project's path
            cleaning configuration. Existing rules are never overwritten — only new rules are appended — and the
            underlying `path_cleaning_suggestions` health issue is resolved. Returns how many rules were added. Requires
            project admin (the same gate as editing path cleaning rules in team settings). Applying changes historical
            numbers in every Web analytics and Paths chart that has cleaning enabled, so confirm with the user before
            calling this.
        feature_flag: web-analytics-path-cleaning-suggestions
    web-analytics-path-cleaning-suggestions-generate:
        operation: web_analytics_path_cleaning_suggestions_generate
        enabled: true
        scopes:
            - web_analytics:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        title: Generate path-cleaning suggestions
        description: >
            Analyze the project's recent URL paths and generate suggested path-cleaning rules on demand. Samples the
            most-viewed paths, asks the model for `{regex, alias}` rules, and validates each against the real paths
            (dropping any that don't match), then stores the result as a `path_cleaning_suggestions` health issue.
            Returns `status` ('generated' with a `suggestion`, or a skip reason like 'skipped_no_paths' /
            'skipped_low_cardinality' when there isn't enough to suggest from). Pending suggestions surface through the
            health-issues API (filter `kind=path_cleaning_suggestions`); dismiss one by PATCHing the issue's `dismissed`
            flag. Use when the user asks to clean up or normalize their paths and no suggestion exists yet. This only
            proposes rules — apply them with `web-analytics-path-cleaning-suggestions-apply`; nothing changes until
            then.
        requires_ai_consent: true
        feature_flag: web-analytics-path-cleaning-suggestions
    web-analytics-path-cleaning-suggestions-preview:
        operation: web_analytics_path_cleaning_suggestions_preview
        enabled: false
    web-analytics-recap:
        operation: web_analytics_recap
        enabled: false
    web-analytics-weekly-digest:
        operation: web_analytics_weekly_digest
        enabled: true
        scopes:
            - web_analytics:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Summarize web analytics
        description: >
            Summarizes a project's web analytics over a lookback window (default 7 days): unique visitors, pageviews,
            sessions, bounce rate, and average session duration with period-over-period comparisons, plus the top 5
            pages, top 5 traffic sources, and goal conversions. Accepts optional `days` (1–90, default 7) and `compare`
            (bool, default true) query params — pass `days=30` to summarize the last month, or `compare=false` to skip
            the period-over-period comparison for a faster response. Use this to answer questions like "how are my web
            analytics?", "how did the site do last week?", or "what's my traffic looking like this month?".
wrappers:
    query-web-overview:
        schema_ref: AssistantWebOverviewQuery
        enabled: true
        scopes:
            - query:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Run a web analytics overview query
        description_file: ./prompts/query-web-overview.md
        system_prompt_hint: Web analytics KPIs — visitors, sessions, bounce rate, session duration
        ui_resource_uri: ui://insights/query-results.html
        exclude_properties:
            - response
            - modifiers
            - samplingFactor
        use_optimized_output: false
    query-web-stats:
        schema_ref: AssistantWebStatsTableQuery
        enabled: true
        scopes:
            - query:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Run a web analytics breakdown table query
        description_file: ./prompts/query-web-stats.md
        system_prompt_hint: Web analytics breakdowns — top pages, UTMs, devices, countries, with bounce rate
        ui_resource_uri: ui://insights/query-results.html
        exclude_properties:
            - response
            - modifiers
            - samplingFactor
        use_optimized_output: false
    query-web-vitals:
        schema_ref: AssistantWebVitalsPathBreakdownQuery
        enabled: true
        scopes:
            - query:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Run a web vitals path breakdown query
        description_file: ./prompts/query-web-vitals.md
        system_prompt_hint: Core Web Vitals per page — LCP, INP, CLS, FCP bucketed into good / needs-improvement / poor
        ui_resource_uri: ui://insights/query-results.html
        exclude_properties:
            - response
            - modifiers
            - samplingFactor
        use_optimized_output: false