MCP tools

These 58 tools are loaded as soon as you connect. Everything else is in the catalog, reachable through find_actions.

Tools that change something say so in their description: your AI calls them only when you asked for it in the conversation, never on its own initiative.

Your profile

get_me

Who I am on X. Load this before writing anything for the user. Returns the account’s voice and style guide with real example lines, audience, goals, products, takes, rules, facts Xholic knows about them, and connected accounts. Treat strong beliefs as facts and weak ones as hints. Never invent facts beyond these.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: me.get · REST and CLI

Field	Type	Required	Description
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Accounts

list_accounts

Connected X accounts. List the X accounts this connection can act on (own, added and shared), with your role on each and which one is the default. Pass an account’s @handle as account on any other tool to act on it.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: accounts.list · REST and CLI

No input.

Context and voice

get_writing_kit

Writing kit. Material for writing posts in the user’s voice: real posts that worked (their own winners, their circle this week, bookmarks, library outliers) to build each new post from, fresh facts and takes, and what they posted lately so you don’t repeat it. Write the posts yourself from this kit, one subject per post, then run check_draft. Never copy a source post’s claims or numbers as the user’s own.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: context.writing_kit · REST and CLI

Field	Type	Required	Description
topic	string ≤ 200 chars	No	Optional subject to pull material for.
limit	integer 1–20	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Updates

get_updates

What happened since last time. Call at the start of a conversation. Returns what happened since this connection last checked: posts that went live or failed, posts doing better than usual, new leads, DMs, Worker drafts waiting, mentions and replies. Lead with what needs the user.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: events.updates · REST and CLI

Field	Type	Required	Description
since	string ≤ 40 chars	No	Cursor from a previous call. Leave it out to continue from the last check.
limit	integer 1–100	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Insights

whats_working

What’s working. What worked for the account over a period and why: best posts, formats, topics and times, compared with their normal. Use it before planning content.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: insights.whats_working · REST and CLI

Field	Type	Required	Description
range	“today” \	“7d” \	“14d” \
timezone	string ≤ 80 chars	No	Default: "UTC".
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Niche

niche_now

What’s working in my niche. Posts proven this week in the account’s circle and niche, plus bookmarks, likes and library outliers. Use as inspiration for shape and subject; never copy claims.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: niche.now · REST and CLI

Field	Type	Required	Description
kind	“all” \	“proven” \	“bookmarks” \
topic	string ≤ 200 chars	No	Narrow to posts about this, in the user’s words.
limit	integer 1–15	No	Default: 10.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Engage

who_to_engage

Who to engage now. People worth replying to right now and why: unanswered mentions, the account’s reply circle, and warm Signals leads. Write the replies yourself in the user’s voice (get_me), then post with schedule_post or publish_now using replyTo only if the user asks.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: engage.who_to_engage · REST and CLI

Field	Type	Required	Description
limit	integer 1–30	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

People

get_person

Look up a person. Everything about one X account: profile, recent posts, and the history with the user (replies, DMs, notes, lead status). Uses live X data when it isn’t stored.

• Scope: read · Plan: Every plan, including the trial
• Cost: Live X lookup: no credits, counts toward the plan’s X data limits.
• Same action: people.get · REST and CLI

Field	Type	Required	Description
username	string ≤ 16 chars	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Posts

get_post

Look up a post. Any X post by id or URL with its numbers and context.

• Scope: read · Plan: Every plan, including the trial
• Cost: Live X lookup: no credits, counts toward the plan’s X data limits.
• Same action: posts.get · REST and CLI

Field	Type	Required	Description
tweetId	string	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

schedule_post

Schedule a post. Schedule a post or thread on X at a time. Supports media and automations. Call it only when the user asked for this in the conversation; never on your own initiative. It spends a post credit when it goes live.

• Scope: publish · Plan: Every plan, including the trial
• Cost: Spends a post credit when the post goes live.
• Same action: posts.schedule · REST and CLI

