Examples

Three common flows illustrated as agent ↔ MCP interactions. Each step uses the real schemas documented in Tools and Prompts and resources.

1. Create a pipeline from an intent

Operator (in chat): "Start tracking @growth_dr and build me analytical drafts for each post."

1. Agent invokes create_pipeline_from_intent with:

   {
     "handle": "growth_dr",
     "intent": "Track this competitor and turn their high-engagement posts into analytical drafts we can refine.",
     "tone": "analytical",
     "idempotency_key": "init-growth-dr-2026-05-16-001"
   }

2. MCP responds with { pipeline_id, run_id }.
3. Agent confirms to the operator with a link to the pipeline in the UI or the ID to use with read_inbox.

Limitation: this tool creates pipelines with source=social, kind=prose, scope=per_post. For --auto-fanout, another source, kind=structured or digest scopes, you need to use the CLI or the UI.

2. Diagnose a pipeline that is not producing

Operator: "Why hasn't pp_a1b2c3 been giving me drafts for 2 days?"

1. Agent invokes diagnose_pipeline with { "pipeline_id": "pp_a1b2c3" }.
2. MCP responds with shape:

   {
     "status": "running",
     "last_run": { "id": "run_5xyz", "status": "failed", "error_code": "credential_dead" },
     "suggested_action": "rotate_credential",
     "suggested_endpoint": "connect_account"
   }

3. Agent explains to the operator: "The adapter ran out of live credentials for this account. Let me walk you through the rotation wizard."
4. If the operator pastes fresh credentials into the chat (not recommended but possible), the agent invokes connect_account with { platform, handle, auth_material, idempotency_key }. The probe runs synchronously and the response indicates whether the credential works.

3. Refine pending drafts and publish

Operator: "Tell me what's ready in the inbox for pp_a1b2c3 and refine the long ones for me."

1. Agent invokes read_inbox with { "pipeline_id": "pp_a1b2c3" }.
2. MCP returns the inbox rows. The agent reviews the preview values and detects drafts longer than 280 characters.
3. For each one, the agent invokes the refine_post prompt with:

   {
     "artifact_id": "rf_4f5g",
     "goal": "shorter and punchier, keep the numbered-list hook"
   }

   The prompt returns a narrated workflow — the agent follows it: reads the artifact via artifact://rf_4f5g, decides refinement_type=shorter, triggers the refinement, polls, and finally invokes publish_artifact on the child if the operator approves.
4. The agent presents the operator with the list (originals + variants) and asks which ones to publish — one by one, not in a silent batch.

4. Drive a drafting session end-to-end

Operator: "Open a session, drop the top 3 posts from pp_a1b2c3, and try two variants — one thread, one long-form."

1. Agent invokes session_create with { "name": "growth_dr · 2026-05-23" }. MCP returns the new session id.
2. Agent invokes read_inbox / list_posts against pp_a1b2c3 and picks the 3 highest-engagement posts.
3. For each post, agent invokes session_add_item with the snapshot fields (sourceKind: "social", externalItemId, title, snippet, capturedAt, metrics, raw).
4. Agent invokes session_add_variant twice:

   { "sessionId": "...", "presetId": "social-thread", "prompt": "Thread on growth tactics, hook-driven", "style": "punchy, numbered", "typeTag": "thread" }

   { "sessionId": "...", "presetId": "long-form", "prompt": "Long-form post, analytical takeaway", "style": "professional, paragraph", "typeTag": "long-form" }

5. Agent invokes session_generate_all with { "sessionId": "..." }. MCP queues both variants; each generation appends a variant_round.
6. Agent invokes session_get to read the latest rounds and presents both variants to the operator.
7. Operator picks the thread; agent invokes session_export_variant with { sessionId, variantId, format: "markdown" } to record the export event.

Sessions don't publish. Exporting records an event and returns the round text — what happens next (paste into your destination, schedule via another tool) lives outside Whet.

Patterns to avoid

• Do not invoke publish_artifact in batch without confirmation. Each publish is an explicit operator intent. An agent that publishes everything ready without asking breaks the product contract.
• Do not re-implement ingestion from the agent. If you need more data, use list_posts or create another pipeline — do not try to fetch from upstream platforms on your own.
• Do not store the idempotency_key in the chat. Generate it on the agent side with a UUIDv4 and discard it after the call. Reusing the same key against another pipeline confuses the idempotent replacement.
• Do not assume create_pipeline_from_intent can modify an existing pipeline. The tool creates or resumes the same pipeline when the idempotency_key is reused. For configuration changes, you need to go to the UI or the CLI.

Cost model

Each tool call consumes resources from the operator's deployment (Postgres queries, LLM calls in many cases). Whet does not bill per MCP call — the cost is in the retainer/setup fee. If you build an agent that consumes intensively, respect the Agent API rate limits (documented in Integrations · Errors).