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

# Use Cases

> Example prompts and workflows for the Peec AI MCP Server. Browse by type if you need ideas on what to ask.

Start by asking your AI assistant to list your projects, then pick one:

> *"List my Peec AI projects"*

<Tip>
  Include a time range in your questions. *"Last 30 days"*, *"this month"*, or *"past week"* gets you better results.
</Tip>

<Note>
  For the most common workflows (weekly pulse, competitor radar, engine scorecard, source audit, campaign tracker), use a built-in [prompt](/mcp/prompts) instead. One slash command runs the full analysis and formats the output.
</Note>

## Example workflows

### 1. Brand visibility overview

> *"How visible is my brand across AI search engines this month?"*

Returns your visibility percentage, sentiment score, share of voice, and average position across all tracked AI models.

### 2. Competitive benchmarking by AI model

> *"Compare our visibility against competitors, broken down by AI model"*

Table showing each brand's visibility across ChatGPT, Perplexity, Gemini, and other platforms. See where you lead and where competitors outperform you.

### 3. Source citation analysis

> *"Which of our pages get cited most by AI engines?"*

Ranked list of your URLs with citation counts, retrieval numbers, and page types.

### 4. Topic deep-dive

> *"How do we perform on the topic 'sustainable fashion' vs competitors?"*

Brand-by-brand comparison within a specific topic: visibility, share of voice, and sentiment.

### 5. Visibility trend

> *"Show me our visibility trend over the last 30 days"*

Daily visibility data with notable changes highlighted.

## More ideas

### Brand visibility

<AccordionGroup>
  <Accordion title="Visibility by AI model">
    > *"Break down our brand visibility by AI model for the past two weeks."*

    Get an overview of your performance for each AI model.
  </Accordion>

  <Accordion title="Topic-level performance">
    > *"Which topics have the highest and lowest visibility for our brand?"*

    Identify the strengths and weaknesses in your AI search presence.
  </Accordion>
</AccordionGroup>

### Competitive analysis

<AccordionGroup>
  <Accordion title="Share of voice comparison">
    > *"Compare our share of voice against all competitors for the last month."*

    Your mention share vs the competitive set.
  </Accordion>

  <Accordion title="Sentiment comparison">
    > *"How does our sentiment compare to \[competitor name] on ChatGPT?"*

    Find out how positively AI models describe you vs a specific competitor.
  </Accordion>

  <Accordion title="Position analysis">
    > *"Which competitor is mentioned first most often across all AI models?"*

    Understand who consistently wins the top position in AI responses.
  </Accordion>
</AccordionGroup>

### Sources and citations

<AccordionGroup>
  <Accordion title="Top cited domains">
    > *"What are the most cited domains in AI responses for our prompts?"*

    Use this to understand which websites have the most authority in your space.
  </Accordion>

  <Accordion title="Your domain's performance">
    > *"How often is our website retrieved and cited? Break it down by AI model."*

    You can make these kinds of queries to gain an idea of how your domain's source authority is across AI platforms.
  </Accordion>

  <Accordion title="Competitor source analysis">
    > *"Which competitor domains have the highest citation rate?"*

    Find out which competitor websites AI treats as authoritative.
  </Accordion>

  <Accordion title="Inspect why a URL wins citations">
    > *"Pull the content of the top-cited competitor URL on the topic 'project management tools' and tell me what it covers that our own page doesn't."*

    The MCP fetches the scraped markdown of the source Peec has indexed, so your AI assistant can compare structure, depth, and framing against your own content.
  </Accordion>
</AccordionGroup>

### Reporting

<AccordionGroup>
  <Accordion title="Weekly performance summary">
    > *"Give me a weekly summary: our visibility, share of voice, and sentiment for the past 7 days vs the previous 7 days."*

    A quick health check you can run every week.
  </Accordion>

  <Accordion title="Country-level breakdown">
    > *"Break down our visibility by country for the last month."*

    Understand the geographic differences in your AI search presence if you have prompts in multiple markets.
  </Accordion>

  <Accordion title="Content gap analysis">
    > *"Which topics have high competitor visibility but low visibility for our brand?"*

    Find opportunities where competitors are visible, but you're not.
  </Accordion>
</AccordionGroup>

### Actions and next steps

