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

# MCP tools reference

> Complete list of Spotlight MCP tools and their REST equivalents.

Spotlight MCP exposes **20 tools**. Each tool calls the same backend as the REST API. Parameters use camelCase in MCP; REST paths use the standard URL structure documented in the [API reference](/api-reference/discovery).

## Context and discovery

| Tool                        | Description                                                                            | REST equivalent                    |
| --------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------- |
| `get_organization_context`  | Organization plan and brand count. Call once per session.                              | `GET /v1/organization/context`     |
| `get_brand_context`         | Brand targeting, prompt quota, schedule, and estimated next fetch. Requires `brandId`. | `GET /v1/brands/{brandId}/context` |
| `get_spotlight_usage_guide` | Returns Markdown guidance for agents (prompt style, quotas, scheduling).               | Built-in guide                     |
| `list_brands`               | All brands in the organization.                                                        | `GET /v1/brands`                   |

## Brands, runs, and results

| Tool                          | Description                                                              | REST equivalent                            |
| ----------------------------- | ------------------------------------------------------------------------ | ------------------------------------------ |
| `list_brand_runs`             | Historical analysis runs for a brand. Supports `page`, `limit`.          | `GET /v1/brands/{brandId}/runs`            |
| `get_run_results`             | Per-prompt results for a run. Optional `includeAnswer`, `page`, `limit`. | `GET /v1/runs/{runId}`                     |
| `get_brand_last_results`      | Latest run results for a brand.                                          | `GET /v1/brands/{brandId}/last/results`    |
| `get_run_stats`               | Aggregate metrics, topic breakdown, and top mentioned brands.            | `GET /v1/runs/{runId}/stats`               |
| `get_run_sources`             | Cited URLs grouped by domain for a run.                                  | `GET /v1/runs/{runId}/sources`             |
| `get_run_content_suggestions` | AI content ideas for a run. Supports pagination.                         | `GET /v1/runs/{runId}/content-suggestions` |

## Perception

| Tool                                     | Description                                                 | REST equivalent                                         |
| ---------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------- |
| `get_brand_perception_prompts_responses` | Perception prompts and scored responses. Optional `runId`.  | `GET /v1/brands/{brandId}/perception-prompts-responses` |
| `get_run_perception_prompts_responses`   | Perception data for a specific run.                         | `GET /v1/runs/{runId}/perception-prompts-responses`     |
| `add_perception_prompts`                 | Add branded perception prompts with optional scoring logic. | `POST /v1/brands/{brandId}/perception-prompts`          |

## Topics and prompts (write)

| Tool                              | Description                                                   | REST equivalent                                  |
| --------------------------------- | ------------------------------------------------------------- | ------------------------------------------------ |
| `batch_create_topics_and_prompts` | Create multiple topics and prompts in one call.               | `POST /v1/brands/{brandId}/topics-prompts/batch` |
| `create_topics`                   | Create one or more topics.                                    | `POST /v1/brands/{brandId}/topics`               |
| `create_prompts_in_topic`         | Add prompts under an existing topic. Returns remaining slots. | `POST /v1/topics/{topicId}/prompts`              |
| `delete_prompt`                   | Delete a single prompt. Prefer `delete_prompts` for multiple. | `POST /v1/prompts/batch-delete`                  |
| `delete_prompts`                  | Delete multiple prompts in one request.                       | `POST /v1/prompts/batch-delete`                  |
| `delete_topic`                    | Delete a topic and all prompts under it.                      | `DELETE /v1/topics/{topicId}`                    |

## Tool details

### `get_brand_context`

**Required:** `brandId`

Returns:

* Language and target market
* Prompt quota (`remainingSlots`, limits)
* Topic and prompt counts
* Report schedule and `nextEstimatedScheduledFetchAt`

Call this before creating or deleting prompts so the agent respects plan limits.

### `get_run_results` / `get_brand_last_results`

**Required:** `runId` or `brandId`

**Optional:** `includeAnswer` (boolean, default `false`), `page`, `limit` (max 500)

Set `includeAnswer: true` only when you need raw LLM response text — responses can be large.

### `add_perception_prompts`

**Required:** `brandId`, `prompts` (array)

Each prompt object:

| Field                    | Required | Description                                 |
| ------------------------ | -------- | ------------------------------------------- |
| `text`                   | Yes      | Perception prompt text (branded)            |
| `propertyId`             | No       | Perception property ID (defaults to Custom) |
| `scoringLogic`           | No       | Object or string defining how to score      |
| `goodScore` / `badScore` | No       | Shorthand score labels                      |

Requires custom perception prompts to be enabled on the brand's plan.

### `batch_create_topics_and_prompts`

**Required:** `brandId`, `topics` (array)

Each topic may include an existing `id` or a new `name`, plus a `prompts` array. Every prompt must belong to a topic. Prompt limits are enforced.

Write tools return `nextScheduledRunAt` and a scheduling note — new prompts run on the **next scheduled report**, not immediately.

## Discovering tools programmatically

MCP clients can call `tools/list` (JSON-RPC) to retrieve the live tool catalog with JSON Schema input definitions. A `GET` request to the MCP endpoint returns server metadata:

```bash theme={null}
curl -s "https://app.get-spotlight.com/api/mcp"
```

```json theme={null}
{
  "name": "spotlight-org-api-mcp",
  "protocol": "mcp",
  "transport": "http",
  "endpoint": "/functions/v1/org-api-mcp"
}
```