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

# Tools

> The 41 MCP tools: 20 read tools and 21 write tools, grouped by area.

Read tools are available with the `mcp:read` scope (granted automatically).
Write tools additionally require `mcp:write`, which you grant explicitly on
the consent page. Calling a write tool without it returns JSON-RPC error
`-32002 missing scope: mcp:write`.

## Read tools

| Tool                    | What it returns                                             |
| ----------------------- | ----------------------------------------------------------- |
| `whoami`                | Your identity, scopes, and token status for this session    |
| `list_projects`         | Projects you can access                                     |
| `list_brands`           | Tracked brands and competitors in a project                 |
| `list_prompts`          | The project's prompt set                                    |
| `list_topics`           | Topics organizing the prompt set                            |
| `list_tags`             | Tags on prompts                                             |
| `list_channels`         | The AI surfaces (model channels) enabled for tracking       |
| `list_models`           | Models behind the channels                                  |
| `list_chats`            | Captured AI answers, filterable by prompt/channel/date      |
| `get_chat`              | One captured answer with its cited sources                  |
| `list_search_queries`   | Search sub-queries the engines ran answering your prompts   |
| `list_shopping_queries` | Shopping sub-queries the engines ran answering your prompts |
| `get_brand_report`      | Brand metrics report (visibility, position, SoV, …)         |
| `get_domain_report`     | Cited-source report aggregated by domain                    |
| `get_url_report`        | Cited-source report aggregated by URL                       |
| `get_url_content`       | Stored content/classification for a cited URL               |
| `get_actions`           | Recommended actions for the project                         |
| `get_action_rollups`    | Action counts by status/type                                |
| `get_scan_status`       | Per-day scan completeness for a project                     |
| `get_project_profile`   | The project profile Mavel uses for analysis                 |

## Write tools

| Tool                           | What it does                                     |
| ------------------------------ | ------------------------------------------------ |
| `create_prompt`                | Add a prompt                                     |
| `create_prompts_bulk`          | Add prompts in bulk                              |
| `update_prompt`                | Edit a prompt                                    |
| `delete_prompt`                | Remove a prompt                                  |
| `classify_prompts`             | Re-run intent classification on up to 20 prompts |
| `create_brand`                 | Add a brand or competitor                        |
| `create_brands_bulk`           | Add brands in bulk                               |
| `update_brand`                 | Edit a brand                                     |
| `delete_brand`                 | Remove a brand                                   |
| `accept_brand_suggestion`      | Accept a suggested brand                         |
| `reject_brand_suggestion`      | Dismiss a suggested brand                        |
| `create_topic`                 | Add a topic                                      |
| `delete_topic`                 | Remove a topic                                   |
| `create_tag`                   | Add a tag                                        |
| `delete_tag`                   | Remove a tag                                     |
| `assign_tag`                   | Attach a tag to up to 50 prompts                 |
| `unassign_tag`                 | Detach a tag from up to 50 prompts               |
| `set_project_profile`          | Update the project profile                       |
| `transition_action`            | Move an action between statuses                  |
| `delete_url_content`           | Remove stored content for a cited URL            |
| `update_domain_classification` | Manually reclassify a domain for your project    |

## Notable tool behavior

* **`get_brand_report`** in raw mode (no `group_by`) orders rows newest
  first (date descending), so the 500-row-per-call cap returns your most
  recent window instead of the oldest day of a multi-day query. Grouped
  mode (`group_by` set) stays chronological, oldest first.
* **`get_url_report`** rows include a `brand_mentioned` boolean: true when
  your own brand was mentioned in at least one chat that cited that URL
  during the window, the same signal the dashboard's Sources table uses for
  its "Mentioned" column.
* **`get_chat`** rows include `prompt_text`, the source prompt's text at
  capture time; null when that prompt has since been deleted.
* **`list_search_queries`** and **`list_shopping_queries`** return the
  fan-out sub-queries the AI engines ran while answering your project's
  prompts. Raw mode is one row per (query, chat), starting with `chat_id`:
  pass that with the row's `date` to `get_chat` to open the full captured
  chat behind any query. Each row also carries an `own_brand_cited`
  boolean (true when that same chat also cites one of your own-brand
  domains). Optional `group_by=query` instead returns one row per distinct
  query with `occurrences` and `own_brand_cited_count`: the content-gap
  list of queries the engines ran that never cite you, ranked by how often
  each one came up. `list_shopping_queries` is the same shape filtered to
  shopping sub-queries (naturally rarer, since they only appear behind a
  rendered product carousel). Both require a `start_date`/`end_date`
  window, capped at 92 days per call; `limit`/`offset` must be a real
  integer (a number, or the exact string form of one, like `"40"`, the
  same rule every paginated tool's `limit`/`offset` follows) or the call
  fails with `-32602` (`error.data.code` = `MCP_ARG_INVALID`) instead of
  silently falling back to the default page size. `summary.channels_capturing`
  is derived per call from this project's own captured data in the
  requested window (any query type,
  ignoring this call's channel/prompt filters), so it is always a superset
  of the channels in the returned rows and can never contradict them; an
  empty result means nothing was captured for this project in this
  window, not that no fan-outs happened anywhere (see issue #1774 for
  which channels have fan-out capture wired at all). Absence of data is
  not evidence of absence of fan-outs, the same principle behind every
  partial-coverage tool in this catalog. Data-quality caveat:
  `perplexity-0` rows currently mix Perplexity's related/suggested-question
  strings in with executed search fan-outs (issue #2101); weigh
  `perplexity-0` aggregates accordingly until that lands.
* **`update_domain_classification`** writes are scoped to your project: a
  manual reclassification only changes what your project sees. Other
  projects citing the same domain, including ones in a different org, are
  unaffected. Every report or table that shows a domain's classification
  reads the effective value: your project's override if you've set one,
  otherwise the shared classification.
* **`classify_prompts`** is subject to a per-organization daily budget set
  by your plan. Exceeding it fails the whole call with a
  `PLAN_LIMIT_REACHED` error naming the UTC time the budget resets.

## Calling tools directly

Tools are ordinary JSON-RPC 2.0 calls. See
[Authentication](/mcp/authentication) for the full protocol surface.

```bash theme={null}
curl https://mcp.mavel.ai/api/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_brand_report","arguments":{"project_id":"<uuid>"}}}'
```