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

# Tools

> Full reference for all MentionPilot MCP tools — inputs, outputs, and usage examples.

The MentionPilot MCP Server exposes **7 tools**. All tools are read-only (`readOnlyHint: true`) and require a valid API key passed as a Bearer token.

<Tip>
  Always call `list_brands` first to get the brand IDs required by the other tools.
</Tip>

***

## list\_brands

Returns all brands in your MentionPilot account.

**Inputs:** none

**Example output:**

```
Your MentionPilot brands (2 total):

• Acme Corp (ID: 42) — domain: acme.com — created: 2024-11-01
• Acme Labs (ID: 43) — domain: labs.acme.com — created: 2025-01-15
```

***

## brand\_report

Aggregated AI visibility, sentiment, and position metrics for a brand across all tracked prompts.

**Inputs:**

| Parameter   | Type      | Required | Description                                                         |
| ----------- | --------- | -------- | ------------------------------------------------------------------- |
| `brand_id`  | number    | Yes      | Brand ID from `list_brands`                                         |
| `date.from` | string    | No       | Start date (`YYYY-MM-DD`)                                           |
| `date.to`   | string    | No       | End date (`YYYY-MM-DD`)                                             |
| `ai_agent`  | string\[] | No       | Filter by platform: `chatgpt`, `gemini`, `perplexity`, `aioverview` |

**Example output:**

```
📊 Brand Report: Acme Corp

Visibility:       64% — how often your brand appears in AI answers
Sentiment:        71/100 — how positively AI describes your brand
Avg Position:     2.3 — where you appear in AI responses (lower = better)
Total Responses:  1,840 AI answers analyzed
```

***

## list\_prompts

Returns all tracked prompts for a brand, including their active/paused status.

**Inputs:**

| Parameter   | Type   | Required | Description                         |
| ----------- | ------ | -------- | ----------------------------------- |
| `brand_id`  | number | Yes      | Brand ID                            |
| `date.from` | string | No       | Start date                          |
| `date.to`   | string | No       | End date                            |
| `limit`     | number | No       | Maximum number of prompts to return |

**Example output:**

```
Tracked prompts for brand ID 42 (3):

• [ID: 101] ✅ "best CRM software for startups" — added 2024-11-01
• [ID: 102] ✅ "top tools for sales teams" — added 2024-11-01
• [ID: 103] ⏸️ "CRM alternatives to Salesforce" — added 2025-01-10
```

***

## prompt\_report

Visibility, sentiment, and position metrics broken down per tracked prompt.

**Inputs:**

| Parameter   | Type      | Required | Description                                     |
| ----------- | --------- | -------- | ----------------------------------------------- |
| `prompt_id` | number    | No       | Specific prompt ID — omit to return all prompts |
| `date.from` | string    | No       | Start date                                      |
| `date.to`   | string    | No       | End date                                        |
| `ai_agent`  | string\[] | No       | Filter by platform                              |
| `limit`     | number    | No       | Maximum results to return                       |

**Example output:**

```
Prompt Performance Report (2 prompts):

📝 "best CRM software for startups"
   Brand: Acme Corp | Responses: 620
   Visibility: 78% | Sentiment: 74/100 | Position: 1.8

📝 "top tools for sales teams"
   Brand: Acme Corp | Responses: 540
   Visibility: 55% | Sentiment: 68/100 | Position: 3.1
```

***

## competitor\_report

Visibility, sentiment, and position for all tracked competitors of a brand, ranked by visibility.

**Inputs:**

| Parameter  | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `brand_id` | number | Yes      | Brand ID    |

**Example output:**

```
Competitor Intelligence for brand ID 42 (ranked by visibility):

1. Rival Inc (rival.io)
   Visibility: 82% | Sentiment: 69/100 | Position: 1.5 | Responses: 1,840

2. OtherCo (otherco.com)
   Visibility: 41% | Sentiment: 72/100 | Position: 3.9 | Responses: 1,840
```

***

## sources\_report

The web domains AI platforms cite when mentioning your brand — useful for PR targeting and content gap analysis.

**Inputs:**

| Parameter   | Type      | Required | Description               |
| ----------- | --------- | -------- | ------------------------- |
| `brand_id`  | number    | Yes      | Brand ID                  |
| `date.from` | string    | No       | Start date                |
| `date.to`   | string    | No       | End date                  |
| `ai_agent`  | string\[] | No       | Filter by platform        |
| `limit`     | number    | No       | Maximum sources to return |

**Example output:**

```
Citation Sources for brand ID 42 (38 total, 12 unique domains):

• g2.com — cited 14 times
• capterra.com — cited 9 times
• techcrunch.com — cited 6 times
• forbes.com — cited 4 times
```

***

## visibility\_summary

A full natural-language narrative of a brand's AI visibility performance — ideal for weekly reports, Slack updates, or executive briefings.

**Inputs:**

| Parameter   | Type      | Required | Description        |
| ----------- | --------- | -------- | ------------------ |
| `brand_id`  | number    | Yes      | Brand ID           |
| `date.from` | string    | No       | Start date         |
| `date.to`   | string    | No       | End date           |
| `ai_agent`  | string\[] | No       | Filter by platform |

This tool fetches the brand report, prompt report, and competitor report in parallel and composes a single cohesive summary. Use it when you need a human-readable overview rather than raw numbers.

***

## AI platform filter values

Use these values in the `ai_agent` array parameter:

| Value        | Platform            |
| ------------ | ------------------- |
| `chatgpt`    | ChatGPT (OpenAI)    |
| `gemini`     | Gemini (Google)     |
| `perplexity` | Perplexity AI       |
| `aioverview` | Google AI Overviews |