Field	Type	Required	Description
text	string ≤ 25000 chars	Yes
threadParts	array of string ≤ 25000 chars (min 2, max 25)	No	For a thread: every part in order, starting with the same first post as text.
scheduledAt	string ≤ 40 chars	Yes	When to post: the user’s local date and time such as 2026-10-25T10:00 (then pass timezone), or an ISO time with offset.
timezone	string ≤ 80 chars	Yes	IANA timezone such as America/New_York. Use the user’s timezone.
media	array of object (max 4)	No	Media from upload_media, by mediaId. Up to 4 images, or 1 GIF or video.
automation	object	No	Post automations (auto-repost, auto-plug reply, auto-delete, auto-DM). Shape as in the docs: docs.xholic.ai/api/automations.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

publish_now

Post now. Post to X immediately. Requires idempotencyKey so a retry can never post twice. Call it only when the user asked for this in the conversation; never on your own initiative. Spends a post credit.

• Scope: publish · Plan: Every plan, including the trial
• Cost: Spends a post credit when the post goes live.
• Same action: posts.publish_now · REST and CLI

Field	Type	Required	Description
text	string ≤ 25000 chars	Yes
threadParts	array of string ≤ 25000 chars (min 2, max 25)	No	For a thread: every part in order, starting with the same first post as text.
media	array of object (max 4)	No	Media from upload_media, by mediaId. Up to 4 images, or 1 GIF or video.
automation	object	No	Post automations (auto-repost, auto-plug reply, auto-delete, auto-DM). Shape as in the docs: docs.xholic.ai/api/automations.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

X search

search_x

Search X. Live X search, one page of up to 20 posts. A sample, not every match.

• Scope: read · Plan: Every plan, including the trial
• Cost: Live X lookup: no credits, counts toward the plan’s X data limits.
• Same action: x.search · REST and CLI

Field	Type	Required	Description
query	string ≤ 500 chars	Yes
sort	“Latest” \	“Top”	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Inspiration

search_inspiration

Search the inspiration library. Search Xholic’s library of proven posts by idea, with outlier scores (how far a post beat its author’s normal).

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: inspiration.search · REST and CLI

Field	Type	Required	Description
query	string ≤ 200 chars	Yes
timeRange	“week” \	“month” \	“3months” \
limit	integer 1–10	No	Default: 8.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Library

get_saved_posts

Saved posts. The account’s X bookmarks and likes mirrored by Xholic, plus saved posts. Bookmarks show taste.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: library.saved · REST and CLI

Field	Type	Required	Description
query	string ≤ 120 chars	No	Words to look for in the saved posts; omit for the newest.
kind	“bookmarks” \	“likes” \	“all”
questionsOnly	boolean	No	Only posts that ask a question. Default: false.
limit	integer 1–20	No	Default: 10.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Drafts

check_draft

Check a draft. Free checks before posting: length for the account’s X tier, links (Xholic drafts never contain links), near-copies of a source post, repeats of what the account posted recently, and thread structure. Run it on every draft you write; fix what it flags.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: drafts.check · REST and CLI

Field	Type	Required	Description
text	string ≤ 25000 chars	Yes
threadParts	array of string ≤ 25000 chars (min 2, max 25)	No	For a thread: every part in order, starting with the same first post as text.
sourceText	string ≤ 25000 chars	No	The post you built from, to catch near-copies.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

save_draft

Save a draft. Save a post or thread as a draft in Xholic. Nothing is posted. A draft is not a post: never tell the user it was posted.

• Scope: write · Plan: Every plan, including the trial
• Cost: Free.
• Same action: drafts.save · REST and CLI

Field	Type	Required	Description
text	string ≤ 25000 chars	Yes
threadParts	array of string ≤ 25000 chars (min 2, max 25)	No
timezone	string ≤ 80 chars	No	Default: "UTC".
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

draft_with_xholic

Write with Xholic’s writer. Only when the user explicitly asks for Xholic’s writer. Runs Xholic’s data-first Worker writer: every post starts from a real post that worked, one subject per post. Uses Xholic AI credits: quote first and pass confirmCredits after the user agrees. Returns a task; read drafts with ask.task. Otherwise write posts yourself with get_writing_kit.

