> ## 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 the 28 Scrunch MCP features across metrics, responses, brands, competitors, personas, prompts, tags, and agent traffic, with example prompts.

Scrunch's MCP connection gives your AI assistant access to 28 features across 9 categories. These are called automatically in response to natural-language prompts — you never need to reference them by name. The descriptions and example prompts below show what each one does and how to ask for it.

***

## 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>

***

## 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>

***

## 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>

***

## 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>

***

## 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>

***

## 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>