Tool reference
Generated from the server itself, so this is exactly what a client receives on tools/list.
Every tool except list_brands takes an optional brand argument. It is required once your account has more than one brand. See Brands.
The server reports itself as Postlyra Server, version 1.0.0, and exposes 7 tools.
list_brands
List the brands (workspaces) this token can act on. Every other tool accepts an optional "brand" argument taking one of the returned brand_id values — required when the account has more than one brand. Call this once at the start of a multi-brand session.
read-only, idempotent
Takes no arguments.
get_mining_context
Fetch this team's idea-mining context: source refs already attached to existing ideas (drop matching commits before mining), the team's voice guide, content pillars, persona, and a summary of recently-known ideas/published hooks to avoid repeating. Call this first, before reading any git log.
read-only, idempotent
| Argument | Type | Description | |
|---|---|---|---|
brand | string | optional | Optional: the brand (workspace) to act on — a brand_id from list_brands. Required when the account has more than one brand. |
push_ideas
Push up to 25 finished content ideas mined from the caller's own machine (e.g. a local git log). Each idea needs a headline and at least one source_ref — a stable identity string for the work it came from, e.g. "postlyra@abc1234" (repo-label@short-sha). Re-pushing the same headline with the same source_refs updates the existing idea instead of creating a duplicate. Ideas land with status "new" in Studio's review queue — this never creates a draft, approves anything, or publishes anything; only a human in Studio can do that.
idempotent
| Argument | Type | Description | |
|---|---|---|---|
brand | string | optional | Optional: the brand (workspace) to act on — a brand_id from list_brands. Required when the account has more than one brand. |
ideas | array of object | required | 1-25 ideas to push. |
ideas[] fields
| Field | Type | Description | |
|---|---|---|---|
headline | string | required | The idea headline. Required, max 500 characters. |
angle | string | optional | Optional: the angle/description for the idea. |
pillar | string | optional | Optional: the content pillar this idea belongs to. |
format | string | optional | Optional: linkedin, reel, carousel, or video. Unrecognized or missing values default to linkedin. |
recording | string | optional | Optional: recording/shot instructions for a reel-format idea. |
source_refs | array of string | required | Required: at least one stable identity string for the work this idea was mined from, e.g. "repo-label@short-sha". |
list_ideas
List this team's content ideas, newest-mined first, optionally filtered by status or format. Capped at 50 results — use get_idea for one idea's full detail including its source refs and linked drafts.
read-only, idempotent
| Argument | Type | Description | |
|---|---|---|---|
brand | string | optional | Optional: the brand (workspace) to act on — a brand_id from list_brands. Required when the account has more than one brand. |
status | enum: new, promoted, dismissed, shortlisted | optional | Optional: filter to one status (new, promoted, dismissed, shortlisted). |
format | enum: linkedin, reel, carousel, video | optional | Optional: filter to one format (linkedin, reel, carousel, video). |
get_idea
Get one idea by id: its headline/description/pillar/format/status, the source refs it was mined from, and any drafts already promoted from it (id + status only — use Studio to see or edit a draft's content).
read-only, idempotent
| Argument | Type | Description | |
|---|---|---|---|
brand | string | optional | Optional: the brand (workspace) to act on — a brand_id from list_brands. Required when the account has more than one brand. |
idea_id | integer | required | The idea id, e.g. from list_ideas or push_ideas' response. |
list_content_profiles
List the brand's content profiles — the per-draft content identities (name, handle, pillars) a draft can be styled and grounded with. create_draft accepts one of the returned ids as content_profile_id. Pillars are the profile's content pillar labels; a draft's optional "pillar" should be one of the pillar KEYS shown here.
read-only, idempotent
| Argument | Type | Description | |
|---|---|---|---|
brand | string | optional | Optional: the brand (workspace) to act on — a brand_id from list_brands. Required when the account has more than one brand. |
create_draft
Create an UNAPPROVED draft in a brand's Planning queue — e.g. "write a LinkedIn post for brand X, planned tomorrow 09:10". Takes a kind (linkedin, reel, carousel, or video), the body text, and optionally a title, a content_profile_id from list_content_profiles, a pillar key (LinkedIn only), and a planned date/time. The draft always lands with status "draft" awaiting human review: this tool can never approve, schedule a publish, or publish — plan_date/plan_time only place it on the planning calendar, and only a human in Studio can approve it and make anything go out.
| Argument | Type | Description | |
|---|---|---|---|
brand | string | optional | Optional: the brand (workspace) to act on — a brand_id from list_brands. Required when the account has more than one brand. |
kind | enum: linkedin, reel, carousel, video | required | The draft kind: linkedin (a LinkedIn post), reel (an Instagram reel script), carousel (an Instagram carousel), or video. |
body | string | required | The draft body — the post text (or script) itself. |
title | string | optional | Optional: a short working title, max 255 characters. |
content_profile_id | integer | optional | Optional: the content profile (identity) this draft belongs to — an id from list_content_profiles. |
pillar | string | optional | Optional: a content pillar KEY from the profile's pillars in list_content_profiles (e.g. "B"). Only meaningful for kind "linkedin"; ignored otherwise. |
plan_date | string | optional | Optional: the planning-calendar date, Y-m-d. Purely a plan — publishing still requires human approval in Studio. |
plan_time | string | optional | Optional: the planning-calendar time, 24h H:i (e.g. "09:10"). |
Server instructions
The server ships this instruction block to clients on connect. It is worth reading, because it is what shapes how an agent uses the tools.
Tools for managing content ideas across the brands (workspaces) the
caller's bearer token can access. One account-level token serves every
brand the user belongs to; each call is pinned to exactly one brand:
pass a brand_id from list_brands in the tool's optional "brand"
argument. An account with a single brand needs no argument; an account
with several gets an error naming list_brands if the argument is
missing. There is no way to reach a brand the token's user doesn't
belong to. In a multi-brand session, call list_brands once up front and
pass "brand" explicitly on every subsequent call.
Idea mining runs client-side, not on this server (docs/plans/2026-08-11
idea-import-and-cli.md): this server never reads anyone's git history.
The intended flow for an AI agent running on the operator's own machine
is: (1) call get_mining_context to fetch the team's voice guide,
content pillars, persona, and already-known source refs;
(2) read the user's LOCAL git log yourself — you run on their machine,
they don't — and drop any commit whose "<repo-label>@<short-sha>" ref
already appears in the refs the context call returned; (3) draft ideas
grounded in that voice/pillars/persona, each carrying source_refs built
the same way (e.g. "postlyra@abc1234"); (4) call push_ideas with the
result. Re-pushing the same headline + source_refs updates the existing
idea instead of duplicating it, so it is safe to re-run mining.
list_ideas and get_idea are read-only lookups over what has already been
pushed or created in Studio. All dates are Y-m-d.
Drafting (2026-08-15): create_draft writes a draft straight into a
brand's Planning queue — "write a LinkedIn post for brand X, planned
tomorrow 09:10" is list_content_profiles (to pick the identity and a
pillar key) followed by create_draft with plan_date/plan_time. A planned
date/time is a calendar note, not a publish slot.
HARD RULE: no tool on this server (or any other Postlyra surface) can
approve or publish anything. Pushed ideas land as status "new" and
created drafts land as status "draft" — approving a draft and
publishing it require a human acting in Studio. Never imply to a user
that push_ideas or create_draft published or scheduled content for
publishing; they only add items to the human review queue.