Cheerful

Use this when the user asks what influencer campaigns they have, a campaign's settings, or which mailboxes a campaign sends from. Read-only. To create a campaign or launch a draft, use create_campaign_draft and preview_campaign_launch when those tools are available. Pausing, deleting or editing a LIVE campaign is done in the Cheerful app: say so without asking which campaign first. Campaigns the user can see: their own plus every campaign their teams share. action='index' (default) lists them — pass `include_stats=true` for sent/reply counts. action='get' with `campaign_id` returns one campaign's full settings. action='senders' with `campaign_id` returns the mailboxes that may send THIS campaign. Senders belong to the campaign, not to the viewer: NEVER name or assume a sending mailbox you did not get from action='senders'. A mailbox the user can read is not necessarily one they may send from. `team_id` and `owner_email` on a campaign tell you it is a teammate's. A 404 here means 'not found OR not yours' — the two are deliberately indistinguishable, so list the index instead of guessing ids.

campaign_read

The user's saved creator lists — their own plus any their teams share. action='index' (default) returns every list; action='get' with `list_id` returns one list's creators (handle, name, followers, email if known, short bio), `limit` per page (default 100, max 500). When `has_more` is true, call again with `offset` = `next_offset`; `creators_total` is the list's full size. A list carrying `owner_email` belongs to a teammate: readable and usable, but treat it as theirs when you talk about it.

list_read

Use this when the user asks who replied, who opted in or said yes, who declined, who needs an answer, or what came back from their creator outreach. Read-only: it cannot send, reply to or draft email for sending; replying happens in the Cheerful app. Email threads across every mailbox the user can read — their own plus mailboxes their teams granted them. action='threads' (default) pages threads, newest first, each with its `campaign_name`, `gifting_status` and the latest message's `snippet`. action='search' finds threads by creator name, email or subject, in every state including finished ones. action='counts' returns inbox tab totals: `pending` = creator replies waiting on the user, `outbox` = threads where the user wrote last, `ignored`. For opt-in and decline totals use campaign_report. PAGING: pass the `next_cursor` from the previous result back as `cursor`. Do NOT page by offset — once a cursor is in play the server ignores offset and you will re-read the same page forever. Every thread names the `account_id` it arrived on, because the user may be reading someone else's mailbox. A thread on a read-only grant cannot be replied to or hidden by this user — check `account_read` before proposing an action on it.

inbox_read

