Available tools
The Whet MCP server exposes tools across three surfaces:
- Core (8) — the original agent-native primitives: pipelines, inbox, drafts, publish, platform credentials, URL ingestion.
- Sessions (18) — the drafting canvas surface (snapshot upstream items → generate variants with per-LLM overrides → export). New in U11.
- Dashboards (9) — read/write of the workspace's analytics dashboards.
Schemas below come straight from the code (apps/web/lib/mcp/tools/*); breaking changes are announced with an MCP server bump.
All mutating tools require
idempotency_key(16–128 chars) where shown — replaying with the same key returns the same run/result.
Core tools (8)
| Tool | Purpose | Side effects |
|---|---|---|
start_draft | Start a draft from an existing post. | Enqueues a run on the job runner. |
read_inbox | List a pipeline's inbox. | Read-only. |
list_posts | List raw posts of a pipeline. Paginated. | Read-only. |
diagnose_pipeline | Returns state, errors and an actionable suggested_action. | Read-only. |
create_pipeline_from_intent | Create a pipeline (or resume an existing one). | Persists pipeline + kicks off first ingest run. |
publish_artifact | Mark an artifact as published. | Mutating, must follow human confirmation. |
connect_account | Connect or rotate a platform account credential. Synchronous probe. | Persists/rotates credential. |
fetch_url | Fetch + structure a public URL via the ingestion adapter. | Persists ingestion result (and schema, if generated). |
start_draft
Starts a draft from an existing post in the inbox. The run is persisted and lands as an artifact in review state once the model finishes; the agent can poll it or subscribe to the riff.ready webhook.
| Field | Type | Required | Description |
|---|---|---|---|
source_post_id | string | yes | Source post ID. sp_<id> for ingested social posts, ws_<uuid> for webpage snapshots. |
style_reference | string (≤4000) | no | Free-form style guide the model should imitate. |
parent_artifact_id | string | no | Parent artifact (rf_<uuid> or bf_<uuid>) if this draft chains from a previous one. |
idempotency_key | string (16–128) | yes | Replaying with the same key returns the same run. |
read_inbox
Lists the pipeline's inbox — drafts in review, pending refinements, runs flagged by diagnose.
| Field | Type | Required | Description |
|---|---|---|---|
pipeline_id | string | yes | pp_<uuid> or bare uuid. |
list_posts
Paginated list of ingested source posts with engagement metrics (likes/replies/reposts/views).
| Field | Type | Required | Description |
|---|---|---|---|
pipeline_id | string | yes | pp_<uuid> or bare uuid. |
cursor | string | no | Pagination cursor from a previous call. |
limit | number (1–100) | no | Page size. |
has_artifact | boolean | no | Filter posts that already have an artifact (true) or don't (false). |
diagnose_pipeline
Structured health report: stuck runs, missing credentials, adapter cool-downs, etc. Each issue carries suggested_action and suggested_endpoint.
| Field | Type | Required | Description |
|---|---|---|---|
pipeline_id | string | yes | pp_<uuid> or bare uuid. |
create_pipeline_from_intent
Idempotent create-or-resume of a pipeline tracking a social handle. Returns pipeline reference, kicks off first ingest run.
| Field | Type | Required | Description |
|---|---|---|---|
handle | string | yes | Handle to track (with or without @). |
intent | string (10–2000) | yes | Free-form description of why this handle matters. |
tone | enum | no | neutral | punchy | analytical | snarky | formal. |
idempotency_key | string (16–128) | yes | Replaying with the same key resumes the same pipeline. |
This tool does not accept
source,kind,scope, orauto_fanout. Defaults:source=social,kind=prose,scope=per_post. Use the CLI for other shapes.
publish_artifact
Marks an artifact as published. The real publish to the destination (when the pipeline opts in via auto-fanout) is handled downstream; this tool records the operator's go-ahead.
| Field | Type | Required | Description |
|---|---|---|---|
artifact_id | string | yes | rf_<uuid> or bf_<uuid> or bare uuid. |
idempotency_key | string (16–128) | yes | Replaying with the same key is a no-op. |
The artifact must be in review/ready — calling it on a different state returns an error with suggested_action: 'fetch_artifact'.
connect_account
Connects or rotates a platform account credential. Probe runs synchronously and the response embeds the outcome.
| Field | Type | Required | Description |
|---|---|---|---|
platform | string | yes | Platform identifier. The set of supported values depends on which adapters are installed. |
handle | string | yes | Handle on the platform, lowercase enforced server-side. |
auth_material | string | yes | Primary session credential the adapter declared in its manifest. |
secondary_auth | string | no | Optional secondary credential the adapter may derive automatically. |
proxy_url | string (URL) | no | Optional SOCKS/HTTPS proxy URL for this credential. |
idempotency_key | string (16–128) | yes |
fetch_url
Fetch a public HTTPS URL via the ingestion adapter. Mode determines parsing:
| Field | Type | Required | Description |
|---|---|---|---|
url | string (HTTPS, ≤2048) | yes | Target URL. |
mode | enum | no | markdown | css | llm | auto. Default auto (CSS first, LLM fallback). |
intent | string (1–2000) | no | Required for css/llm/auto unless schema_id is provided. |
schema_id | string | no | Reuse a previously generated schema. |
Repeat fetches for the same (url, intent) pair hit the cache after the first call.
Sessions tools (18)
The drafting canvas: snapshot upstream items into a session, attach variants with per-variant LLM and preset, generate rounds, export. See Sessions for the full model.
Lifecycle
| Tool | Params | Effect |
|---|---|---|
session_create | name? | Create empty canvas for the active (org, user). Returns id + name. |
session_list | limit (1–50, default 20) | List sessions ordered by last_active_at desc, with item/variant counts. |
session_get | sessionId | Load full session: items, variants with rounds, sources, recent activity. |
session_update | sessionId, name (nullable) | Rename a session. |
session_delete | sessionId | Cascade-delete session + items + variants + rounds + exports. Irreversible. |
Selection (items)
| Tool | Params | Effect |
|---|---|---|
session_add_item | sessionId, upstreamItemId?, sourceId?, sourceKind, externalItemId?, title, snippet, capturedAt, metrics?, raw? | Snapshot an upstream item (social post / webpage / RSS / custom) into the session. Immutable snapshot. |
session_remove_item | sessionId, sessionItemId | Drop a snapshotted item. Upstream untouched. |
session_clear_selection | sessionId | Remove every item. Variants and rounds stay. |
Variants
| Tool | Params | Effect |
|---|---|---|
session_add_variant | sessionId, presetId, userPresetId?, prompt, style, typeTag, llmCredentialId? | Add a variant with preset + prompt + style. Starts status=idle. |
session_update_variant | variantId, prompt?, style?, llmCredentialId? | Patch variant config. Omit a field to leave it unchanged. |
session_remove_variant | variantId | Delete variant. Cascades to rounds + exports. |
session_select_round | variantId, roundIndex | Switch the variant's active round (0-based, clamps to valid range). |
session_generate_variant | variantId, sessionId | Queue LLM generation. Returns when the round is generated or status if still queued. |
session_generate_all | sessionId | Queue generation for every variant in the session. |
session_variant_rounds | variantId | List round history (oldest first) without loading the full session. |
Exports + presets
| Tool | Params | Effect |
|---|---|---|
session_export_variant | sessionId, variantId, roundId?, format (default markdown) | Record an export event (logs session_export; backs the EXPORTS 7D KPI). |
session_save_preset | name, description, prompt, style, typeTag | Persist a variant config as a named user preset (scoped per org + user). |
Sources (read-only)
| Tool | Params | Effect |
|---|---|---|
session_list_sources | — | List the workspace's connected sources (social handles, webpages, RSS feeds) for the session item picker. |
Dashboards tools (9)
Read/write access to the workspace's analytics dashboards. Widgets are validated against the dataset catalog at write time and resolved at execute time.
| Tool | Params | Effect |
|---|---|---|
dashboards_list | — | List dashboards in the active workspace, ordered by most-recently updated. |
dashboards_get | id | Load dashboard + all widgets in creation order. Does not execute widgets. |
dashboards_create | name, description?, templateId?, layout? | Provision a new dashboard. With templateId, seeds widgets. |
dashboards_delete | id | Hard-delete dashboard + cascade widgets. Only the creator can call. |
dashboards_create_widget | dashboardId, title, type (kpi/timeseries/donut/bar/topN/table), querySpec, position?, visualization? | Append a widget. Validates querySpec against the dataset catalog. |
dashboards_update_widget | widgetId, title?, querySpec?, position?, visualization? | Patch a widget. Re-validates querySpec. |
dashboards_delete_widget | widgetId | Remove widget + matching layout entry. |
dashboards_list_datasets | — | Return the catalog: metric names, dimension names, filters, groupBy buckets per dataset. Tenant scoping info included. |
dashboards_execute_widget | widgetId, timeRange? (override, not persisted) | Run the widget's querySpec through the resolver; return QueryResult (current/previous/partial). |
Common errors
All tools return errors with shape { error: { code, message, suggested_action?, suggested_endpoint? } }. Main codes:
unauthorized— invalid or revoked token.not_found— resource doesn't exist in the deployment.validation_failed— params don't satisfy the schema.messagetells you what's missing.state_conflict— the resource isn't in a valid state for the operation.credential_missing/credential_dead— the adapter has no usable credentials. Pair withconnect_account.
Errors include suggested_action when there's a concrete, agent-actionable next step that doesn't require a human in the loop.