• Scope: write · Plan: Every plan, including the trial
• Cost: Xholic AI: up to about 25 credits (Xholic’s writer through Ask, charged for what it uses up to this amount). Returns a quote first; pass confirmCredits after the user agrees.
• Same action: drafts.with_xholic · REST and CLI

Field	Type	Required	Description
count	integer 1–12	No
angles	array of string ≤ 500 chars (max 12)	No
sourcePostIds	array of string ≤ 40 chars (max 12)	No
likePostId	string ≤ 40 chars	No	Keep this post’s shape (“like this post”).
topic	string ≤ 300 chars	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.
confirmCredits	number 0–100000	No	Xholic AI credits the user agreed to spend. Call first without it to get the quote, show the quote to the user, and pass the amount only after they say yes.
quoteId	string ≤ 100 chars	No	The quoteId from the quote the user agreed to. Send it with confirmCredits.

Queue

get_queue

Queue and drafts. Scheduled posts and drafts, soonest first.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: queue.list · REST and CLI

Field	Type	Required	Description
view	“all” \	“queued” \	“drafts” \
limit	integer 1–20	No	Default: 10.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

reschedule_post

Reschedule a post. Move a queued post to a new time. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: publish · Plan: Every plan, including the trial
• Cost: Free.
• Same action: queue.reschedule · REST and CLI

Field	Type	Required	Description
postId	string (uuid)	Yes
scheduledAt	string	Yes	The local date and time in timezone, such as 2026-10-25T10:00. Write the time the user means; do not convert it to UTC or add an offset.
timezone	string ≤ 80 chars	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

unschedule_post

Unschedule a post. Take a scheduled post out of the queue and keep it as a draft.

• Scope: write · Plan: Every plan, including the trial
• Cost: Free.
• Same action: queue.unschedule · REST and CLI

Field	Type	Required	Description
postId	string ≤ 120 chars	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

edit_queued_post

Edit a queued post. Change the text, thread, media or automations of a draft or scheduled post.

• Scope: publish · Plan: Every plan, including the trial
• Cost: Free.
• Same action: queue.edit · REST and CLI

Field	Type	Required	Description
postId	string ≤ 120 chars	Yes
text	string ≤ 25000 chars	Yes
threadParts	array of string ≤ 25000 chars (min 2, max 25)	No	For a thread: every part in order, starting with the same first post as text.
media	array of object (max 4)	No	Media from upload_media, by mediaId. Up to 4 images, or 1 GIF or video.
automation	object	No	Post automations (auto-repost, auto-plug reply, auto-delete, auto-DM). Shape as in the docs: docs.xholic.ai/api/automations.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

delete_queued_post

Delete a draft or scheduled post. Delete a draft or scheduled post from Xholic. It does not delete anything already on X. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Every plan, including the trial
• Cost: Free.
• Same action: queue.delete · REST and CLI

Field	Type	Required	Description
postId	string ≤ 120 chars	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Media

upload_media

Upload media. Start a media upload (image, GIF or video). Returns a mediaId and an upload URL; PUT the file bytes there, then call media.complete_upload. Video works too.

• Scope: write · Plan: Every plan, including the trial
• Cost: Free.
• Same action: media.create_upload · REST and CLI

Field	Type	Required	Description
originalFilename	string ≤ 255 chars	Yes
mimeType	string ≤ 100 chars	Yes
byteSize	integer ≤ 536870912	Yes
kind	“IMAGE” \	“VIDEO”	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Analytics

get_analytics

Analytics. Totals and a daily series for a period: impressions, engagement, followers, posts and replies counted separately.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: analytics.summary · REST and CLI

Field	Type	Required	Description
range	“today” \	“7d” \	“14d” \
timezone	string ≤ 80 chars	No	Default: "UTC".
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

how_did_it_do

How posts did. How the account’s posts performed, compared with its normal. Search for one post or sort a period.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: analytics.content · REST and CLI

Field	Type	Required	Description
range	“today” \	“7d” \	“14d” \
timezone	string ≤ 80 chars	No	Default: "UTC".
search	string ≤ 100 chars	No	Default: "".
sort	“publishedAt” \	“impressions” \	“engagements” \
limit	integer 1–20	No	Default: 10.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Memory