<AccordionGroup>
  <Accordion title="Ranked next steps for the quarter">
    > *"What should we focus on next quarter to improve AI visibility?"*

    Returns Peec's opportunity-scored recommendations grouped by owned pages, editorial coverage, reference sites, and UGC communities. No invented advice. Rankings are computed from your actual visibility gaps.
  </Accordion>

  <Accordion title="Drill into a specific opportunity">
    > *"Our biggest opportunity is UGC on YouTube. What specifically should we do there?"*

    The MCP first calls the actions overview to surface the opportunity, then drills into the UGC domain with concrete outreach suggestions (creators to contact, formats that work).
  </Accordion>
</AccordionGroup>

### Agent analytics

Pair these with [Crawl Insights](/crawl-insights). The MCP exposes the same access-log data via [`list_bots`](/mcp/tools#list-bots) and [`get_agent_visits`](/mcp/tools#get-agent-visits), so an assistant can answer ad-hoc questions without leaving the chat.

<AccordionGroup>
  <Accordion title="Which AI bots are hitting our site?">
    > *"Break down AI bot visits to our site by bot for the last 30 days."*

    Returns a ranked list of bots (`GPTBot`, `ClaudeBot`, `PerplexityBot`, ...) with visit counts. Group by `bot_id` to see who's crawling you most.
  </Accordion>

  <Accordion title="What's our failure rate for AI bots?">
    > *"Group AI bot visits by response status for the last 7 days. Show me the share of 4xx and 5xx."*

    Surfaces non-200 responses bots received. High shares of `403`, `404`, or `5xx` codes are a signal that crawlers can't reach the content you want indexed.
  </Accordion>

  <Accordion title="Which folders are bots crawling most?">
    > *"For the last 30 days, group AI bot visits by request path. Which sections of the site get the most attention?"*

    Returns paths sorted by visit count. Useful for confirming whether bots are spending time on the pages you most care about ranking in AI responses.
  </Accordion>

  <Accordion title="Has crawl activity changed over time?">
    > *"Show me daily AI bot visits over the last 90 days. Highlight any drops or spikes."*

    Uses `time_bucket=day` to return a daily series. Pair with bot grouping to see whether one vendor is responsible for a change.
  </Accordion>

  <Accordion title="Tie bot traffic to AI visibility">
    > *"For the top 20 URLs by AI bot visits last month, also pull their retrieval and citation counts as AI sources."*

    Combines [`get_agent_visits`](/mcp/tools#get-agent-visits) grouped by `request_path` with [`get_url_report`](/mcp/tools#get-url-report). Surfaces whether the pages bots crawl most are the same pages winning AI citations.
  </Accordion>
</AccordionGroup>

### Shopping

For [shopping projects](/setting-up-shopping-prompts), the MCP exposes product-level visibility, the attribute grid AI builds for your catalog, and the product sub-queries engines fan out to. Products are either claimed (`CATALOG`) or AI-detected (`LLM`).

<AccordionGroup>
  <Accordion title="Which of our products win in AI shopping answers?">
    > *"Show our top and bottom products by AI visibility over the last 30 days."*

    Uses `list_products` ordered by `visibility`. Each row carries mentions, wins, average position, and share of voice. Filter by `category_ids` or `source` (`CATALOG` vs `LLM`) to narrow it down.
  </Accordion>

  <Accordion title="Why does a competitor's product beat ours?">
    > *"Compare our running shoe against the top competitors on the attributes AI mentions."*

    Calls `get_shopping_attributes` with `scope=product`. Returns the characteristics, true/false facts, and ordinal dimensions the models associate with each product, side by side with competitors.
  </Accordion>

  <Accordion title="What sub-queries do engines run for our category?">
    > *"List the shopping sub-queries behind our category prompts last week, and the products each returned."*

    Uses `list_shopping_queries`. Pass a returned `chat_id` to [`get_chat`](/mcp/tools#get-chat) to read the full answer that produced them.
  </Accordion>

  <Accordion title="Load a product catalog">
    > *"Add these 40 products under our brand, in a Shoes > Running category."*

    The assistant resolves the `global_brand_id` with `list_global_brands`, builds the tree with `create_categories`, then calls `create_products` with the category attached — after you confirm.
  </Accordion>
</AccordionGroup>

### Edit your project setup

<AccordionGroup>
  <Accordion title="Add a prompt you just thought of">
    > *"Add this prompt to my project: 'best CRM for remote sales teams 2026'. Target US, tag it 'competitive'."*

    The assistant resolves the tag and the project, then confirms with you before calling `create_prompt`.
  </Accordion>

  <Accordion title="Re-organize prompts under a new topic">
    > *"Create a topic called 'Pricing' and move every prompt that mentions 'cost' or 'pricing' into it."*

    The assistant lists matching prompts first, creates the topic, and calls `update_prompt` for each one. Only after you confirm the list.
  </Accordion>

  <Accordion title="Track a new competitor brand">
    > *"Start tracking Acme as a competitor. Their domains are acme.com and getacme.io, and they also go by 'Acme Labs'."*

    The assistant calls `create_brand` with the domains and aliases you provided.
  </Accordion>

  <Accordion title="Clean up stale tags">
    > *"List my tags, tell me which ones are attached to fewer than 3 prompts, and delete those after I confirm."*

    The assistant uses `list_tags` and `list_prompts`, surfaces the low-use tags, and only calls `delete_tag` for the ones you approve.
  </Accordion>

  <Accordion title="Add a batch of prompts in one go">
    > *"Here are 30 prompts from our customer-research doc. Add them to my project under the 'Discovery' topic, all targeting the US."*

    The assistant resolves the topic ID once, then calls `create_prompts` with all 30 entries in a single batch. Duplicates and any IDs that don't resolve come back per-item so nothing silently fails.
  </Accordion>

  <Accordion title="Refine your brand profile so prompt suggestions improve">
    > *"Read my current brand profile, change the industry to 'B2B SaaS', and add 'AI search analytics' to our product list."*

    The assistant calls `get_project_profile`, shows you the current values, merges your changes, and calls `set_project_profile` after you confirm. Saving triggers a refresh of the AI-generated prompt suggestions.
  </Accordion>
</AccordionGroup>

### Workflows validated in the MCP Challenge

<AccordionGroup>
  <Accordion title="Fix outdated information in AI sources">
    > *"After our pricing change last week, find every URL AI models are citing for pricing-related prompts that still mentions the old price. Draft personalized outreach emails to each publication."*

    The MCP pulls `get_url_report` and `get_domain_report` for pricing topics, uses `get_url_content` to inspect which pages still reference the old price, and drafts outreach. Works for any stale information (pricing, product names, feature lists). Add a Gmail or Firecrawl MCP to the session to send the outreach in the same flow.
  </Accordion>

  <Accordion title="Find which of your pages are losing AI citations">
    > *"For our owned domain, show URLs whose retrieval rate dropped most over the last 90 days compared to the prior 90. Rank them by the size of the drop. These are our content-refresh priorities."*

    Pulls `get_url_report` with `date` dimension filtered to your domain, computes rolling-window deltas, and surfaces URLs where AI engines are citing you less over time. Content refresh is a high-leverage GEO action. Phrase the query to explicitly compare time windows. Vague queries like "which content needs a refresh?" tend to return a generic gap analysis instead of a time-decay ranking.
  </Accordion>

  <Accordion title="Find the prompts where a competitor beats you">
    > *"For every prompt we track, compare our visibility to \[Competitor] and rank the prompts where they beat us most."*

    `get_brand_report` dimensioned by `prompt_id` for both brands returns a ranked gap table. Output: the exact queries where the competitor is mentioned and you are not. Use `list_prompts` to resolve `prompt_id` values to the actual prompt text for the final ranking.
  </Accordion>

  <Accordion title="Find the URL hurting your brand">
    > *"Which URLs are AI models citing most when they describe us negatively?"*

    The MCP pulls `get_url_report` for top-retrieved pages, cross-references with per-chat sentiment via `list_chats` + `get_chat`, and surfaces the specific URLs dragging the score down. Often: an old review, a negative forum thread, or a competitor comparison page.
  </Accordion>
</AccordionGroup>

## Tips

To make the experience smoother or complete, take a look at the following tips:

* **Include dates:** Always specify a time range (e.g. "Last 7 days", "Last month").
* **Name brands:** Mention specific competitors by name (e.g. "How do I compare against \[competitor]?").
* **Ask for breakdowns:** *"Break down by model"* or *"split by topic"* gives per-dimension results.
* **Start broad, then drill down:** Start with your overview, then follow up on what stands out.