Save creators to one of the user's own Cheerful creator lists, or to a new list. Free, and safe to repeat: creators already on the list are counted in `already_present_count`, not duplicated. `creators`: rows as returned by creator_search, creator_search_status or creator_profile. Only `handle` (or `username`) is required; `full_name` and `profile_pic_url` are kept if present. Creators with an invalid handle are returned in `skipped`, the rest are saved. `platform` is required: the platform the creators were found on (the one creator_search used). All creators in one call share it; call once per platform. Pass exactly one of `list_id` (from list_read; must be a list where `is_owner` is true; teammates' lists are read-only) or `new_list_name` (re-uses the user's own list with that exact name if one exists). Returns the list id, name, counts and an `open_url` to the list in Cheerful.

save_creators_to_list

Use this when the user wants to find, discover or shortlist influencers or creators for a brand, product or campaign: by niche, topic, location, platform, follower range, or similar to a handle. Find Instagram, TikTok, or YouTube creators. Searches use the caller's account permissions and cost credits. YOUTUBE: set platform='youtube'. keyword/smart start a durable Deep Search; similar uses query as a seed channel handle or URL. This creates a search and saves results to a new list. It runs asynchronously: the initial response is a run ID, NOT discovered creators. It vets every candidate's videos and usually takes 10 to 45 minutes. Do NOT poll in a loop: tell the user it is running in the background, that results land in the list at `open_url`, and check creator_search_status once whenever they ask how it is going. Report any blocked/failed launch and its detail. Report only returned creators and disclose shortfalls. Resume a failed launch with action='resume', query=run_id; never create a duplicate search. Supports limit (1-50), follower bounds and one country in location. YouTube does not support page>1, min_engagement, or exclude_saved. Use list_read for paging the resulting saved list. INSTAGRAM/TIKTOK: action: keyword — filtered search over the indexed catalogue. Use when the brief has hard filters (country, follower band, engagement) or names a country outside the smart-search whitelist below. smart — natural-language brief; a planner turns it into queries and ranks the results. Use for open briefs with no hard filters. similar — creators resembling one handle. `query` is the handle. TRAPS, in the order they cost turns: - action='smart' only binds a location for: United States, United Kingdom, Canada, Australia, Germany, France, Spain, Brazil, India, Mexico, Italy, Netherlands, Japan, South Korea, United Arab Emirates. Any other country is SILENTLY DROPPED and you get global results. For those, use action='keyword' with an explicit `location`. - `location` is full country names, never codes: 'United States' not 'US', 'United Arab Emirates' not 'UAE'. - No apostrophes in `query`: "women's health" 502s. Use 'womens health'. - `query` for keyword search describes the PERSON ('vegan meal prep mom'), not the campaign or the product. READING THE RESULT: report how many creators you actually received. `total` is the provider's pre-filter pool (often tens of thousands) and is not what you got. `filtered_blocked_count` are creators removed because the user already blocked them. DO NOT silently drop results for a floor the user never set — a 1k-follower on-niche creator is a valid hit. Engagement under ~0.5% on 50k+ followers is a bought-audience signature: FLAG it in your reply, do not drop it. SHORTFALL: if you get fewer than asked, relax ONE axis (follower band first, then engagement, then location), re-run, and label the extras as relaxed. Never mix them in silently. Still short after one widen? Stop and tell the user the count and which axis you would relax next. TIMING (measured on prod 2026-10-01): keyword ≈3s, smart ≈55s; YouTube returns a run ID at once and finishes in the background. A slow smart search is normal, not a hang. Costs credits. To keep creators, pass the returned rows to save_creators_to_list.

creator_search

Launches a reviewed campaign draft: emails start going to its creators from the user's mailbox, in the send window, at the mailbox's daily pace. Called ONLY by the launch card's Confirm & send button, with the one-time confirmation it holds; it cannot be called from the conversation.

campaign_send

Use this when the user asks which inbox their outreach sends from, wants to connect or send from their Gmail or work email, or asks whether their email domain is set up to land in the inbox. Read-only: lists the connected mailboxes that can send, checks each sending domain's SPF / DKIM / DMARC, and gives the link to connect a mailbox in Cheerful. Connecting happens on Cheerful's settings page (Google sign-in or SMTP), never in chat: never ask for a password. Statuses: fail = lead with it, it costs replies; warn = worth fixing; not_checkable / error = say you couldn't verify it, never call it a problem. provider_managed (gmail.com, outlook.com) means nothing to configure. Quote `summary` and `fix_hint`; no raw DNS unless asked. Each mailbox paces about 30 new emails a day (rising to ~50 after two weeks), so more mailboxes send a big list faster.

check_sending_mailboxes

Use this when the user wants to see a campaign DRAFT they are setting up: its email, follow-up, product, sender, creators and what is still missing before it can launch. Read-only. Shows it as a card. For launched campaigns use campaign_read and campaign_report.

get_campaign_draft

Use this when the user wants to change a campaign DRAFT: its name, product, subject, email, follow-up, send window, sending mailbox or reply samples. Replaces the fields you pass (the old text is not kept), leaves the rest as they are, and never sends. A launched campaign cannot be edited here: say it is edited in the Cheerful app. Returns the updated draft as a card. COPY RULES (they decide whether it gets delivered): - Plain text, short (well under 150 words), one ask, at most one link. - Exactly ONE merge tag by default: {name} in the greeting. None in the subject. Single braces. {first_name} is the safe alternative when names look like brand titles. No other tags: a tag no creator has data for skips them. - One follow-up, 3 days later, that adds something new. - Optional interested_reply / declined_reply: short samples of how the user answers a yes or a no; they set the tone of reply drafts. SENDING: emails go from the user's own connected mailbox (`sender_email`; never invent one: call check_sending_mailboxes). send_window: 'every_day' (default: 7am-9pm New York time), 'weekdays_business_hours' (9-5, pass `timezone`) or 'all_hours' (only if the user asks). Never say emails send immediately.

update_campaign_draft

Progress and results of a YouTube creator search started by creator_search(platform='youtube'). Read-only: it never starts or re-launches a search and costs nothing. `run_id` is the id returned by creator_search. A run usually takes 10-45 minutes: check once per user request, not in a loop. `status` ends as completed, failed, or cancelled; `current_stage` says what it is doing now. `creators` holds only the creators saved to the run's list so far; `delivered_count` vs `target_count` is the honest progress. A failed or blocked `launch` needs creator_search(action='resume').

creator_search_status