remember

Remember. Save a fact, writing preference or answer about the user to the memory every Xholic writer reads. Only things the user told you or confirmed.

• Scope: write · Plan: Every plan, including the trial
• Cost: Free.
• Same action: memory.remember · REST and CLI

Field	Type	Required	Description
fact	string ≤ 300 chars	Yes
kind	“WRITING” \	“FACT” \	“ANSWER”
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

forget

Forget. Remove a memory the user says is wrong or outdated.

• Scope: write · Plan: Every plan, including the trial
• Cost: Free.
• Same action: memory.forget · REST and CLI

Field	Type	Required	Description
memoryId	string (uuid)	Yes
fact	string ≤ 300 chars	No	The memory’s text, shown on the approval card.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Workers

get_workers

Workers. The account’s Workers (always-on AI writers): settings, schedule and status.

• Scope: read · Plan: Pro plan or higher
• Cost: Free.
• Same action: workers.list · REST and CLI

Field	Type	Required	Description
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

get_worker_drafts

Worker drafts. Drafts a Worker wrote that are waiting for review.

• Scope: read · Plan: Pro plan or higher
• Cost: Free.
• Same action: workers.drafts · REST and CLI

Field	Type	Required	Description
neuronId	string (uuid)	No
limit	integer 1–30	No	Default: 12.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

create_worker

Create a Worker. Create a Worker that writes posts on a schedule or on demand. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: workers.create · REST and CLI

Field	Type	Required	Description
name	string ≤ 80 chars	Yes
status	“ACTIVE” \	“PAUSED”	No
voiceMode	“OWN” \	“CREATOR” \	“HYBRID”
creatorXIds	array of string ≤ 120 chars (max 3)	No	Creator xid values from findWorkerCreators: one for HYBRID unless the user asks for more (up to three), one to three for CREATOR, none for OWN. Default: [].
instructions	string ≤ 2000 chars or null	No	The worker’s brief, broad boundaries only: who it writes for, who speaks, how the account likes to write, the areas it usually writes in, when to mention products and hard bans. Never a thesis, a point of view to push or specific topics to cover.
applyAccountRules	boolean	No	Follow the account’s saved writing rules. Default: true.
mirrorProvenPosts	boolean	No	Shape posts on formats that already work in the niche. Default: true.
topicMode	“FOR_YOU” \	“PRODUCT” \	“CUSTOM_TOPIC” \
customTopic	string ≤ 500 chars or null	No	CUSTOM_TOPIC: what to post about. NICHE_TRENDING: one to five comma-separated keywords.
productIds	array of string ≤ 120 chars (max 5)	No	PRODUCT only: saved product IDs from getAutomationSetup or getAccountContext. Default: [].
outputCount	8 or 12 or 24	Yes	Posts written per run: 8, 12 or 24.
scheduleMode	“ON_DEMAND” \	“DAILY” \	“WEEKLY”
scheduleTimeMinutes	integer 0–1439 or null	No	DAILY or WEEKLY: minutes after midnight in the account’s timezone, e.g. 540 for 9:00.
scheduleDayOfWeek	integer 0–6 or null	No	WEEKLY: 0 is Sunday, 6 is Saturday.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

update_worker

Edit a Worker. Change a Worker’s instructions, voice, topics, products, size or schedule. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: workers.update · REST and CLI

