pro.particle/particle-pro

Create an alert that watches a single entity and emails you whenever it is mentioned on a podcast episode (kind=ENTITY_MENTION) or appears as a speaker (kind=PODCAST_SPEAKER). Pass the entity slug from a resolve tool — resolve a name with particle_entity_resolve, then create the alert with the slug it returns. An alert watches exactly one entity; to cover several entities, call this tool once per entity. When a name has no entity slug, or its entity has no podcast coverage (a startup known by a brand that differs from its legal name, a product, a drug, a code word), create a kind=KEYWORD_MENTION alert with `keyword` instead of `entities`. It fires whenever the phrase is spoken — the match particle_podcast_search_transcripts makes for a double-quoted keyword_search phrase (words adjacent and in order), not the looser unquoted match — so also set `description` to say what the phrase means; that is how same-name mentions of something else are filtered out. Use the optional `filters` object to narrow what gets surfaced on every channel (matches list, realtime email, daily/weekly digest). Four independent axes: `languages` (BCP-47-like tags like ['en','pt-BR'] — empty means all languages), `relevance` (EVERYTHING returns on-target + incidental matches, RELEVANT narrows to on-target only — dropping passing mentions), `source_popularity` (ANY keeps every source, POPULAR keeps only matches from podcasts in the top 5% by chart popularity), and `speaker_roles` (PODCAST_SPEAKER alerts only — REPLACES the default appearance set GUEST/PANELIST/CORRESPONDENT/AUDIENCE/SOUNDBITE_SPEAKER; sending it on an ENTITY_MENTION alert errors with unprocessable_entity). Billing: creating an active alert can move an eligible organization's subscription from its credit/trial phase to paid fixed-fee billing. Explain this possible billing change and obtain the user's explicit confirmation before creating an active alert. Creating a paused alert (is_active=false) does not trigger this billing…

Delete an alert. This is a soft delete: the alert stops producing matches and disappears from particle_alert_list, but its past matches and deliveries are retained for audit. To pause an alert instead of removing it, use particle_alert_update with is_active=false.

Fetch a single alert's full configuration — title, kind, cadence, watched entities (with names), notification emails, and any active filters (languages, relevance, source_popularity, speaker_roles). The `filters` section is omitted when the alert carries none. By default the response is just the configuration; request include=['matches'] to embed the most recent matches it has caught and include=['deliveries'] for the email audit log. For the full, paginated match history with transcript excerpts, use particle_alert_list_matches.

List the alerts in your project, newest first. Each entry carries the alert `id` — feed it into particle_alert_get for full configuration, particle_alert_list_matches for what it has caught, or particle_alert_update / particle_alert_delete to manage it.

List the matches an alert has caught, newest first — the payoff of an alert. Each match names the watched entity and the podcast episode it was detected on (with episode and podcast slugs that feed particle_podcast_get_episode and particle_podcast_resolve). Use view=detailed to include the transcript excerpts around each mention, and after/before to scope to a date range. Backfilled matches (from the past-week sweep at creation) are flagged and never triggered an email.

Preview how often an alert would fire BEFORE creating it. Sweeps the past N days (default 7, max 30) for the given entity (or keyword, for kind=KEYWORD_MENTION) and returns the total match count, a per-day breakdown, and a small sample of the most recent matches with episode context. Use this to size an alert (REALTIME vs DAILY vs WEEKLY cadence) or to confirm the entity slug watches the right thing, then call particle_alert_create with the same entity slug (for KEYWORD_MENTION, the same keyword instead). Pass the same `filters` you plan to save so the estimate matches what the alert would surface — the languages and speaker_roles axes narrow the sweep; relevance and source_popularity are read-time projections that don't, so the count is an upper bound when relevance=RELEVANT. Starts a background sweep and caches its progress and results; it does not create an alert or send notifications.

