# Agent workflows

> Step-by-step tool sequences an AI agent can follow in Convia, from drafting an on-brand post to building a campaign, revising drafts and taking posts back.

> For the complete documentation index, see [llms.txt](https://docs.conviapro.com/llms.txt).

These recipes show how an AI agent connected to Convia Pro through MCP should combine tools to get a task right the first time. Each step names the tool, the arguments that matter, and why it comes in that order. Every recipe follows the instructions the Convia MCP server sends on connection: read before you write, write drafts only, revise rather than duplicate, and ask the user when something is ambiguous.

For every parameter and return field, see the [MCP tool reference](https://docs.conviapro.com/docs/mcp-tools.md).

## Rules every recipe follows

- **Read context first.** Copy written without `get_brand_context` will not match the workspace's voice.
- **Verify before stating.** A figure, quote or claim that `search_content` cannot find in a transcript is unverified. Do not write it as fact, and never quote clip titles or descriptions as speech.
- **Use ids from results.** Never invent a post, clip, idea or account id.
- **Prefer bare dates.** Pass `scheduled_date` as `YYYY-MM-DD` so Convia applies the workspace's own posting time.
- **Drafts only.** Nothing you write is published. A dated draft sits on the calendar until a person schedules it, and a campaign stays a draft until a person activates it.
- **Ask when unsure.** A wrong draft costs the user more to find and fix than a question costs to ask.

## Draft a post in the brand's voice

Use this recipe for one post on one platform.

1. **`get_brand_context`** with no arguments. This returns the voice, audience and content rules. If `has_brand_context` is `false`, tell the user their [Brand Brain](https://docs.conviapro.com/docs/brand-brain.md) is not set up and ask whether to continue.
2. **`get_prompt_template`** with `{"surface": "platform", "platform": "linkedin"}` (or the target platform). This shows how the workspace frames copy for that platform. If `template` is `null`, Convia's default applies.
3. **`get_text_snippets`**. If the post needs a standard line, such as a call to action or outro, use the snippet text exactly as stored.
4. **`search_content`** with `{"query": "<distinctive words>", "types": ["transcript"]}` for every figure or quote you plan to use. Use the literal words, not a paraphrase. Read the surrounding passage with **`get_transcript`** (`episode_id`, plus `start_seconds` near the hit). If `speaker_name` is `null`, do not name the speaker.
5. **`list_episode_guests`** with `{"episode_ids": ["<episode id>"]}`, to spell the guest's name, job title and company correctly.
6. **`list_social_platforms`** to get the `social_account_id` for the target account.
7. **`get_schedule_settings`**, then **`list_scheduled_posts`** for the weeks you are considering (`start_date` and `end_date` are ISO 8601 with an offset, such as `2026-10-19T00:00:00Z`), so the new post does not land on a busy day.
8. Write the copy yourself.
9. **`create_post`**:

```json
{
  "content": "<your copy>",
  "social_account_id": "<id from list_social_platforms>",
  "scheduled_date": "2026-10-20",
  "source_idea_id": "<idea id, if the post came from an idea>",
  "tags": ["pricing", "founder-led sales"]
}
```

10. Report back the `url`, the resolved `scheduled_date` and any `warnings`, and remind the user the post is a draft they still need to schedule.

## Put one clip out on a given day

Use this when the user wants a clip posted without building a campaign.

1. **`list_clips`** with `{"platform": "linkedin", "max_times_used": 0, "sort": "least_used"}` to find clips never posted to that platform. Add `episode_id` to stay within one episode, or `not_used_since` to resurface older material.
2. **`get_transcript`** with the clip's `episode_id` and `clip_id` to read what is said in it. Check `offset_basis` before citing a timestamp.
3. **`get_brand_context`**, then write the caption.
4. **`get_schedule_settings`** and **`list_scheduled_posts`** to pick the day.
5. **`create_post`** with `source_clip_id`, `social_account_id` and a bare `scheduled_date`. Supply `source_clip_id` only when you are confident the clip matches: an unknown id is an error, not a text-only post.
6. Read `source_clip.times_used` in the response to confirm the clip is now counted as used.

## Turn an episode into a campaign

Use `create_campaign_from_plan` for a coordinated set of posts around one argument. Do not call `create_post` repeatedly to build a campaign. This tool needs Magic Campaign on the workspace's plan; see [Magic Campaign](https://docs.conviapro.com/docs/magic-campaign.md).

1. **`list_episodes`** to find the episode. Check `has_transcript` and `clip_count`, not `status`.
2. **`get_derived`** with `{"episode_id": "<id>"}`. If posts or a campaign already exist for this episode, show the user and ask before adding another.
3. **`get_brand_context`**.
4. **`get_transcript`** for the episode. For a long episode, page with `next_start_seconds`. Identify the one argument the campaign will make and the quotes that support it.
5. **`list_episode_guests`** with the episode's id in `episode_ids`, to name the guest correctly.
6. **`list_clips`** with `{"episode_id": "<id>", "sort": "least_used"}` to find clips for clip-backed posts.
7. **`get_schedule_settings`** and **`list_scheduled_posts`** for the campaign window.
8. Write the spine (`through_line` and `authority_objective`) and every post. Keep to one idea per campaign: for a month covering several arguments, make one call per argument with dates that do not overlap.
9. **`create_campaign_from_plan`** with `parent_webcast_id`, bare dates inside a window of 90 days or less, and at most 40 posts on at most 8 platforms. For a post that needs an asset you cannot supply, leave `content` as `""` if you have no copy, set `needed_asset` to describe it, and add `asset_instructions` with the full brief.
10. Read the response. Tell the user how many posts were created, list each entry in `gaps` (those posts are flagged with your brief), and pass on every warning, such as a platform with no connected account. Remind them to review the campaign and activate it in [Campaigns](https://docs.conviapro.com/docs/campaigns.md).

A `source_clip_id` that does not match a clip is discarded and that post is held as a gap, with a warning. That is the safe outcome, not an error.

## Revise a draft instead of duplicating it

When the user asks to change something that already exists, find it and update it.

1. Find the post. Use **`list_posts`** with `body_contains` for a phrase in the caption, or `parent_webcast_id` for an episode's posts, and `status` such as `["draft", "pending_approval", "scheduled"]`. **`get_derived`** also lists posts made from an episode, clip or idea.
2. **`get_post`** to read the full body. `update_post` replaces the whole body, so start from what is there.
3. **`update_post`** with `post_id` and only the fields that change.
4. Read the response:
   - `approval_reset: true` means the post was waiting for approval and is back in draft, so the edit is reviewed. Tell the user.
   - `post_immutable` means the post is published or approved. Tell the user to change it in the app.
   - A scheduled post stays scheduled after an edit. If the user wanted it off the calendar, use `unschedule_posts`.

Ideas and scripts work the same way: **`list_ideas`** then **`get_idea`** then **`update_idea`**, or **`list_scripts`** then **`get_script`** then **`update_script`**. An idea is never deleted: set its `status` to `archived`.

## Take posts back

Pick the tool by what the user means. Editing the text is not a way to stop a post.

| The user means | Tool |
|---|---|
| "Stop this going out, I'll decide later" | `unschedule_posts`: back to draft, scheduled date cleared |
| "We're not doing this, but keep a record" | `archive_posts`: archived, scheduled date cleared |
| "This should never have been made" | `delete_posts`: moved to Trash, restorable by a person. Unschedule first if it is scheduled |
| "Fix a typo" | `update_post`: the post stays scheduled |

1. Find the posts with **`list_posts`** (for example `status: ["scheduled"]` with `body_contains` or `parent_webcast_id`) or **`list_scheduled_posts`** for a date window.
2. Show the user the list and confirm before changing anything.
3. Call the tool with up to 25 `post_ids` and a short `reason`, such as "wrong guest named in the caption". The reason goes to the workspace's MCP audit log. For more than 25 posts, split into several calls.
4. To delete scheduled posts, call **`unschedule_posts`** first, then **`delete_posts`** with the same ids.
5. Read `updated`, `unchanged` and `refused`. `unchanged` means the post was already in that state. For each refused post, pass on the reason: a published post must be taken down on the platform itself, and an approved post must be handled in the app.

`unschedule_posts` returns each post's `previous_scheduled_date`, so you can restore the date later with `update_post`. The post then stays a draft on the calendar until a person schedules it.

## Choose what to make next from analytics

These tools need Advanced Analytics on the plan. A `null` metric means not collected yet, never zero.

1. **`list_posts`** with `{"status": ["published"]}`, optionally filtered by `platform`.
2. **`get_post_analytics`** for the posts you want to compare. Look at `performance.pace` for posts banded above the account's usual, and `analytics.engagement_rate`.
3. **`get_web_analytics`** with `{"group_by": "post"}` (or `"campaign"`) to see which posts sent people to the workspace's own website.
4. **`get_search_queries`** with `{"position_min": 8, "position_max": 20, "sort": "impressions"}` for searches where the site is close to page one, or `{"branded": "only"}` to track how often people search for the brand by name.
5. **`search_content`** on the winning topics to find source material, and **`list_clips`** with `not_used_since` to find clips worth resurfacing.
6. **`list_ideas`** with `query` to check the backlog for the same idea, then **`create_idea`** with the evidence in `notes`: the numbers, the source episode and the angle.

See [Analytics](https://docs.conviapro.com/docs/analytics.md) and [Website analytics](https://docs.conviapro.com/docs/website-analytics.md) for what each figure means.

## Grow the idea backlog

1. **`list_ideas`** with `query` for the topic, and **`get_idea`** on close matches. The user may already have had the thought.
2. **`create_idea`** for genuinely new ideas. Put the angle, the audience, the raw material (episode, timestamp, clip) and any overlap with existing ideas in `notes`, so a later session can act on it without redoing the thinking.
3. When an idea has been used or dropped, **`update_idea`** with `{"status": "archived"}`.

See [Ideas & scripts](https://docs.conviapro.com/docs/ideas-and-scripts.md).

## Manage prompt templates

An agent can read every prompt template and stage a new version, but it cannot change what Convia generates with. A person makes a staged version live.

1. **`list_prompt_templates`** to see what exists. `resolves_as: "default"` marks the live template for each content type.
2. **`get_prompt_template`** with `template_id`, or with `{"surface": "content", "content_type": "article"}` for the live one. Note `variables_used`: keep every `{placeholder}` in your revision.
3. **`get_brand_context`**, so the template does not repeat rules Convia already supplies. Some generators add less brand context than others, so keep essential voice guidance in the template.
4. **`upsert_prompt_template`** with `content_type`, a clear `name` and the full `prompt_template`. Add `template_id` only to revise an alternative you staged earlier; the live default cannot be edited.
5. Tell the user the version is saved but not live, and that a manager can make it the default in **Brand Brain → AI Prompts**.

Per-platform social prompts are read-only through MCP. If one needs changing, give the user the proposed text to paste into **Brand Brain → Social Platform Prompts**. See [How AI uses your brand](https://docs.conviapro.com/docs/how-ai-uses-your-brand.md).

## Related

- [MCP tool reference](https://docs.conviapro.com/docs/mcp-tools.md): exact parameters, limits and errors for every tool.
- [Connect an AI assistant (MCP)](https://docs.conviapro.com/docs/mcp-quickstart.md): set up the connection these recipes use.
- [MCP access, permissions & audit](https://docs.conviapro.com/docs/mcp-security.md): what an agent is allowed to do, and the Activity log.
- [Campaigns](https://docs.conviapro.com/docs/campaigns.md): what happens to a draft campaign after the agent hands it over.

---

Source: https://docs.conviapro.com/docs/mcp-workflows · Section: AI agents & MCP · Last updated: 2026-10-03