Field	Type	Required	Description
workerId	string (uuid)	Yes
changes	object	Yes
changes.name	string ≤ 80 chars	No
changes.status	“ACTIVE” \	“PAUSED”	No
changes.voiceMode	“OWN” \	“CREATOR” \	“HYBRID”
changes.creatorXIds	array of string ≤ 120 chars (max 3)	No	Creator xid values from findWorkerCreators: one for HYBRID unless the user asks for more (up to three), one to three for CREATOR, none for OWN.
changes.instructions	string ≤ 2000 chars or null	No	The worker’s brief, broad boundaries only: who it writes for, who speaks, how the account likes to write, the areas it usually writes in, when to mention products and hard bans. Never a thesis, a point of view to push or specific topics to cover.
changes.applyAccountRules	boolean	No	Follow the account’s saved writing rules.
changes.mirrorProvenPosts	boolean	No	Shape posts on formats that already work in the niche.
changes.topicMode	“FOR_YOU” \	“PRODUCT” \	“CUSTOM_TOPIC” \
changes.customTopic	string ≤ 500 chars or null	No	CUSTOM_TOPIC: what to post about. NICHE_TRENDING: one to five comma-separated keywords.
changes.productIds	array of string ≤ 120 chars (max 5)	No	PRODUCT only: saved product IDs from getAutomationSetup or getAccountContext.
changes.outputCount	8 or 12 or 24	No	Posts written per run: 8, 12 or 24.
changes.scheduleMode	“ON_DEMAND” \	“DAILY” \	“WEEKLY”
changes.scheduleTimeMinutes	integer 0–1439 or null	No	DAILY or WEEKLY: minutes after midnight in the account’s timezone, e.g. 540 for 9:00.
changes.scheduleDayOfWeek	integer 0–6 or null	No	WEEKLY: 0 is Sunday, 6 is Saturday.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

pause_or_resume_worker

Pause or resume a Worker. Pause or resume a Worker.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: workers.set_status · REST and CLI

Field	Type	Required	Description
workerId	string (uuid)	Yes
status	“ACTIVE” \	“PAUSED”	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

run_worker

Run a Worker now. Queue a Worker to write a new batch now with Xholic’s writer. Spends Xholic AI credits per post: quote first, show it to the user, and pass confirmCredits after they agree. Returns right away; drafts arrive in get_worker_drafts.

• Scope: write · Plan: Pro plan or higher
• Cost: Xholic AI: up to about 120 credits (Xholic’s Worker writer, charged per post in the batch). Returns a quote first; pass confirmCredits after the user agrees.
• Same action: workers.run · REST and CLI

Field	Type	Required	Description
neuronId	string (uuid)	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.
confirmCredits	number 0–100000	No	Xholic AI credits the user agreed to spend. Call first without it to get the quote, show the quote to the user, and pass the amount only after they say yes.
quoteId	string ≤ 100 chars	No	The quoteId from the quote the user agreed to. Send it with confirmCredits.

review_worker_draft

Review a Worker draft. Move a Worker draft: DRAFT keeps it in the user’s drafts, DISMISSED throws it away, TO_REVIEW puts it back in review. When dismissing because it isn’t the user’s opinion, pass reason NOT_MY_OPINION so Workers learn. To post or schedule it, use schedule_post with its text. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: workers.review_draft · REST and CLI

Field	Type	Required	Description
id	string ≤ 160 chars	Yes	Worker draft id from get_worker_drafts.
status	“TO_REVIEW” \	“DRAFT” \	“DISMISSED”
reason	“NOT_MY_OPINION”	No	Only with DISMISSED: why, when it teaches the Workers something.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Leads

get_leads

Leads. Leads found by the account’s Signals agents, hottest first, with why each one fits.

• Scope: read · Plan: Pro plan or higher
• Cost: Free.
• Same action: leads.list · REST and CLI

Field	Type	Required	Description
agentId	string (uuid)	No
status	“ALL” \	“COLLECTED” \	“CONTACTED” \
limit	integer 1–20	No	Default: 10.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

set_lead_status

Mark a lead. Mark a lead COLLECTED (keep), CONTACTED (reached out) or DISMISSED (not now). Pass suppress true with DISMISSED to never surface this person again. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: leads.set_status · REST and CLI

Field	Type	Required	Description
id	string (uuid)	Yes	Lead id from get_leads.
status	“COLLECTED” \	“CONTACTED” \	“DISMISSED”
suppress	boolean	No	Never show this person as a lead again.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

rate_lead

Rate a lead. Mark a lead as a FIT or NOT_FIT, with an optional short reason, so the Signals agent learns who to find. Pass verdict null to clear the rating. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: leads.rate · REST and CLI

Field	Type	Required	Description
id	string (uuid)	Yes	Lead id from get_leads.
verdict	“FIT” \	“NOT_FIT” or null	Yes
reason	string ≤ 200 chars or null	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Signals

