Tools reference
The Phase 1 tool surface, grouped by intent. Every mutation returns the updated entity.
Discovery & context
| Tool | Description |
|---|---|
list_projects | Projects the caller can access |
get_project_brand | The whole brand in one call: positioning, voices, audiences (each with its companies, personas and topics), proof points — read before writing or reviewing so drafts stay on-brand |
list_collections | Collections in a project (filter by type/status); each row carries the persona_ids it targets and its topic |
pipeline_status | Dashboard: publications/promos by status, upcoming scheduled_for, stale items |
get_publication | Full publication incl. promos, media, reviews |
list_publications | Filter by project, collection, status |
search_content | Text search across titles, subtitles, summaries and bodies |
Planning
| Tool | Description |
|---|---|
create_collection | New campaign or section (dates derive from the schedule); optional targeted personas + outlets |
update_collection | Edit a campaign's name/slug/type/description/personas/outlets |
set_campaign_topic | Set or clear the one topic a campaign is about; frozen onto the campaign once it launches |
delete_collection | Permanently delete a campaign and all its publications + promos |
create_stub | Title + idea + collection → publication in stub |
batch_create_stubs | Plan a whole campaign in one call |
Writing & review — publications
| Tool | Description |
|---|---|
update_draft | Write/edit title, subtitle, summary, body, notes; moves stub → draft when a body is added. A patch — only the fields you pass change, and an empty string clears one |
submit_for_review | draft → reviewing |
review_publication | Record a review; approve → approved, request_changes → draft with notes |
archive_publication | → archived |
Going live is start_promoting (below), which took over mark_published's canonical_url argument when published merged into promoting.
Promos
| Tool | Description |
|---|---|
start_promoting | approved → promoting, the live state. Requires canonical_url — the address the piece now lives at, which every promo links to. Returns the channel list + per-channel constraints from channels.config, including the max_chars each channel's promos are held to. Idempotent on a publication already promoting, so it doubles as the way to re-read those constraints mid-campaign |
create_promo | Channel-ready copy for one channel; starts in draft. A publication can have several promos per channel — pass an optional internal name to tell them apart (never published). Optional kind (text default, or image) is the post type, fixed at creation: an image promo posts its attached image with the body as caption. Optional account aims it at a posting identity (see list_promo_accounts); omitted, it takes the channel's default account, or the project's own profile when there is none. A body over the channel's max_chars is rejected |
update_promo | Edit the internal name (any time before published; empty string clears it), the copy (draft only, and subject to the same max_chars limit), or the scheduled_for (any time before published). Omit a field to leave it unchanged |
list_promo_accounts | The identities a promo can post as on this project — the project's own profile, or a company page it administers. A channel is which platform, an account is which identity on it. Optionally filtered by channel. Rows with archived_at set are pages the platform no longer reports, and rows with enabled false are ones the owner switched off — never aim a new promo at either; the database refuses both. The row with is_default true is what a promo posts as when account is omitted |
set_promo_account | Point an existing promo at an account, or omit account to reset it to the project profile. Refused once published, or while a scheduled post is pending — that queued post already carries its destination, so unschedule it first |
submit_promo_for_review | draft → reviewing. An image promo must have its image attached first |
publish_promo | For manual channels: record external_url, → published. Auto channels dispatch through upload-post from the Promos page, not this tool |
review_promo | Record a promo verdict. approve → scheduled, and books the post with upload-post in the same call. Refused if the promo has no scheduled_for or its time has passed — set a future one with update_promo first. request_changes → back to draft. The reply's scheduled field says whether a job was created; false means a manual channel you publish yourself |
reopen_promo | scheduled → draft for edits. A promo with a pending upload-post scheduled post must be unscheduled first |
delete_promo | Permanently delete an unpublished, unscheduled promo. Published promos can't be deleted |
Brand editing
One entity per call, each gated to project owners and managers. Ids are uuids — read them from get_project_brand. An omitted field is left unchanged; a supplied array replaces that list wholesale. See Brand & audiences for what these fields mean.
| Tool | Description |
|---|---|
set_brand_positioning | Set (or clear, with an empty string) the positioning line |
add_brand_voice / update_brand_voice | A voice: tone, style, personality, words to use and avoid |
add_brand_audience / update_brand_audience | An audience: name, description, colour, goals, and the voices it is written in |
add_brand_company / update_brand_company | The ideal customer company as an archetype — name, one-liner, narrative — added to an audience |
add_brand_persona / update_brand_persona | A person inside that company: name, role, optional company_id in the same audience, narrative, pains, hooks |
add_brand_topic / update_brand_topic | An angle written for one audience, optionally aimed at personas inside it; update can move it to another audience |
add_brand_proof / update_brand_proof | A proof point, tagged with the audiences it lands with (none = all) |
Deleting brand content is not exposed to agents
Removing an audience, company, persona, topic or voice happens in the web app, where a human can see what goes with it — deleting an audience takes its profiles, and deleting a persona stops every campaign that targeted it. Archiving is the reversible alternative and is also UI-only.
Media
| Tool | Description |
|---|---|
upload_media_from_url | Fetch an image or video URL into Supabase Storage, create a media row |
list_media | Media for a project. public_url is the durable URL to use when placing an image in a body; it is null until the asset has been placed or published |
attach_media | Link media to a publication or promo (with position). Promo attachments are draft-only — frozen from review through dispatch. On a publication this records that the piece uses an asset; where an image sits in an article is expressed by Markdown in the body |
Example call
Advance a publication to review
await client.callTool("submit_for_review", {
publication: "pub_9f21",
});
Transitions are validated
Calling a tool that would skip statuses returns a structured invalid-transition error naming the current status and allowed next states. Move items one legal step at a time.