> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scrunch MCP Feature Reference and Example Prompts

> Reference for 33 Scrunch MCP tools covering reporting, responses, prompts, brand configuration, agent traffic, and help docs, with example prompts.

Scrunch's MCP connection gives your AI assistant access to 33 features. These are called automatically in response to natural-language prompts — you never need to reference them by name. Related categories are grouped into the tabs below; use them to jump to what you need. Each description and example prompt shows what a feature does and how to ask for it.

<Tabs>
  <Tab title="Reporting">
    Everything for measuring and visualizing AI visibility — the core metrics, plus the Explorer charts and dashboards built on top of them.

    ## Metrics

    The four core analytics features. Each accepts the same set of filters: AI platform, country, persona, funnel stage, tags, topics, branded vs. non-branded prompts, and a date range.

    <AccordionGroup>
      <Accordion title="get_presence_metrics">
        Returns brand mention rate (presence) over time — the percentage of AI responses where your brand is mentioned. Set `include_competitors=true` to compare brands side by side.

        **Example prompts**

        * "How has our presence in ChatGPT trended over the last 90 days?"
        * "Compare our mention rate vs. all tracked competitors over the past month."
        * "Show me weekly presence for our brand on Perplexity since January."
      </Accordion>

      <Accordion title="get_position_metrics">
        Returns how often the brand appears in the top, middle, or bottom position within AI responses — relative to other brands mentioned in the same response.

        **Example prompts**

        * "Are we showing up first or last when AI assistants list options in our category?"
        * "What's our average position on ChatGPT for consideration-stage prompts?"
      </Accordion>

      <Accordion title="get_sentiment_metrics">
        Returns sentiment breakdown (positive, mixed, negative) for brand mentions in AI responses.

        **Example prompts**

        * "What's the sentiment trend for our brand on Perplexity in the last 30 days?"
        * "Is sentiment improving or declining compared to last quarter?"
        * "Compare our sentiment vs. our top competitor across all platforms."
      </Accordion>

      <Accordion title="get_citations_metrics">
        Returns how AI-cited URLs break down by ownership: brand-owned, competitor-owned, and third-party. Use `citation_owner` to focus on one type, or `brand_mentioned` to filter by branded vs. non-branded prompts.

        **Example prompts**

        * "What share of citations come from third-party sites for our non-branded queries?"
        * "Which competitor's domains are getting cited the most in our category?"
        * "How has our owned citation share changed over the last 60 days?"
      </Accordion>
    </AccordionGroup>

    ## Explorer

    Turn a metric question into an interactive Scrunch Explorer chart or a saved dashboard. Both return a deep link that opens the Explorer pre-configured — great for exploring the data behind an answer or saving a view you'll revisit.

    <AccordionGroup>
      <Accordion title="generate_explorer_chart">
        Builds an Explorer chart from a metric/breakdown/filter spec and returns a deep link that opens the Explorer with that chart already configured. Your assistant offers this after answering an analysis question so you can explore the chart behind the numbers. Supports line, bar, and pivot visualizations, breakdowns (e.g. by platform or competitor), custom date ranges, and comparison overlays.

        **Example prompts**

        * "Chart our mention rate by AI platform over the last 30 days."
        * "Visualize our share of voice vs. our top 3 competitors, weekly."
        * "Show citations broken down by owner as a bar chart, and give me the link."
      </Accordion>

      <Accordion title="create_explorer_dashboard">
        Creates a saved dashboard of metric tiles for a brand and returns a deep link to it. Each tile uses the same spec as `generate_explorer_chart` plus a title — mix a few headline "card" tiles with line/bar charts for trends and breakdowns.

        **Example prompts**

        * "Build a dashboard for Acme Coffee with presence, sentiment, and citation trends."
        * "Create a competitive dashboard comparing our share of voice against Blue Bottle and Stumptown."
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Responses">
    Pull the raw AI responses Scrunch has captured — full response text, citations, and per-competitor evaluations for individual answers. Use this when you need to read what an AI actually said, not just an aggregate metric.

    <AccordionGroup>
      <Accordion title="list_responses">
        Lists individual AI responses (observations) for a brand. Filter by platform, prompt, persona, funnel stage, date range, and whether the response includes shopping results. Results are paginated with `limit` (default 10, max 100) and `offset`.

        By default it returns observation IDs only, to keep payloads small. Ask for full detail (`ids_only=false`) to include response text, evaluation data, citations, and competitor analysis for every listed response — or fetch IDs first and pull individual responses with `get_response`.

        Use this when you want to audit a specific answer, compare what two platforms said about the same prompt, or pull a sample of recent responses for qualitative review. For aggregated trends, use the metrics features instead.

        **Example prompts**

        * "Show me the 10 most recent ChatGPT responses for Acme Coffee where our brand wasn't mentioned."
        * "Pull every Perplexity response from last week for prompt #482 so I can compare them side by side."
        * "Find responses on Google AI Overviews in the comparison stage that include shopping results."
        * "Give me the raw responses Claude returned for the 'sustainability' persona in April."
      </Accordion>

      <Accordion title="get_response">
        Fetches a single AI response by ID with full evaluation data, citations, and competitor analysis. Use it to inspect a response ID returned by `list_responses`.

        **Example prompts**

        * "Pull the full text and citations for response #918273."
        * "What did the AI actually say in that response — and which URLs did it cite?"
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Prompts">
    Manage the seed prompts Scrunch runs against AI platforms on your behalf, and the tags you use to organize them.

    ## Prompts

    Browse and manage the seed prompts Scrunch runs against AI platforms on your behalf.

    <AccordionGroup>
      <Accordion title="list_prompt_variants">
        Lists the prompt variants Scrunch is monitoring for a brand. Filterable by tag, persona, country, branded vs. non-branded, citation domain, funnel stage, and more.

        **Example prompts**

        * "Show me the top 20 non-branded prompts for Acme Coffee in the US."
        * "List all the prompts tagged 'consideration' for our brand."
        * "Browse the prompts in the awareness stage — I want to see what's covered before I add new ones."
      </Accordion>

      <Accordion title="create_prompt">
        Adds a new seed prompt for a brand, optionally with category, key topics, persona, platforms, and tags.

        **Example prompts**

        * "Add a prompt to Acme Coffee: 'What's the best mail-order coffee subscription for offices?' Tag it as 'consideration'."
        * "Create 5 new awareness-stage prompts for Acme Coffee focused on sustainability."
      </Accordion>

      <Accordion title="archive_prompt">
        Archives (soft-deletes) a seed prompt so it stops running. History is preserved.

        **Example prompts**

        * "Archive prompt #482 — we don't need to track that one anymore."
        * "Archive all prompts tagged 'Q1 campaign' for Acme Coffee."
      </Accordion>

      <Accordion title="unarchive_prompt">
        Restores previously archived prompts so they resume running.

        **Example prompts**

        * "Restore the prompts I archived last month for Acme Coffee."
        * "Unarchive all prompts in the 'seasonal' tag so they start running again."
      </Accordion>
    </AccordionGroup>

    ## Tags

    Read, add, and remove the tags attached to prompts so you can slice metrics by funnel stage, persona, campaign, or any custom dimension.

    <AccordionGroup>
      <Accordion title="get_tags">
        Returns all tags currently configured for a brand.

        **Example prompts**

        * "What tags do we use for Acme Coffee?"
        * "Show me the full tag list across all our brands."
      </Accordion>

      <Accordion title="add_tag_to_prompts">
        Adds a single tag to a list of prompts (up to 500 at a time). Existing tags are preserved — this only appends, never replaces. The tag is created for the brand if it doesn't already exist, and prompts that already have it are skipped.

        **Example prompts**

        * "Tag prompts #482 and #483 with 'mobile'."
        * "Add the 'evergreen' tag to every prompt in the awareness stage."
      </Accordion>

      <Accordion title="remove_tag_from_prompts">
        Removes a single tag from a list of prompts. Prompts that don't have the tag are ignored, and other tags on each prompt are unaffected.

        **Example prompts**

        * "Remove the 'Q1 campaign' tag from prompts #482 and #483."
        * "Untag 'draft' from all the prompts I created yesterday."
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Configure">
    Set up and maintain what Scrunch tracks for each brand — the brands themselves, their competitors, and the personas you slice metrics by.

    ## Brands

    Look up and manage the brands tracked in your Scrunch organization.

    <AccordionGroup>
      <Accordion title="list_brands">
        Lists all brands accessible within the authenticated organization, including name, website, status, and configuration details.

        **Example prompts**

        * "Show me all the brands I have access to in Scrunch."
        * "Which brands in our org have the most prompts configured?"
      </Accordion>

      <Accordion title="create_brand">
        Creates a new brand within the organization. Name, website, and status are required.

        **Example prompts**

        * "Create a new Scrunch brand for Acme Coffee, website acmecoffee.com."
        * "Set up a new brand for our UK subsidiary — name is Acme Coffee UK, website acmecoffee.co.uk."
      </Accordion>

      <Accordion title="update_brand">
        Updates an existing brand's name, alternative names, websites, geo, or case-sensitivity settings.

        **Example prompts**

        * "Add 'Acme Coffee Co.' as an alternative name for the Acme Coffee brand."
        * "Switch the geo for our Acme brand from US to UK."
      </Accordion>
    </AccordionGroup>

    ## Competitors

    Manage the competitors tracked alongside each brand.

    <AccordionGroup>
      <Accordion title="list_competitors">
        Lists all competitors being tracked for a specific brand, including their alternative names and websites.

        **Example prompts**

        * "Who are we tracking as competitors for Acme Coffee?"
        * "List the competitors for all our brands."
      </Accordion>

      <Accordion title="create_competitor">
        Adds a new competitor to a brand, with an optional list of alternative names and websites.

        **Example prompts**

        * "Add Blue Bottle as a competitor for Acme Coffee with website bluebottlecoffee.com."
        * "Start tracking Stumptown Coffee as a competitor — add their main site and their DTC site."
      </Accordion>

      <Accordion title="update_competitor">
        Updates an existing competitor's name, alternative names, or websites.

        **Example prompts**

        * "Add bluebottle.com as an alternative website for the Blue Bottle competitor."
        * "Rename the competitor 'Blue Bottle' to 'Blue Bottle Coffee' for Acme Coffee."
      </Accordion>

      <Accordion title="archive_competitor">
        Soft-deletes a competitor from a brand's tracked list. History is preserved; the competitor just stops appearing in new data.

        **Example prompts**

        * "Stop tracking Blue Bottle as a competitor for Acme Coffee."
        * "Remove the three competitors we added last year that are no longer relevant."
      </Accordion>
    </AccordionGroup>

    ## Personas

    Manage the personas tracked alongside each brand. Personas represent distinct customer segments (for example, "first-time buyers" or "enterprise IT admins") and can be attached to prompts so you can slice metrics by audience.

    <AccordionGroup>
      <Accordion title="list_personas">
        Lists all personas configured for a brand, including their names and descriptions.

        **Example prompts**

        * "What personas do we have for Acme Coffee?"
        * "List the personas across all our brands."
      </Accordion>

      <Accordion title="create_persona">
        Creates a new persona on a brand. Requires a name and description.

        **Example prompts**

        * "Create a persona called 'Office manager' for Acme Coffee — someone responsible for stocking the office kitchen."
        * "Add a 'Home barista' persona for Acme Coffee focused on enthusiasts who grind their own beans."
      </Accordion>

      <Accordion title="archive_persona">
        Soft-deletes a persona from a brand. Historical data is preserved; the persona just stops appearing in new prompts and filters.

        **Example prompts**

        * "Archive the 'Q1 test' persona on Acme Coffee."
        * "Remove the personas we added during the pilot — they're no longer used."
      </Accordion>

      <Accordion title="update_persona_on_prompts">
        Assigns, changes, or removes the persona on a batch of prompts in one call. Pass a persona ID to attach it, or omit the persona to clear it.

        **Example prompts**

        * "Assign the 'Office manager' persona to all prompts tagged 'workplace' for Acme Coffee."
        * "Clear the persona on prompts #482, #491, and #503 — they should be persona-agnostic."
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Agent traffic">
    Bring AI bot crawl logs into Scrunch, or pull them out for analysis elsewhere. Useful for understanding how often GPTBot, ClaudeBot, PerplexityBot, and others are crawling your site.

    <AccordionGroup>
      <Accordion title="import_agent_traffic">
        Ingests agent traffic logs from a CSV. Required columns: `domain`, `user_agent`, `url`, `path`, `method`, `status_code`, `timestamp`. Bot classification happens automatically on import.

        **Example prompts**

        * "Import this week's bot traffic CSV for acmecoffee.com."
        * "Load the server logs I just exported — here's the CSV."
      </Accordion>

      <Accordion title="export_agent_traffic">
        Exports agent traffic data as a CSV. Filterable by date range, site, path, and aggregation level (day or week).

        **Example prompts**

        * "Export the last 30 days of GPTBot traffic to acmecoffee.com."
        * "Give me a weekly summary of all AI bot activity on our site in Q1."
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Help & docs">
    Answer questions about how Scrunch works. Your assistant reaches for the Help Center first, then falls back to Scrunch's public web content — always citing its sources.

    <AccordionGroup>
      <Accordion title="list_scrunch_help_collections">
        Lists every Scrunch Help Center collection and the articles inside each one. Your assistant uses this to find the article that best matches a support-style question (features, troubleshooting, onboarding, plan/billing UX), then reads it with `get_scrunch_help_article`.

        **Example prompts**

        * "How do I set up a new brand in Scrunch?"
        * "What's the difference between branded and non-branded prompts?"
      </Accordion>

      <Accordion title="get_scrunch_help_article">
        Fetches the full body of a single Help Center article by ID — discovered via `list_scrunch_help_collections`. The assistant quotes or summarizes the article and cites its URL under a `Sources:` section.

        **Example prompts**

        * "Walk me through configuring competitors, and cite the help docs."
        * "Explain how funnel stages work, with a link to the article."
      </Accordion>

      <Accordion title="fetch_scrunch_url">
        Fetches a Scrunch-owned web page and returns its main content as markdown. Used when the Help Center doesn't cover a question and the answer lives in Scrunch's public content — product and feature pages on `scrunchai.com`, or REST/SDK reference on `developers.scrunch.com`. Only `scrunch.com`, `scrunchai.com`, and `developers.scrunch.com` (and their subdomains) are allowed.

        **Example prompts**

        * "Summarize the Agent Experience Platform product page."
        * "What do the developer docs say about API authentication?"
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Utility">
    Lightweight helpers your assistant uses automatically behind the scenes.

    <AccordionGroup>
      <Accordion title="get_caller_identity">
        Returns the signed-in user's email, basic profile, and accessible brands. Your assistant calls this to determine which brands you have access to without asking you to look up a brand ID.

        **Example prompts**

        * "What brands do I have access to in Scrunch?"
        * "Which org am I connected to right now?"
      </Accordion>

      <Accordion title="get_current_date">
        Returns the server's current date in UTC. Your assistant uses this to anchor relative date phrases like "the last 30 days" or "this quarter" before constructing analytics queries. You don't need to call this directly.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>