create_report
ChatGPTCreate 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.
get_apps
ChatGPTApps 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_bio_keywords
ChatGPTWords 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_brands
ChatGPTBrands, 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_demographics
ChatGPTDemographics 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_networks
ChatGPTSocial networks the audience uses heavily — which platforms over-index for this group (e.g. "this audience is 3.2x more active on LinkedIn than the average internet user"). Fast. Use this to answer "where should I reach this audience" at the platform level. For specific accounts to follow on each network, call get_social instead.
get_podcasts
ChatGPTPodcasts 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_press
ChatGPTNews and press outlets this audience reads — publications, journalists, and beats relevant to this group. Use this for PR and media-relations work: which outlets to pitch, which journalists cover this audience, where earned coverage will reach the right people.
get_prompts
ChatGPTLikely 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_quota
ChatGPTCheck 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_reddit
ChatGPTSubreddits this audience participates in — community names, member counts, and audience affinity. Use this for community marketing, AMAs, ad targeting on Reddit, or qualitative research into how this audience talks about its problems.
get_report_status
ChatGPTCheck 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_search_keywords
ChatGPTSearch keywords this audience uses — terms they actively look up and engage with, ranked by audience affinity. Use this for SEO opportunity finding, content ideation, and ad campaign keyword expansion. Cold-path calls can take up to 2 minutes on the first fetch for a report; cached calls return in under a second. If a call times out, retry once — the second call hits the populated cache.
get_social
ChatGPTSpecific social-media accounts this audience follows — usernames, platforms, follower counts, and audience affinity. Use this for influencer marketing, partnership identification, and community research. For platform-level insights ("how active is this audience on TikTok overall"), call get_networks instead.
get_tam
ChatGPTTotal addressable market for this audience: estimated population, year-over-year growth, estimated annual market value (USD), and the rationale explaining the data sources and assumptions behind the estimate. Use this when the user asks about audience size, market opportunity, or "how big is this audience" in commercial terms. Pairs well with get_demographics for context on who is in that market. Always surface the rationale to the user — these are estimates, not exact counts, and the rationale shows which sources (Census, BLS, Statista, etc.) and assumptions drove the number.
get_website_categories
ChatGPTThe IAB content categories this audience's websites fall into — a higher-level view than individual domains (get_websites). Answers "what kinds of content does this audience spend time on" and how much they over-index on each category vs. the typical person in the report's country. Each returned category carries an iab_id. To drill into a category's subcategories, call this tool again with that iab_id. Without iab_id you get the top-level (tier-1) breakdown. Each category includes its audience share, the country-baseline share, and an over-index ratio (how much more this audience concentrates there than average).
get_websites
ChatGPTWebsites this audience visits — domains with audience affinity scores, monthly visit estimates, and domain authority. Use this to answer "where does this audience spend time online" at the website level. Foundational for content distribution, guest posting, partnerships, and ad placement.
get_youtube
ChatGPTYouTube channels this audience watches — channel names, subscriber counts, and audience affinity scores. Fast. Use this for video-content strategy: which creators to sponsor, partner with, or study for content ideas.
list_reports
ChatGPTList 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.
create_report
Claudeget_apps
Claudeget_bio_keywords
Claudeget_brands
Claudeget_demographics
Claudeget_networks
Claudeget_podcasts
Claudeget_press
Claudeget_prompts
Claudeget_quota
Claudeget_reddit
Claudeget_report_status
Claudeget_search_keywords
Claudeget_social
Claudeget_tam
Claudeget_website_categories
Claudeget_websites
Claudeget_youtube
Claudelist_reports
Claude