Update an existing alert. Only the fields you pass change; the entities and notifications lists, when provided, replace the whole set (pass a single entity slug from the resolve tools, same as particle_alert_create — an alert watches exactly one entity). A KEYWORD_MENTION alert takes a new `keyword` instead of `entities`. Use is_active to pause or resume an alert without deleting it. An alert's kind is fixed at creation — to change it, create a new alert. The optional `filters` object replaces the alert's filter set wholesale — omit to leave the existing filters unchanged, send {} to clear all filters. Same four axes as particle_alert_create.filters: `languages`, `relevance` (EVERYTHING/RELEVANT), `source_popularity` (ANY/POPULAR), and `speaker_roles` (PODCAST_SPEAKER alerts only — sending it on an ENTITY_MENTION alert returns unprocessable_entity).

Dispatch any public Particle tool by name. Compatibility fallback for harnesses that block calling tools that weren't advertised on tools/list — every public Particle tool is executable by name, so prefer calling discovered tools directly when your harness allows it. Identical metering and plan gating apply either way. Use particle_catalog to discover tool names and input schemas.

Browse the full Particle tool catalog. Your tools/list shows only the default categories, but EVERY public Particle tool is callable by name regardless of what was advertised — call this tool to discover the rest. Without arguments: the categorical menu (every category with tool names, one-line summaries, and an `↳` line listing each tool's expand options). With `category`: the full input schema for each of that category's tools, ready to call. Two conventions the one-line summaries don't convey, so read tools through this lens: - Tools are lean by default and EXPAND. Most return a minimal payload and opt into richer sections via an `include` array (e.g. a company's people, products, and competitors; a person's roles and podcast appearances) or change behavior via a `mode`/`format` switch. The `↳` line names these — a tool does far more than its summary alone implies. - Responses are a graph; slugs are edges. A slug a tool returns (person, company, podcast, episode, publisher, guest) is a valid input to the other tools, so you resolve once and then traverse: company → its people → a person's podcast appearances → that episode's transcript and every entity in it. Categories on offer: - `system` (always-on): Discovery meta-tools: browse the full tool catalog and call any tool by name. - `podcasts` (default): Resolve podcasts, list and fetch episodes, search transcripts, and find entity mentions. - `people` (default): Resolve people and entities to canonical handles and fetch person profiles. - `companies` (default): Resolve companies and fetch company profiles with people, products, and competitors. - `topics` (default): Browse the hierarchical topic taxonomy used to classify podcast episodes. - `podcast_rankings` (default): Podcast chart rankings: current charts, movers, and ranking history. - `podcast_guests` (default): Podcast guest directory, trending guests, and per-guest appearance profiles. - `podcast_advertising` (opt-in): Podcast advertising intelligence:…

Return a bundled profile for one company: identifiers (slug, ticker, domain, CIK, QID, linked entity), name, and description. Request optional sections via `include`: 'people' for current leadership and notable people (person slugs feed `particle_person_get`), 'products' for the three-level product hierarchy, 'competitors' for the competitor list, 'external_links' for the company's LinkedIn, social profiles, domain, Wikidata QID, SEC CIK and tickers. The default response is lean — include only what you need. For sponsor/advertising analytics on this company, use `particle_company_get_podcast_ad_presence` instead.

Resolve a company by free-text name, ticker, SEC CIK, Wikidata QID, or domain. Returns candidates with the agent-facing identifier (`slug`, falling back to `domain` or `id`) you should pass to `particle_company_get`, `particle_company_get_podcast_ad_presence`, `particle_podcast_find_mentions` (as `company_slug`), or `particle_podcast_list_episodes`. At least one identifier is required. Multiple are ANDed together — useful for disambiguating (e.g. ticker plus a name hint). For people or other knowledge-graph entities (not companies) use `particle_entity_resolve` instead.

One knowledge-graph entity's profile: name, kind, description, and Wikipedia link. Use it to confirm what a slug from `particle_entity_resolve` actually refers to — especially for the long tail that isn't a person or company (places, organizations, events, products, concepts). When the entity is a linked person or company the response carries the person_slug / company_slug — prefer `particle_person_get` / `particle_company_get` for those, which return the full profiles. Entity slugs feed `particle_podcast_find_mentions`, `particle_podcast_get_episode_timeseries`, and the alert tools.

Resolve any named thing — person, company, place, or other entity — by free-text name in one union search. Each candidate carries a `type` and the canonical `slug` for that type: - `person`: the canonical person slug. Feed it into `particle_person_get`, every `person_slug` parameter (`particle_podcast_find_mentions`, `particle_podcast_search_transcripts`, `particle_podcast_list_episodes`), or `particle_podcast_get_guest`'s `guest_slug`. - `company`: the canonical company slug. Feed it into `particle_company_get` and every `company_slug` parameter. - `place`/`other`: a bare entity slug. Feed it into the `entity_slug` parameter on `particle_podcast_find_mentions`, `particle_podcast_search_transcripts`, and `particle_podcast_list_episodes` to filter by that entity. Use this first whenever you only have a name and don't know what kind of thing it names. If you already know it's a person, `particle_person_resolve` ranks people only; for companies with a known ticker, domain, CIK, or QID, `particle_company_resolve` has more identifier surface. For bulk resolution, pass a comma-separated `query` (e.g. "sam altman, nvidia, davos") — each name is resolved independently in a single call and `limit` applies per query.

Return a person's profile: name, current role, and bio, keyed by the canonical person slug from `particle_person_resolve`. Request optional sections via `include`: 'external_links' for LinkedIn/Wikipedia/social profiles, 'podcast_appearances' for their most recent podcast appearances (episode and podcast slugs included for follow-up calls), 'companies' for the full role history. The default response is lean. For podcast-guest analytics (appearance stats, suitability exposure, co-appearance graph) use `particle_podcast_get_guest` with the same slug.

Resolve a person by free-text name. Returns ranked candidates with the canonical person `slug` — the stable handle accepted by `particle_person_get`, by every `person_slug` parameter (`particle_podcast_find_mentions`, `particle_podcast_search_transcripts`, `particle_podcast_list_episodes`), and by `particle_podcast_get_guest`'s `guest_slug`. For bulk resolution, pass a comma-separated `query` — each name resolves independently in one call. For organizations, places, or mixed/unknown entity kinds use `particle_entity_resolve`; for companies with a known ticker or domain use `particle_company_resolve`.

Find dialogue lines where a specific person or company is named in podcast transcripts. ## Two response modes **`format="summary"` (default, wide scan).** Returns up to `limit` episodes (reverse-chronological), each with metadata + the first 10 mention-only lines (just the lines naming the entity, no surrounding dialogue). Use this to see *what's been said across episodes* and decide which episodes are worth reading in full. Paginate older episodes with `cursor`. **`format="detail"` (narrow drill-in).** Requires `episode_slug`. Returns the full mention windows with `context_lines` of surrounding dialogue around each mention. Pass one slug for a single episode, or up to 10 comma-separated slugs (e.g. `episode_slug="all-in-200,all-in-201,all-in-202"`) to multi-get several episodes in one call. `limit`/`cursor` don't apply. ## Workflow Two patterns, depending on what you already know: - **No specific episode in mind:** call `format="summary"` first to scan, then call `format="detail"` with the slug(s) of the episodes worth reading in full. For most questions (sentiment, recurring themes, who said what when), summary alone has enough signal and the second call isn't needed. - **Already have the episode slug** (e.g. user mentioned the episode by name, or you have it from another tool like `particle_podcast_get_episode` or `particle_podcast_search_transcripts`): skip summary entirely and call `format="detail"` with `episode_slug` directly. ## Examples *Wide scan, then drill in:* User asks "what has All-In said about OpenAI recently?". Call `format="summary"`, `company_slug="openai"`, `podcast_slug="all-in"`, `since="2025-11-01"`, `limit=20`. Read the mention lines per episode; if 2-3 episodes have substantive discussion, call `format="detail"`, `episode_slug="slug1,slug2,slug3"` for full context in one round-trip. *Direct drill-in:* User says "In All-In #200 they discuss OpenAI's strategy — pull the full quotes". Call `format="detail"`, `episode_slug="all-in-20…

Return a bundled overview of one podcast episode: title, podcast, speakers (with entity slugs), top mentioned entities, and segment/clip counts. By default the response is lean — counts plus the top mentioned entities. Request optional sections via `include`: 'segments' for the structural outline with timestamps, 'entities' for the complete entity list, 'clips' for engagement-ranked highlight clips, 'topics' for topic classifications with slugs, or 'transcript' for the dialogue transcript (narrow it by speaker or time range via `transcript_speaker` / `transcript_start` / `transcript_end` — full transcripts are large). For "every line about X in this episode" use `particle_podcast_find_mentions` with `episode_slug` instead — that returns the dialogue around each mention with `is_mention` flags. For the ad reads inside the episode use `particle_podcast_get_episode_ads` (premium).

Time-bucketed episode counts — the purpose-built answer to "how often is X discussed over time". Counts episodes matching the same filters as `particle_podcast_list_episodes` (person, company, entity, podcast, keyword, language, duration, transcript availability) per day, week, or month, plus range totals. `keyword_search` additionally counts matching transcript segments per bucket (exact counts); `semantic_search` does the same by meaning, with the same similarity threshold as `particle_podcast_search_transcripts` (lower bounds for pathologically broad queries), and requires `published_after`. The two cannot be combined. Use this for appearance, publication, or topic trend lines instead of paging `particle_podcast_list_episodes`, `particle_podcast_find_mentions`, or `particle_podcast_search_transcripts` once per period. Buckets are UTC-aligned, zero-filled, and Monday-aligned for weeks; ranges are capped at 1000 buckets. At least one of podcast_slug, person_slug, company_slug, entity_slug, keyword_search, or semantic_search is required.

A guest's podcast-appearance profile: lifetime stats (appearances, distinct podcasts, first/last appearance) plus their most frequent podcasts. Guests are people — the same slug works with `particle_person_get` for the biographical profile. Request optional sections via `include`: 'appearances' for the most recent episode appearances (episode and podcast slugs included for follow-up calls), 'podcasts' for the per-podcast rollup, 'suitability' for brand-suitability exposure across the podcasts they appear on, 'recommended_podcasts' for the five shows they could plausibly appear on next — shows related to the ones they have guested on, minus those, with the venues behind each pick (the pitch list; branch on each row's band). Returns not_found for people who exist but have never appeared on a podcast — use `particle_person_get` for those.

