MCP tools reference - Spotlight Docs

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.

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:

curl -s "https://app.get-spotlight.com/api/mcp"

{
  "name": "spotlight-org-api-mcp",
  "protocol": "mcp",
  "transport": "http",
  "endpoint": "/functions/v1/org-api-mcp"
}

​Context and discovery

​Brands, runs, and results

​Perception

​Topics and prompts (write)

​Tool details

​get_brand_context

​get_run_results / get_brand_last_results

​add_perception_prompts

​batch_create_topics_and_prompts

​Discovering tools programmatically