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.

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"
}