Podcast chart rankings from Apple Podcasts and Spotify, in four modes: - `chart` (default): the current chart for a source/country/category slot, or — with `podcast_slug` — every chart slot that podcast currently holds. - `movers`: the biggest rank changes over `window_days` (risers, fallers, debuts, exits). - `history`: past snapshots for a chart slot, or — with `podcast_slug` — one podcast's chart history over time. - `slots`: the valid slot values — every source, country, and category_slug with live chart data — so filter values are discovered, not guessed. `source` narrows the country/category listings; other filters are ignored. Each row carries the matched `podcast_slug` when the chart entry is in the catalog — feed it into `particle_podcast_resolve` or any podcast tool. For a single podcast's at-a-glance chart presence, `particle_podcast_resolve` with `include: ["rankings"]` is one call instead of two.

Browse AI-extracted highlight clips across the catalog, ranked by engagement potential — the shareable moments. Filter by podcast, episode, clip type (FUNNY, CONTROVERSIAL, INSIGHTFUL, ...), minimum engagement score, or speaker — `speaker` takes a person slug and returns only clips of that person talking ('an insightful Sam Altman clip'). Pass `clip_id` for one clip's full detail (description, social-hook intro, speaker, audio URL), plus `include: ["transcript"]` for its dialogue. For text-based clip discovery — finding clips about a topic or entity — use `particle_podcast_search_transcripts` instead: matching clips arrive inline on each search result. Episode slugs on every row feed `particle_podcast_get_episode`.

