Agent workflows

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.

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 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:

{
  "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.

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.

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.

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 and Website analytics 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.

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.

Related

• MCP tool reference: exact parameters, limits and errors for every tool.
• Connect an AI assistant (MCP): set up the connection these recipes use.
• MCP access, permissions & audit: what an agent is allowed to do, and the Activity log.
• Campaigns: what happens to a draft campaign after the agent hands it over.