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

# Capabilities

> The tools the Cited MCP server exposes — resolvers to discover your brands and dimensions, and read tools for AI shelf and the Cited Index.

Every Cited MCP tool authenticates with your API key and is scoped to the brands your key can access. **Call `whoami` or `list_brands` first** — the `brand_id` values they return are what the other tools expect.

## Resolver tools

### `whoami`

Returns your key's identity: its scopes and the brands it can access.

```json theme={null}
{ "key_id": "…", "scopes": ["read"], "rate_tier": "standard",
  "brands": [{ "brand_id": "…", "role": "brand_admin" }] }
```

### `list_brands`

The brands your key can access, with names and websites. A single-brand key returns one; an agency (multi-brand) key returns all granted brands — loop over these to run a report per brand.

### `list_dimensions`

**Args:** `brand_id`

The filterable dimensions for a brand: the AI **platforms** tracked, the **competitors** configured, and the **topics** covered. Use these to scope other tools.

```json theme={null}
{ "brand_id": "…", "platforms": ["openai", "perplexity"],
  "competitors": ["…"], "topics": ["Personal loans", "Credit cards"] }
```

## Read tools

### `get_ai_shelf_products`

**Args:** `brand_id`, `days` (default 30), `platform` (optional), `limit` (default 50)

The products AI shopping answers show for your brand's category — title, position, whether it's **you vs a competitor**, merchant, price, platform, and topic.

<Note>Requires the **Scale plan or higher** (or a per-brand override).</Note>

```json theme={null}
{ "brand_id": "…", "window_days": 30, "count": 12,
  "products": [{ "product": "…", "platform": "chatgpt", "position": 2,
    "attribution": "you", "merchant": "Amazon", "price": 9.99, "topic": "…" }] }
```

### `get_cited_index`

**Args:** `edition` (optional — latest if omitted), `category` (optional — id, slug, or name), `top_n` (default 10)

The **Cited Index** — India's AI-visibility ranking of brands across categories and LLMs. Market-wide data (not scoped to your brand); any valid key can read it. Returns the top brands per category for an edition.

```json theme={null}
{ "edition": "june-2026", "verticals": [{ "vertical": "D2C",
  "categories": [{ "category": "Skincare", "slug": "skincare",
    "top_brands": [{ "rank": 1, "name": "…", "score": 88.0,
      "sentiment": "positive", "avg_position": 1.2 }] }] }] }
```

## Coming soon

* **Metric tools** — `cube_slice` / `cube_drill`: a single, composable, recursive query over Cited's conformed **metrics cube** (visibility, share of voice, citation share, by platform / topic / domain / page). Returns the exact numbers the dashboard shows.
* **Action tools** — generate a content brief, find source targets, create a task: run Cited's execution layer from your assistant.

## Errors

Tools return an error (surfaced as an MCP tool error) when: the API key is missing/invalid/expired or revoked (`Invalid API key`), the key isn't granted the requested brand (`API key not granted this brand`), the plan doesn't include the feature (e.g. `AI Shelf requires the Scale plan or higher`), or a rate limit is hit (`Rate limit exceeded`).