List episodes across the catalog with rich filters: by podcast, person, company, language, date range, duration, or transcript availability. Use this for episode-level discovery when you only need metadata (title, duration, speakers, counts). For dialogue around a person in any episode, use `particle_podcast_find_mentions`. For ranked retrieval by topic, use `particle_podcast_search_transcripts`.

Browse podcast guests across the catalog, in two opinionated modes: - `directory` (default): the guest directory ranked by lifetime appearances (guests with 2+ appearances). - `trends`: who's making the rounds right now — guests with appearances on 2+ distinct podcasts in the last 30 days, which surfaces cross-show press tours rather than show regulars. The press-tour shape is enforced: every in-window appearance must be on a different podcast, each needs 5+ minutes of identified speaking time, mononymous catch-all people are excluded, and the in-window rate must be a 2x spike over the guest's lifetime baseline. `podcast_slug` switches the directory to one show's roster: every guest who has appeared on that podcast, ranked by appearances on the show (one-off guests included). `topic_slug` narrows either corpus mode to guests appearing on episodes about that topic. Guest slugs ARE person slugs — feed them into `particle_podcast_get_guest` for the appearance profile or `particle_person_get` for the person profile.

List the shows most related to a podcast, best first — "shows like this show". Each result carries the related show's slug, a calibrated score in (0,1], and a coarse band (strong: same beat and audience; moderate: overlapping subject or audience; weak: a loose connection) to branch on. Add `include: ["basis"]` to see WHY each pair is related: content similarity of recent episodes, shared topics, shared guests (named), same publisher, shared sponsors — use it to explain a recommendation or to keep only pairs related for the reason you care about (shared guests for booking, content for media planning). Related sets are precomputed per show from its transcripts, topic profile, guest roster, network and advertisers, restricted to the show's language. Only shows above a relatedness floor are listed, machine-generated and farmed feeds are never listed, and a publisher's duplicate feeds of one show appear once. An empty FIRST page is not an error: its `coverage` says whether the set is not computed yet, nothing cleared the floor, or the request's filters and the default policy removed everything; an empty page reached through a cursor is simply the end of the list. Not a topic browser: for shows that COVER a topic use `particle_podcast_resolve` with `topic_slug`. Not a guest lookup: for where a person has appeared use `particle_podcast_get_guest`. Not advertiser co-occurrence: use `particle_podcast_get_sponsors`. Every related show's slug feeds `particle_podcast_resolve`, `particle_podcast_list_episodes` and the other podcast tools; person slugs in the basis feed `particle_podcast_get_guest`, topic slugs feed `particle_podcast_resolve`'s `topic_slug`. For the five most related shows inline on a resolve, pass `include: ["related"]` to `particle_podcast_resolve` instead of calling this tool.

