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

# MCP tools reference

> Reference for every tool the Rheos MCP server exposes — posts, brands, formulas, images, video, scheduling and publishing — with parameters and payloads.

<Warning>
  **Work in progress** — connector not yet publicly available. Email **[hello@rheos.app](mailto:hello@rheos.app)** for early access.
</Warning>

This is the full technical reference for everything the Rheos connector can do. If you're an end user, you probably don't need this — your AI chat picks the right tool automatically. It's useful if you're building agent workflows or want to know exactly what's possible.

This page lists every tool the Rheos MCP server registers, with the parameters
your assistant needs to know about. Each tool returns a JSON payload — the
shapes shown below are summaries; call the tool and inspect the response for
the full schema.

<Note>
  Almost every tool takes a `brand_id` (short ID like `default_f7634e61`). Start any session with `rheos_list_brands` to discover valid IDs, or call `rheos_get_context` to grab brand + formulas + reference data in one call.
</Note>

## Posts

CRUD for posts, pillars, campaigns and other Rheos records. `resource_type`
selects the collection.

### `rheos_list`

List records of a given type for the user or brand.

* **`resource_type`** — `"posts" | "pillars" | "campaigns" | "brands" | ...`
* **`brand_id`** *(optional)* — filter to one brand
* **`status`** *(optional)* — e.g. `"draft"`, `"idea"`, `"scheduled"`, `"published"`
* **`limit`** *(optional)*

### `rheos_get`

Fetch a single record by id.

* **`resource_type`** — same enum as `rheos_list`
* **`id`** — record id

### `rheos_create`

Create a record. For `resource_type="posts"` this is the canonical drafting
endpoint — pass `brand_id`, `textBody`, and any formula fields (`intent`,
`hookId`, `ctaId`) you've picked from `rheos_get_formulas`.

```json theme={null}
{
  "resource_type": "posts",
  "brand_id": "default_f7634e61",
  "fields": {
    "textBody": "We just shipped...",
    "intent": "announce",
    "hookId": "before-after",
    "ctaId": "learn-more",
    "channels": ["linkedin", "instagram"],
    "assetIds": ["asset_abc123"]
  }
}
```

### `rheos_update`

Patch fields on an existing record. Use this after `rheos_accept_idea` to
write the post body, or to edit a draft before scheduling.

* **`resource_type`**, **`id`**, **`fields`** — partial update object

## Ideation

Formula-aware idea generation. Ideas live as posts with `status="idea"`;
accepting one flips it to `status="draft"`.

### `rheos_brainstorm`

Calls the Genkit `postBrainstormFlow`. Returns a list of formula-aware ideas
suitable for picking one and writing the body yourself with `rheos_create`.

* **`brand_id`** *(required)*
* **`topic`** *(optional)* — seed concept
* **`count`** *(optional)* — defaults to a small batch

### `rheos_generate_ideas`

Persists a batch of new ideas (posts with `status="idea"`) and returns their
`idea_ids`. Use when you want the user to pick from a queue rather than
inline-brainstorm.

* **`brand_id`** *(required)*
* **`count`**, **`intent`**, **`hook_type`**, **`audience_name`**, **`theme_title`** *(optional)* — bias the set toward a formula slot, audience or theme

### `rheos_accept_idea`

Flips one idea from `status="idea"` to `status="draft"`. After accepting,
write the body in the brand voice and save it via `rheos_update`.

* **`idea_id`** *(required)*

### `rheos_refresh_idea`

Regenerates a single idea in place — keeps the id, replaces the content.

* **`idea_id`** *(required)*

## Publishing

Move a draft to scheduled or live across one or more channels.

### `rheos_schedule_post`

Queue a post for a future time. Status moves to `scheduled`; the backend
cron picks it up at `scheduled_at`. The post publishes to the channels already
set on the draft.

* **`post_id`** *(required)*
* **`scheduled_at`** — ISO 8601 timestamp

### `rheos_publish_post`

Publish immediately to the channels set on the draft. Returns per-channel
`publishResults` — inspect `results[].error` if any channel fails.

* **`post_id`** *(required)*

### `rheos_cancel_scheduled`

Pull a scheduled post back to draft so you can edit or delete it.

* **`post_id`** *(required)*

### `rheos_connect_platform`

Returns a dashboard OAuth deep-link the user can open in a browser to
connect Instagram, LinkedIn, Facebook, etc.

* **`channel`** — `"instagram" | "linkedin" | "facebook" | ...`
* **`brand_id`** *(required)*

## Brands & identity

Read and update the brand identity document, the sources that feed it, and
the metadata stored on the brand record.

### `rheos_list_brands`

List every brand in the org (both business and personal). Call this **first**
in any drafting flow — every subsequent tool needs a `brand_id`.

### `rheos_get_context`

Bundle call: returns the brand record, identity document, pillars, audiences,
themes, and formulas in one response. Use it at the start of a drafting
session to seed the assistant with everything it needs.

* **`brand_id`** *(required)*

### `rheos_view_brand_document`

Read the freeform markdown identity document for a brand — the synthesised
output of all sources.

* **`brand_id`** *(required)*
* **`version`** *(optional)* — pick an older version

### `rheos_view_brand_sources`

List every source attached to the brand (website scrape, AI import, uploaded
docs) with status and timestamps.

* **`brand_id`** *(required)*

