> ## 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 best practices

> Recommended workflows for AI agents using Spotlight MCP.

These guidelines help AI assistants use Spotlight MCP safely and effectively. Agents can also call **`get_spotlight_usage_guide`** at runtime to retrieve this guidance as Markdown.

## Recommended session flow

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Spotlight MCP

    Agent->>Spotlight MCP: get_organization_context
    Spotlight MCP-->>Agent: plan, brand count
    Agent->>Spotlight MCP: list_brands
    Spotlight MCP-->>Agent: brand IDs
    Agent->>Spotlight MCP: get_brand_context (per brand)
    Spotlight MCP-->>Agent: quota, schedule, targeting
    Note over Agent,Spotlight MCP: Read or write data as needed
```

1. **`get_organization_context`** — once per session; confirms auth and plan scope.
2. **`list_brands`** — pick which brand(s) to work with.
3. **`get_brand_context`** — before any prompt edits or limit-sensitive operations.
4. **`get_spotlight_usage_guide`** — when writing or restructuring prompts.

## Regular analysis prompts

Regular prompts power your weekly AI visibility reports. Write them like real search queries:

* **Neutral and unbranded** — do not include the client's brand name in the prompt text.
* **Consideration-stage** when appropriate — comparison, evaluation, migration, pricing models, and "how to choose" intents reflect discovery behavior.
* **Topic-organized** — every prompt belongs to a topic. Use `batch_create_topics_and_prompts` for bulk setup.

### Quota awareness

`get_brand_context` returns `promptQuota.remainingSlots`. Never create more prompts than remaining slots allow. If the quota is exhausted, delete unused prompts with `delete_prompts` before adding new ones.

### Bulk deletes

When removing multiple prompts, use **`delete_prompts`** with all IDs in one call. Do not call `delete_prompt` repeatedly — it is slower and wastes rate limit quota.

## Perception prompts

Perception prompts are **branded** — they evaluate how the brand is perceived on specific properties (trust, clarity, etc.).

* Use **`add_perception_prompts`** to create them.
* Include **`scoringLogic`** (or `goodScore` / `badScore`) when scores need to be interpretable.
* Read results with `get_brand_perception_prompts_responses` or `get_run_perception_prompts_responses`.

Custom perception prompts must be enabled on your plan.

## Scheduled data collection

Prompt and topic changes do **not** trigger an immediate analysis run. New and updated prompts are picked up on the **next scheduled report**.

After write operations, tools may return:

* `nextScheduledRunAt` — estimated time of the next run
* `schedulingNote` — explains that timing is approximate

`nextEstimatedScheduledFetchAt` from `get_brand_context` is derived from schedule frequency and last activity. Actual cron timing may differ slightly.

## Reading analysis data

| Goal                  | Suggested tools                                                                   |
| --------------------- | --------------------------------------------------------------------------------- |
| Latest snapshot       | `get_brand_last_results`, `get_run_stats` on latest run ID from `list_brand_runs` |
| Historical comparison | `list_brand_runs` then `get_run_stats` per run                                    |
| Citations and sources | `get_run_sources`                                                                 |
| Content backlog ideas | `get_run_content_suggestions`                                                     |
| Full LLM answers      | `get_run_results` with `includeAnswer: true` (large payloads)                     |

Prefer `get_run_stats` for dashboards and summaries — it returns pre-aggregated metrics including topic breakdown and top mentioned brands.

## Scope and permissions

* One API key = **one organization**. You cannot access other orgs' data.
* User role restrictions apply: **viewer** and **guest** accounts are read-only and cannot use write tools.
* Rate limit defaults to **120 requests per minute** per organization.

## Example agent prompts

These are natural-language instructions you can give a connected assistant:

```text theme={null}
List all brands in my Spotlight organization and show how many prompts each has.
```

```text theme={null}
For brand BRAND_ID, summarize the latest run stats and top 5 mentioned competitors.
```

```text theme={null}
Add a topic called "Enterprise security" with three neutral comparison prompts.
Check remaining prompt slots first.
```

```text theme={null}
Export all perception prompt responses from the latest run for brand BRAND_ID.
```

## Related docs

<CardGroup cols={2}>
  <Card title="Connect an MCP client" icon="link" href="/spotlight-mcp/connect">
    Cursor, Claude Desktop, and generic HTTP setup.
  </Card>

  <Card title="Tools reference" icon="wrench" href="/spotlight-mcp/tools">
    Full tool list with parameters.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API keys and rate limits.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/errors">
    HTTP status codes and troubleshooting.
  </Card>
</CardGroup>