Episodes from OTHER shows that cover the same story or subject as a given episode, best first — a live nearest-neighbour search over episode content, reranked on shared salient entities, shared topics and a shared news story. Each row carries a calibrated score and a band (strong / moderate / weak) to branch on; pass `include: ["basis"]` to see the signals behind every match. Each show contributes at most two episodes, the same content republished on another feed is collapsed to one row, and feeds the screens flag as machine-made or syndication spam are excluded. Use it when you already have an episode and want its coverage elsewhere ('who else covered this?'). Add `published_within_days` (7–30) to keep to the same news cycle; `same_podcast: true` admits the show's own episodes, which are otherwise excluded. Do NOT use it to find dialogue about a topic — that is `particle_podcast_search_transcripts` — nor to find every line naming an entity, which is `particle_podcast_find_mentions`. Episode slugs on every row feed `particle_podcast_get_episode`; podcast slugs feed `particle_podcast_resolve`.

Find a podcast by free-text title, exact slug, iTunes ID, or RSS feed URL. Returns slug, title, episode count, bias, and the top recurring speakers (with entity slugs). Use the slug as the agent-facing handle to feed into other podcast tools (`particle_podcast_find_mentions`, `particle_podcast_list_episodes`, `particle_podcast_get_sponsors`). Free-text matching is forgiving — typos, missing or extra words, and pasted episode titles all work. Results are ordered best-match-first; text matches carry a `match_quality` field, and an empty list means the catalog has no plausible candidate. With all identifiers omitted, returns the most recently updated podcasts — useful for browsing the catalog when you don't have a name in mind. Narrow free-text browsing with `topic_slug` (topic concentration, descendants included), `suitability_tier`, or `min_popularity` (global popularity percentile over charting podcasts). Optional hydrations attach extra data to each result in the same call: - `include: ["external_links"]`: third-party platform presences (directories, social profiles, video channels, publisher websites) with resolved URLs and audience metrics. - `include: ["suitability"]`: per-category brand-suitability breakdown (12 categories with prevalence, treatment, derived risk level, reasoning, and evidence excerpts) — premium-grade data, requires a plan with premium endpoints. The high-level `suitability_tier` enum (SAFE / LIMITED / SENSITIVE / UNSAFE) is rendered on every result without opt-in. - `include: ["ratings_summary"]`: listener-review aggregate (average stars, count, per-platform breakdown). - `include: ["bias"]`: full political-bias analysis (the high-level bias enum is always rendered without opt-in). - `include: ["rankings"]`: current chart positions across sources/countries/categories — premium-grade data, requires a plan with premium endpoints. For movers and history use `particle_podcast_get_rankings`. - `include: ["format"]`: the show's form…