### `rheos_view_source`

Read the full content of a single source.

* **`brand_id`**, **`source_id`**

### `rheos_update_ai_import`

Write or replace the AI-import source — the one external write path into the
brand's source set. Personal brands use this instead of `rheos_scrape_website`.

* **`brand_id`** *(required)*
* **`content`** — markdown body

### `rheos_scrape_website`

Scrape a URL via Firecrawl (Cheerio fallback) and populate the brand's
website source. Business brands only.

* **`brand_id`** *(required)*
* **`url`** *(required)*

### `rheos_trigger_identity_doc_flow`

Synthesise all active sources into the brand identity document. Call after
populating sources via `rheos_update_ai_import` or `rheos_scrape_website`.

* **`brand_id`** *(required)*
* **`regenerate`** *(optional)* — force a fresh synthesis even if cached

### `rheos_update_brand_metadata`

Set structured fields on the brand record (name, tone, audience labels, etc.)
without re-running the full identity flow.

* **`brand_id`** *(required)*
* **`fields`** — partial metadata patch

## Images

Generate, iterate, upload and save image assets. Generated images return
inline as base64; saved assets get an `asset_id` you pass into `rheos_create`.

### `rheos_image_generate`

Generate or iterate an image inside an ephemeral session. Pass
`iterate_from_generation_id` to refine instead of starting fresh.

* **`brand_id`** *(required)*
* **`prompt`** *(required)*
* **`session_id`** *(optional)* — resume an existing session
* **`iterate_from_generation_id`** *(optional)*

### `rheos_image_save_asset`

Promote a generation into the brand's asset library so it can be attached
to a post.

* **`session_id`**, **`generation_id`** — from the previous `rheos_image_generate` call

### `rheos_upload_image`

Store an externally-generated image (PNG / JPEG / WebP, ≤10 MB) as a Rheos
asset. Returns an `asset_id`.

* **`brand_id`** *(required)*
* **`image_base64`** or **`image_url`**
* **`alt_text`** *(optional)*

### `rheos_draft_post_from_image`

One-shot: upload an image **and** draft a caption + post in a single call.
Preferred over `rheos_upload_image` + `rheos_create` when the user already
has a topic in mind.

* **`brand_id`** *(required)*
* **`image_base64`** or **`image_url`**
* **`topic`** *(optional)*
* **`hook_type`** *(optional)* — formula hook label

## Video

Session-based video editing: get the current scenes, edit them, render via
AWS Lambda, then have Gemini review the MP4.

### `rheos_video_get_session`

Fetch the current scenes and metadata for a video session.

* **`session_id`** *(required)*

### `rheos_video_update_scenes`

Apply scene-level edits (text layers, timing, asset swaps). For AI-suggested
edits prefer `rheos_video_apply_suggestions` — it preserves layer ids.

* **`session_id`** *(required)*
* **`scenes`** — full scene array

### `rheos_video_render`

Kick off the Lambda render. Returns `render_id` + `bucket_name` — poll
progress with `rheos_video_render_progress` every 3–5 seconds.

* **`session_id`** *(required)*

### `rheos_video_render_progress`

Poll a render. Returns `done`, `progress`, and (when complete) the MP4 URL.

* **`render_id`**, **`bucket_name`**

### `rheos_video_review`

Send the rendered MP4 to Gemini for critique. Returns text suggestions you
can feed back into `rheos_video_apply_suggestions`.

* **`session_id`** *(required)*

### `rheos_video_apply_suggestions`

Patch scenes from a review's suggestions. Preserves layer ids so animations
don't reset. After applying, re-render with `rheos_video_render`.

* **`session_id`**, **`suggestions`** — from `rheos_video_review`

## Search

### `rheos_search_posts`

Substring search over a brand's posts (drafts + scheduled + published).

* **`brand_id`** *(required)*
* **`query`** *(required)*

### `rheos_search_assets`

Basic text matching against the asset library (filename, alt text, prompt).

* **`brand_id`** *(required)*
* **`query`** *(required)*

## Reference

Small read-only helpers split out so they don't bloat `rheos_get_context`.

### `rheos_get_formulas`

Return the static formula tree: 8 intents × 35+ hooks × 10 CTAs. Use to seed
`rheos_brainstorm` or to validate fields before `rheos_create`.

### `rheos_list_audiences`

Extract the union of audiences across a brand's pillars.

* **`brand_id`** *(required)*

### `rheos_list_themes`

Extract the union of themes across a brand's pillars.

* **`brand_id`** *(required)*

### `rheos_get_platforms`

List connected social platforms for the user with token status and expiry.

### `rheos_get_credits`

Return the user's current credit balance and the credit cost of common
operations.

### `rheos_fetch_docs`

Fetch a page from `rheos.app/docs` as markdown — useful for grounding an
assistant in product help articles. Pass no URL to get the docs index.

* **`url`** *(optional)* — must be on `rheos.app`

## Conventions

* **Errors** come back as `{ error, hint, next_step }` — the `hint` tells the
  caller which tool to invoke next (e.g. *"Call `rheos_list_brands` first"*).
* **All timestamps** are ISO 8601 in UTC.
* **`brand_id`** for personal brands is the user's `user_id`; for business
  brands it's the short id from `rheos_list_brands`.
* **Credits** are deducted on tool success, not invocation. A failed
  `rheos_image_generate` won't charge you.