create_signal_agent

Create a Signals agent. Create an always-on agent that finds leads on X from sources and an audience description. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: signals.create_agent · REST and CLI

Field	Type	Required	Description
name	string ≤ 80 chars	Yes
productId	string ≤ 160 chars or null	No
audienceDescription	string ≤ 3000 chars	Yes
exclusions	string ≤ 1500 chars or null	No
rubric	object or null	No
rubric.who	string ≤ 600 chars	Yes
rubric.needs	array of string ≤ 200 chars (max 8)	No	Default: [].
rubric.disqualifiers	array of string ≤ 200 chars (max 8)	No	Default: [].
rubric.exampleMatch	string ≤ 600 chars or null	No	Default: null.
rubric.exampleNonMatch	string ≤ 600 chars or null	No	Default: null.
strictness	“HIGH_PRECISION” \	“DISCOVERY”	No
dmPolicy	“ANYONE” \	“OPEN_DMS_ONLY”	No
destinationListId	string (uuid)	No
baselineMode	“FUTURE_ONLY” \	“RECENT”	No
intervalHours	integer 4–24	No	Default: 6.
status	“ACTIVE” \	“PAUSED”	No
sources	array of object (min 1, max 15)	Yes
newListName	string ≤ 80 chars	No	A name for a new contact list to save leads to.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

find_customers

Find customers for a product. One-click agent that finds people asking for what a product does, and its competitors’ customers. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: signals.find_customers · REST and CLI

Field	Type	Required	Description
productId	string ≤ 160 chars	Yes
replaceAgentId	string ≤ 160 chars	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

run_signal_agent

Run a Signals agent now. Queue a Signals agent to search for leads now instead of waiting for its schedule. Leads it scores count toward the month’s Signals quota, and each agent has a few manual runs per 24 hours. Returns right away; new leads arrive in get_leads. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: signals.run_agent · REST and CLI

Field	Type	Required	Description
id	string (uuid)	Yes	Signals agent id.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Contacts

get_contacts

Contacts. Contacts and lists: search, filter by score or intent.

• Scope: read · Plan: Pro plan or higher
• Cost: Free.
• Same action: contacts.list · REST and CLI

Field	Type	Required	Description
listId	string (uuid)	No
search	string ≤ 80 chars	No
minimumScore	integer 1–3	No
intent	“HOT” \	“WARM” \	“COLD”
limit	integer 1–30	No	Default: 15.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

add_to_contact_list

Add someone to a contact list. Add an X account to a contact list by handle. Looks the profile up on X when Xholic doesn’t have it yet. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Live X lookup: no credits, counts toward the plan’s X data limits.
• Same action: contacts.add_to_list · REST and CLI

Field	Type	Required	Description
listId	string (uuid)	Yes	Contact list id from get_contact_lists.
handle	string ≤ 120 chars	Yes	X handle like @name, or a link to their profile.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Ask Xholic

ask_xholic

Hand a job to Xholic. Hand a long job to Xholic’s own agent, e.g. ‘find 30 leads, research each and draft DMs’. Uses Xholic AI credits: quote first, show it to the user, pass confirmCredits after they agree. Returns a task id; read progress with ask.task.

• Scope: write · Plan: Every plan, including the trial
• Cost: Xholic AI: up to about 25 credits (Ask Xholic, charged for what the job uses up to this amount). Returns a quote first; pass confirmCredits after the user agrees.
• Same action: ask.start · REST and CLI

Field	Type	Required	Description
task	string ≤ 8000 chars	Yes	The job, in the user’s words.
model	“luna” \	“sol” \	“sonnet” \
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.
confirmCredits	number 0–100000	No	Xholic AI credits the user agreed to spend. Call first without it to get the quote, show the quote to the user, and pass the amount only after they say yes.
quoteId	string ≤ 100 chars	No	The quoteId from the quote the user agreed to. Send it with confirmCredits.

Action catalog

find_actions

