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

# MCP tools reference

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

rocketblue MCP exposes **23 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).

Some REST convenience routes (for example `.../last/sources` or `.../last/content-suggestions`) do not have a dedicated MCP tool — use the run-scoped tools after resolving the latest run with `list_brand_runs`.

## 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_usage_guide`          | Returns Markdown guidance for agents (prompt style, quotas, scheduling).               | Built-in guide                     |
| `list_brands`              | All brands in the organization.                                                        | `GET /v1/brands`                   |

## Created content

| Tool                         | Description                                                                    | REST equivalent                                 |
| ---------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------- |
| `list_brand_created_content` | Paginated draft metadata for a brand (title, excerpt, prompt, featured image). | `GET /v1/brands/{brandId}/contents`             |
| `get_created_content`        | Full draft markdown plus schema/JSON-LD/research sources.                      | `GET /v1/brands/{brandId}/contents/{contentId}` |

## 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` |

## Web search queries

| Tool                           | Description                                                      | REST equivalent                               |
| ------------------------------ | ---------------------------------------------------------------- | --------------------------------------------- |
| `get_run_web_search_queries`   | Queries LLMs used during a run. Optional `promptId`, `llmNames`. | `GET /v1/runs/{runId}/web-search-queries`     |
| `get_brand_web_search_queries` | Same for a brand (latest run unless `runId` is set).             | `GET /v1/brands/{brandId}/web-search-queries` |

## 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 (implemented via batch-delete). 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.

### `get_run_web_search_queries` / `get_brand_web_search_queries`

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

**Optional:** `promptId`, `llmNames` (array of LLM names such as `chatgpt`, `perplexity`)

Use these to mine the exact queries models ran while answering your prompts — useful for content briefs and AEO keyword lists.

### `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.rocketblue.ai/api/mcp"
```

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