---
name: sprkly
description: Schedule social posts, check what worked, and manage a posting queue through sprkly. Use when the user wants to post or schedule to Instagram, TikTok, YouTube, Threads or Facebook, asks what to post or when, or asks how their posts performed.
---

# Posting with sprkly

sprkly schedules posts to Instagram, TikTok, YouTube, Threads and Facebook.

You reach it through the sprkly connector. If the user has not added it yet, point them at
**Settings, then Connectors, then Add custom connector**, and give them
`https://sprkly.app/api/mcp`. It is included in the free trial, so they do not need to pay
to try this.

## Start here

There are five ready-made workflows. Suggest one by name when it fits:

| They say | Use |
|---|---|
| "post this" / "put this up tomorrow" | `post_this` |
| "plan my week" / "here are 10 photos" | `plan_week` |
| "how did I do" / "what worked" | `how_did_i_do` |
| "what's scheduled" / "did that go out" | `check_my_queue` |
| "write more like that one" | `more_like_this` |

If none fit, use the tools directly. The rules below apply either way.

## Scheduling

**Be fast.** The point of this connector is that posting takes one exchange, not a
conversation. Every extra tool call is an approval click; every extra question is a reply the
user has to type. A post needs four things: **what, where, when, how many.** Everything else
has a sane default. If you have the four, go.

**Go straight to `sprkly_schedule_post`.** Do not call other tools to prepare for it. It runs
every platform check itself and returns the same errors a separate check would: caption
limits, missing media, missing titles.

Calling `sprkly_list_profiles` and `sprkly_validate_post_policy` first feels thorough. It is
not. Each costs a click, and neither tells you anything the schedule call will not.

**Do not read the plan back for approval before scheduling.** The user can see what they
asked for, and a scheduled post can be edited or deleted. Schedule it, then say what went
where and when, in one line. Ask before *deleting* something.

Times are ISO 8601 and the user is not thinking in UTC. Work out what they meant in their own
timezone. Only ask when it is genuinely ambiguous.

### When there is more than one account

If the user has two Instagram accounts, `sprkly_schedule_post` does not post. It returns
`needsAccountChoice` with the list.

Ask the user which ones they mean. Never pick for them. Then call again with `profile_ids`
set to every account they chose. `profile_ids` on its own is a complete call and replaces
`platforms` entirely.

### Media: just pass the link

**Put the link straight into `media_urls` on `sprkly_schedule_post`. That is all.**

sprkly pulls it into its own storage whenever the target platform needs that, which TikTok,
YouTube and Facebook always do. Instagram and Threads fetch links themselves, so those stay
as links and cost nothing.

- **Google Drive and Dropbox share links work.** sprkly converts them to the direct-download
  form for you. The file does have to be shared publicly, or Drive serves a sign-in page and
  sprkly says so.
- Limit is 50 MB. Bigger files go through the sprkly composer.
- For a carousel, pass the whole ordered list. Order is what you send.
- `sprkly_add_media_from_url` still exists, and you rarely need it. Reach for it only when
  the user wants a reusable `media_id` to put on several posts.

⚠️ This is the one thing that used to fail badly. A plain link to TikTok scheduled fine, then
failed in a cron job days later. It does not any more, and you do not have to work around it.

### Per platform

- **TikTok** needs a title and a privacy level. Just send one. `sprkly_schedule_post` checks
  it against what that creator is really allowed and, if it is wrong, comes back naming the
  levels that would work. You do **not** need `sprkly_get_tiktok_posting_options` first.
  "Only I can see it" is `SELF_ONLY`. Public is `PUBLIC_TO_EVERYONE`.
- **YouTube** needs a title, 100 characters or fewer.
- **TikTok and YouTube keep their text in the title, not the caption.** A caption-only post
  to those platforms publishes with nothing written on it.
- **Instagram and TikTok both require media.** Text-only fails.

Write a caption per platform. One caption pasted everywhere reads like one caption pasted
everywhere.

### Shapes worth knowing

- Instagram crops **every** carousel slide to the first slide's shape. Lead with the shape
  you want.
- Threads and Facebook publish only the **first** image and drop the rest silently.
- TikTok photo sets must all be the same pixel size.
- Facebook Reels must be 9:16, or the post publishes dead.
- YouTube has no image posting at all.

## Analytics

For "what should I post" or "when should I post", call `sprkly_get_analytics` **first** and
reason from what it returns. It gives evidence, not advice: totals, change against the
previous period, best hour and weekday, and the posts behind them.

Two rules, and they matter more than the numbers.

**Check `samples` before you call anything a pattern.** A best hour backed by one post is
not a finding. Saying "you have posted three times, that is not enough to see a pattern
yet" is more useful than a confident guess, and the user can act on it.

**Check `coverage` before you compare platforms.** Instagram reports likes and comments
only. Threads and Facebook report nothing at all. Posts published outside sprkly are
invisible. A platform with no data is not a platform doing badly, and presenting it as one
sends the user chasing a problem that is not there.

When you name what worked, be specific. "Engaging content" is not an observation. "The two
that did best both open with a question and have one idea" is.

## Things not to do

- **Do not re-schedule or re-send a post that failed.** Tell the user what failed and why,
  in plain words, and let them decide. Publishing is public and cannot be undone, and they
  may already have posted it by hand.
- **Do not schedule without showing the user first.** Draft, show, then schedule.
- **Do not read ids out.** Talk about accounts by handle and posts by their caption. Post
  ids, profile ids and media ids are plumbing.
- **Do not invent limits.** If you are unsure whether something is allowed, schedule it and
  read the error, or use `sprkly_validate_post_policy` on a draft you are not scheduling.

## When something is refused

- `needsAccountChoice` is not an error. Ask the user, then call again.
- `403 plan_required` means the trial ended without a plan. They can start one at
  sprkly.app/checkout.
- A validation error names what is wrong. Fix it and call again. Do not work around it by
  dropping the platform without telling the user.

## The whole tool list

Writing: `sprkly_schedule_post`, `sprkly_update_scheduled_post`,
`sprkly_delete_scheduled_post`, `sprkly_draft_post`, `sprkly_add_media_from_url`,
`sprkly_request_post_approval`

Reading: `sprkly_list_profiles`, `sprkly_list_connected_social_accounts`,
`sprkly_list_scheduled_posts`, `sprkly_get_post_status`, `sprkly_get_post_approval_status`,
`sprkly_get_analytics`, `sprkly_get_tiktok_posting_options`, `sprkly_get_account_summary`,
`sprkly_get_billing_summary`, `sprkly_validate_post_policy`