Find an action. Search everything Xholic can do (about 150 actions) and the docs. Use it when no loaded tool fits; then call run_read_action or run_write_action with the action id.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: actions.find · REST and CLI

Field	Type	Required	Description
query	string ≤ 200 chars	Yes
limit	integer 1–25	No

Docs

read_doc

Read a docs page. Read a page of the Xholic docs by path, e.g. /api/authentication.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: docs.read · REST and CLI

Field	Type	Required	Description
path	string ≤ 200 chars	Yes

Scheduler

best_posting_times

Best times to post. The best upcoming times for this account to post, from when its audience engages. Use before scheduling when the user wants a good time rather than a set one.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: scheduler.best_times · REST and CLI

Field	Type	Required	Description
timezone	string ≤ 100 chars	No	IANA timezone such as America/New_York. Use the user’s timezone.
slotCount	integer 1–140	No	How many times to return (default 12).
windowStartMinutes	integer 0–1439	No	Only times after this, in minutes after local midnight. Send with windowEndMinutes.
windowEndMinutes	integer 0–1439	No	Only times before this, in minutes after local midnight. Send with windowStartMinutes.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Tags

list_tags

List tags. The account’s post tags (name, color, id). Use the ids to filter the queue or calendar, or to tag a post.

• Scope: read · Plan: Every plan, including the trial
• Cost: Free.
• Same action: tags.list · REST and CLI

Field	Type	Required	Description
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Articles

create_article

Create an article. Start a new X Article draft with a title. Then write its body yourself and save it with update_article. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: articles.create · REST and CLI

Field	Type	Required	Description
title	string ≤ 200 chars	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

update_article

Edit an article. Save an article’s title, subtitle or body. Pass the current version from articles.get; it returns the new version. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: articles.update · REST and CLI

Field	Type	Required	Description
id	string (uuid)	Yes	Article id from articles.list.
title	string ≤ 200 chars	No
subtitle	string ≤ 280 chars or null	No
document	object	No	The whole body as a Tiptap/ProseMirror JSON document: {type:“doc”,content:[paragraph, heading, bulletList, image… nodes]}. See docs.xholic.ai/api/articles.
document.type	“doc”	Yes
version	integer 1–9007199254740991	Yes	The article’s current version, from articles.get. A stale version is refused so edits never overwrite each other.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

schedule_article

Schedule an article. Schedule an article to publish on X at a time. Pass the current version from articles.get. Call it only when the user asked for this in the conversation; never on your own initiative. Spends a post credit when it goes live.

• Scope: publish · Plan: Pro plan or higher
• Cost: Spends a post credit when the post goes live.
• Same action: articles.schedule · REST and CLI

Field	Type	Required	Description
id	string (uuid)	Yes	Article id from articles.list.
scheduledAt	string ≤ 40 chars	Yes	When to publish, as an ISO time with offset such as 2026-10-25T10:00:00-04:00.
timezone	string ≤ 100 chars	Yes	IANA timezone such as America/New_York. Use the user’s timezone.
version	integer 1–9007199254740991	Yes	The article’s current version, from articles.get. A stale version is refused so edits never overwrite each other.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

publish_article

Publish an article now. Publish an article to X now. Pass the current version from articles.get. Call it only when the user asked for this in the conversation; never on your own initiative. Spends a post credit.

• Scope: publish · Plan: Pro plan or higher
• Cost: Spends a post credit when the post goes live.
• Same action: articles.publish · REST and CLI

Field	Type	Required	Description
id	string (uuid)	Yes	Article id from articles.list.
version	integer 1–9007199254740991	Yes	The article’s current version, from articles.get. A stale version is refused so edits never overwrite each other.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

Contact lists

get_contact_lists

Contact lists. The account’s contact lists with member counts, including which one is the close-accounts list. Use a list’s id with the other contact tools.

• Scope: read · Plan: Pro plan or higher
• Cost: Free.
• Same action: contact_lists.list · REST and CLI

Field	Type	Required	Description
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

Direct messages

send_dms

Send DMs now. Send one message to up to 500 people found with dm.preview_recipients, paced safely from the user’s X account. Write the message yourself; variables like [first] personalise it. Only pass confirmedConsent true after the user confirmed these people agreed to or expect the message. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: publish · Plan: Pro plan or higher
• Cost: Free.
• Same action: dm.quick_send · REST and CLI

