SparkToro

Likely AI-assistant prompts this audience uses — the questions and requests this group asks ChatGPT, Claude, and similar tools. Use this to understand the audience's intent and pain points in their own words — useful for content ideation, ad copy, and product positioning. Different from `get_search_keywords` (terms they look up in traditional search engines).

get_prompts

Check the user's current plan, report quota usage, billing-period dates, and which sections are available vs. locked on their plan. Use this when the user asks "how many reports do I have left", "when does my plan reset", "what can I see on my plan", or before warning them about quota. Also useful before calling `create_report` if you want to confirm headroom — but don't preemptively call it on every request, only when the user is asking about their account. Returns: `{plan, reports_used, reports_available, reports_remaining, billing_period_start, billing_period_end, available_sections, locked_sections}`. `reports_available` may be a very large number on unlimited plans (Agency). `available_sections` and `locked_sections` are arrays of `{name, title}` describing which section tools the current plan can call vs. which require an upgrade.

get_quota

Apps and websites this audience uses, scoped by category. Each call returns one category. Pick the category that matches what the user asked about — do NOT call multiple categories speculatively. **Free-plan restriction:** Free users can only call this tool with `app_type="ai"`. Other categories require a paid plan. Valid `app_type` values: - `ai` — AI tools and assistants (ChatGPT, Claude, Midjourney, etc.) - `productivity` — productivity software (Notion, Asana, Slack, etc.) - `entertainment` — entertainment apps and platforms (streaming, gaming, etc.) - `lifestyle` — lifestyle and wellness apps - `finance` — finance and banking apps - `sports` — sports apps and platforms - `ecommerce` — shopping and e-commerce platforms There is no general "marketing", "social", "cms", or "analytics" category — those are not valid `app_type` values. If the user asks about marketing tools or CMS, the closest match is `productivity`. Social platforms come back from `get_social`, not `get_apps`.

get_apps

Words and phrases that appear most often in this audience's social-media bios — how they describe themselves. Use this for messaging, ad copy, and persona work — the language an audience uses about itself usually beats marketer-written language. Cold-path calls can take up to 2 minutes (calls OpenAI). If a call times out, retry once — the second call hits the cache and returns immediately.

get_bio_keywords

Brands, products, and services this audience is most familiar with and resonant toward — each scored 25-100 for relevance and tagged with a short category (e.g. "Athletic Apparel", "Streaming Service"). Use this for partnership ideation, competitive landscape mapping, sponsorship targeting, and ad-creative inspiration. Depends on `get_websites`, `get_search_keywords`, and `get_demographics` having been computed already; if those aren't ready the tool will return a clear error asking you to call them first.

get_brands

Check whether an audience report is ready to query. Use this to poll after `create_report` returned status "processing": call every 5–10 seconds until status is "ready". Returns one of: - `{status: "processing"}` — audience is still being built; wait and poll again. - `{status: "ready"}` — audience is ready. Tell the user it's built and ask what they want to know — do NOT proactively pull every section. - `{status: "failed", error: <string>}` — audience generation failed; ask the user whether to retry with a different prompt.

get_report_status

Create a new SparkToro audience report from a natural-language description. Each call consumes one report from the user's monthly plan quota (Free: 5/mo, Personal: 50/mo, Business: 500/mo, Agency: unlimited), so do not call this multiple times in the same session unless the user explicitly asks for separate audiences. Ask first if you're unsure. **How to fill the arguments.** - `prompt`: natural-language description of the *people* in the audience, including any sub-country geography (states, regions, cities, ZIP codes), demographics (age, gender, income, profession), and behavioral attributes (interests, brand affinities, sites visited). - `location`: country code only — `us`, `ca`, or `uk`. Do NOT put country names in the prompt; do NOT put states/cities in `location`. **Example.** User asks: "audience of male golfers in Washington state, ages 30-50." → `prompt="male golfers aged 30-50 in Washington state"`, `location="us"`. **Two-step lifecycle.** Returns immediately with `{report_id, status: "processing"}`. The audience is built asynchronously (~20-40s). Poll `get_report_status` with the report_id every 5-10 seconds until `status` is "ready". Once ready, **stop and ask the user what they want to know about the audience** — do not proactively call every section tool. Section tools should be called only in response to the user's specific question (e.g. user asks about podcasts → call `get_podcasts`, not all 13 sections). Do not call section tools while processing. **Reuse over recreate.** If the user is asking about an audience already built in this conversation, reuse the existing `report_id` instead of creating a new report.

create_report

Demographics for an audience: gender split, age distribution, salary bands, job titles by role and seniority, and company size. Typically returns in under a second on cache hit; first-touch may take several seconds. Use this when the user asks "who is this audience" — it gives the most concrete picture of the people in the audience. Pairs well with `get_bio_keywords` for richer descriptive language.

get_demographics

List the user's recent audience reports — useful when the user references a past audience without a `report_id`. Returns an array of `{report_id, prompt, created_at, status}` ordered by most recent first. Use the `report_id` from the matching entry with section tools (`get_demographics`, `get_websites`, etc.) — no need to call `create_report` again for an audience that already exists.

list_reports

Podcasts this audience listens to — show titles, hosts, networks, descriptions, and audience affinity scores. Use this for podcast advertising, sponsorship, and guest-pitching strategy. Results are sourced via vector search over a Postgres podcast index keyed off the audience's source domains, so cache-hit and first-call latency are similar — typically under 2 seconds.

get_podcasts