Search the podcast catalog by what is said in episodes — by meaning (`semantic_search`), by exact phrase (`keyword_search`), or both at once (hybrid ranking). This is THE way to retrieve relevant dialogue, segments, and clips: each result is one segment of one episode with bounded transcript windows pinpointing the highest-relevance lines, plus any highlight clips that overlap the segment inline on the match. Segments partition an episode's transcript — where start_line and end_line are present, every spoken line belongs to exactly one segment and one segment's end_line + 1 is the next one's start_line. They are contiguous in transcript lines, not in wall-clock seconds: the seconds between one segment's end_seconds and the next's start_seconds contain no transcribed speech. These matches do not carry the line ranges themselves — fetch them with `particle_podcast_get_episode` and `include: ["segments"]`, where their absence marks an episode segmented by an earlier version, a small share of which do leave lines uncovered. Clips are sparse, engagement-ranked highlights that overlap some segments. There is no separate clip-search tool — relevant clips arrive on these matches, and a known episode's full clip list is `particle_podcast_get_episode` with `include: ["clips"]`. A match window defaults to one line of context around each matched line; raise `context` to widen windows in place instead of fetching the full transcript. Use this for "find dialogue *about* a topic". For "every line *naming* a person or company" use `particle_podcast_find_mentions` instead — `person_slug` and `company_slug` here narrow ranked results, they don't drive the ranking. **Choosing your query.** At least one of `semantic_search` or `keyword_search` is required, and they do different jobs: - `semantic_search` carries the *idea*. Write it as a sentence describing what should be discussed, in the vocabulary a speaker would use. It is paraphrase-tolerant, so it finds the topic however it h…

Navigate the topic taxonomy. Without `parent_slug`, returns the top-level roots (Politics, Business, Technology, etc.). With `parent_slug` set, returns the direct children of that topic. Topic slugs use a `parent/child` convention (e.g. `politics/elections`) and let agents browse the hierarchy to find well-named categories.