Field	Type	Required	Description
name	string ≤ 80 chars or null	No
messageTemplate	string ≤ 5000 chars	Yes	The message. Variables: [first], [name], [handle], [location], [followers], list fields such as [first_line], with optional fallbacks like [first|there]; spintax like {Hi|Hey}. Write it yourself in the user’s voice.
confirmedConsent	true	Yes
recipients	array of object (min 1, max 500)	Yes	Recipients exactly as dm.preview_recipients returned them.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

create_dm_campaign

Create a DM campaign. Create a draft DM campaign for a contact list. Then write its steps with dm.update_campaign, check it with dm.review_campaign and launch it with launch_dm_campaign. Write the messages and any per-person first lines with your own model: import the lines as a CSV column (dm.import_csv, e.g. first_line) and use [first_line]. The [ai_line] variable makes Xholic’s AI write a line per recipient at launch and spends AI credits; use it only when the user asks for Xholic to write them. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: write · Plan: Pro plan or higher
• Cost: Free.
• Same action: dm.create_campaign · REST and CLI

Field	Type	Required	Description
name	string ≤ 80 chars	No
contactListId	string (uuid) or null	No	Contact list to message.
deliveryMode	“AUTOMATIC” \	“ASSISTED”	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.

launch_dm_campaign

Launch a DM campaign. Launch a reviewed campaign: its messages start sending on its schedule. Run dm.review_campaign first, show the user the outreach guidelines, and pass confirmedConsent true only after they accept. If a template uses [ai_line], launching reserves AI credits for each recipient and needs confirmCredits. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: publish · Plan: Pro plan or higher
• Cost: Xholic AI: up to about 0 credits (Xholic AI first lines ([ai_line]) for each eligible recipient; nothing when no template uses them). Returns a quote first; pass confirmCredits after the user agrees.
• Same action: dm.launch_campaign · REST and CLI

Field	Type	Required	Description
id	string (uuid)	Yes	DM campaign id.
confirmedConsent	boolean	Yes	The user accepted the cold-outreach guidelines shown by dm.review_campaign.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.
confirmCredits	number 0–100000	No	Xholic AI credits the user agreed to spend. Call first without it to get the quote, show the quote to the user, and pass the amount only after they say yes.
quoteId	string ≤ 100 chars	No	The quoteId from the quote the user agreed to. Send it with confirmCredits.

get_dm_campaign_stats

DM campaign results. How a campaign is doing: sent, replied, interested and booked, by step and A/B variant.

• Scope: read · Plan: Pro plan or higher
• Cost: Free.
• Same action: dm.campaign_stats · REST and CLI

Field	Type	Required	Description
id	string (uuid)	Yes	DM campaign id.
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

get_dm_inbox

DM inbox. DM conversations with replies, newest first, with each person’s lead status. Filter by lead status, campaign or unread.

• Scope: read · Plan: Pro plan or higher
• Cost: Free.
• Same action: dm.inbox · REST and CLI

Field	Type	Required	Description
leadStatus	“NEW” \	“REPLIED” \	“INTERESTED” \
campaignId	string (uuid)	No
unread	“true” \	“false”	No
limit	integer 1–50	No
offset	integer 0–9007199254740991	No
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.

reply_to_dm

Reply to a DM. Send a DM reply in a conversation from the user’s X account. Write the reply yourself from the thread (dm.thread) in the user’s voice. Call it only when the user asked for this in the conversation; never on your own initiative.

• Scope: publish · Plan: Pro plan or higher
• Cost: Free.
• Same action: dm.reply · REST and CLI

Field	Type	Required	Description
creatorId	string	Yes	The person’s numeric X user id.
text	string ≤ 5000 chars	Yes
account	string ≤ 64 chars	No	X account to act on, as @handle. Leave it out to use the connection’s default account.
dryRun	boolean	No	Return exactly what would happen without doing it.
idempotencyKey	string ≤ 200 chars	No	A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice.