> ## Documentation Index
> Fetch the complete documentation index at: https://docs.particle.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> What's new on the Particle Pro MCP server — new tools and capabilities, and anything that changes how your agent connects or calls.

Tool *behavior* grows additively — new `include` sections and modes never break an existing call. Renames and changes that could affect your integration are called out explicitly.

## July 2026

### Ad timeseries scopes to a show or a network

[`particle_podcast_get_ad_trends`](/mcp/tools/podcast_advertising/podcast-get-ad-trends) in `timeseries` mode now takes `podcast_slug` and `publisher_slug`, so a company's ad volume can be charted on one show or across one publisher's catalog instead of the whole corpus. Both accept a slug or an ID, matching the same filters on the mentions timeseries — which is what makes organic mentions and ad reads comparable under one scope. A reference that resolves to nothing returns zero-filled buckets rather than silently widening back to the full corpus. Omitting both preserves the previous behavior. The REST endpoint `GET /v1/podcasts/advertising/timeseries` gained the matching `podcast_id` and `publisher_id` query parameters.

### REST parity: five new tools and six expanded ones

The MCP surface now covers every public GA REST capability. Five new tools:

* [`particle_podcast_get_episode_timeseries`](/mcp/tools/podcasts/podcast-get-episode-timeseries) — time-bucketed episode and mention counts with the same filters as `particle_podcast_list_episodes` plus `keyword_search`; the purpose-built answer to "how often is X discussed over time".
* [`particle_podcast_list_clips`](/mcp/tools/podcasts/podcast-list-clips) — browse highlight clips by podcast, type, or engagement score, with a `clip_id` detail path and `include=["transcript"]`.
* [`particle_podcast_get_episode_ads`](/mcp/tools/podcast_advertising/podcast-get-episode-ads) (premium) — every detected ad read inside one episode with sponsor, product, offer, read type, placement, and exact offsets.
* [`particle_podcast_get_ad_trends`](/mcp/tools/podcast_advertising/podcast-get-ad-trends) (premium) — `sponsor_trends` (advertisers ramping up or pulling back) and `timeseries` (one company's ad volume over time, split host-read vs pre-recorded).
* [`particle_entity_get`](/mcp/tools/people/entity-get) — a knowledge-graph entity's profile, closing the loop for `place`/`other` slugs from `particle_entity_resolve`.

And six expanded surfaces (all additive — existing calls are unchanged):

* [`particle_podcast_list_guests`](/mcp/tools/podcast_guests/podcast-list-guests) takes `podcast_slug` for one show's guest roster (one-off guests included).
* [`particle_podcast_get_rankings`](/mcp/tools/podcast_rankings/podcast-get-rankings) adds `mode=slots` — every valid source, country, and `category_slug` with live chart data, so filter values are discovered rather than guessed.
* [`particle_podcast_get_publisher`](/mcp/tools/podcast_publishers/podcast-get-publisher) takes `query` to resolve a publisher name to a slug in the same call (candidates on ambiguity). The REST `GET /v1/podcasts/publishers` listing gained the matching `q` filter.
* [`particle_podcast_get_sponsor_leaderboard`](/mcp/tools/podcast_advertising/podcast-get-sponsor-leaderboard) adds `mode=publishers` (the sell-side leaderboard with `unique_sponsors` and `ads_per_active_podcast` metrics) and a `publisher_slug` filter for sponsors mode.
* [`particle_company_get_podcast_ad_presence`](/mcp/tools/podcast_advertising/company-get-podcast-ad-presence) adds `include=podcasts` (full ranked show list), `include=segments` (actual ad-read segments with AI summaries), and `include=co_advertisers` (sponsor pairs sharing episodes).
* [`particle_podcast_get_episode`](/mcp/tools/podcasts/podcast-get-episode) cross-references the new episode-ads tool.

### Premium include sections now honor the plan's premium entitlement

The include sections that carry premium-grade data on standard-tier tools now require a plan with premium endpoints, matching the premium-tier tools themselves: `suitability` and `rankings` on [`particle_podcast_resolve`](/mcp/tools/podcasts/podcast-resolve), and `bias`, `suitability`, and `advertising` on [`particle_podcast_get_publisher`](/mcp/tools/podcast_publishers/podcast-get-publisher). Entitled plans are unaffected. A plan without premium endpoints now receives a `premium_required` error naming the offending include values — retry without them for the standard sections (the high-level `suitability_tier` and `bias` enums on resolve results are standard data and always rendered).

### Filter-aware alert previews

[`particle_alert_preview`](/mcp/tools/alerts/alert-preview) now accepts the same `filters` object as [`particle_alert_create`](/mcp/tools/alerts/alert-create), so the match-frequency estimate reflects what the alert would actually surface once its filters are applied. `languages` and `speaker_roles` narrow the historical sweep exactly; `relevance` and `source_popularity` are graded at read time and don't run on historical episodes, so they leave the count unchanged (the estimate is an upper bound when `relevance=RELEVANT`). The preview cache key keys on the count-affecting filters — changing `languages` or `speaker_roles` starts a fresh sweep, while toggling `relevance` or `source_popularity` returns the same cached count. Omitting `filters` preserves the previous unfiltered behavior.

## June 2026

### Alert filters — narrow what an alert surfaces

Alerts now carry a persistent `filters` object that narrows what gets surfaced — applied identically to the matches list, the realtime email, and the daily/weekly digests. Four axes: `languages` (BCP-47 tags), `relevance` (`EVERYTHING` vs `RELEVANT`), `source_popularity` (`ANY` vs `POPULAR` = top 5% of currently-charting podcasts), and `speaker_roles` for `PODCAST_SPEAKER` alerts (defaults to `GUEST,PANELIST,CORRESPONDENT,AUDIENCE,SOUNDBITE_SPEAKER`; sending it on an `ENTITY_MENTION` alert returns an `unprocessable_entity` error).

[`particle_alert_create`](/mcp/tools/alerts/alert-create) and [`particle_alert_update`](/mcp/tools/alerts/alert-update) accept the `filters` object directly, and [`particle_alert_get`](/mcp/tools/alerts/alert-get) / [`particle_alert_list`](/mcp/tools/alerts/alert-list) echo the active filter set back so reads expose the current state. Update semantics mirror `entities`/`notifications`: passing `filters` on update **replaces** the whole set, `{}` clears all four axes, and omitting it leaves the existing set unchanged. See [Alerts → Filtering matches](/alerts/overview#filtering-matches) for the per-axis spec and the [REST changelog](/changelog#alert-filters-narrow-what-an-alert-surfaces) for the wire shape — the same filter object is accepted on `POST /v1/projects/{projectId}/alerts` and `PATCH /v1/alerts/{id}`.

### Better entity & person resolution

* [`particle_entity_resolve`](/mcp/tools/people/entity-resolve) and [`particle_person_resolve`](/mcp/tools/people/person-resolve) now rank across people, companies, and knowledge graph entities with one relevance model (exact name / identifier / known alias → prefix → all-words → fuzzy), replacing the prior name-only substring match. Results are better-ordered and tolerate typos, stock tickers, `@handles`, and domains. `particle_person_resolve` also now finds people who aren't yet linked to a knowledge-graph entity. Each match carries the canonical `slug`, `name`, and `description` (plus a company's `company_domain`) — enough to confirm the hit and traverse to the matching `get` tool.

### Alerts

* **Seven alert lifecycle tools** — a new default `alerts` category brings the [Alerts](/api-reference/alerts) feature to the MCP surface: [`particle_alert_create`](/mcp/tools/alerts/alert-create), [`particle_alert_list`](/mcp/tools/alerts/alert-list), [`particle_alert_get`](/mcp/tools/alerts/alert-get), [`particle_alert_update`](/mcp/tools/alerts/alert-update), [`particle_alert_delete`](/mcp/tools/alerts/alert-delete), [`particle_alert_preview`](/mcp/tools/alerts/alert-preview), and [`particle_alert_list_matches`](/mcp/tools/alerts/alert-list-matches). Watch a person, company, or other entity and get emailed whenever it's mentioned on a podcast (`ENTITY_MENTION`) or appears as a speaker (`PODCAST_SPEAKER`); preview match frequency before committing; and review the matches an alert has caught.
* **The first writable tools** — `particle_alert_create`/`particle_alert_update` mutate and `particle_alert_delete` is a destructive soft delete, so these are *not* `readOnlyHint: true`. They act on the **single project your credential is scoped to** — there is no project parameter and no way to reach another project's alerts. Watch targets are passed as the same entity slugs the resolve tools return (resolve a name once, then watch it).

### Richer external links

* **External-link attributes in markdown** — when [`particle_podcast_resolve`](/mcp/tools/podcasts/podcast-resolve) hydrates `include: ["external_links"]`, each platform bullet now appends the attributes the platform reports (audience size, content tallies, verified status, ...), so a YouTube channel renders its subscriber and video counts alongside the URL rather than the link alone. The attributes were already present on the `output_format: "json"` form; this surfaces them in the default markdown.

### Agent discovery (auth.md)

* **`/auth.md`** — both hosts now serve the [auth.md](https://github.com/workos/auth.md) agent-onboarding document at [`https://api.particle.pro/auth.md`](https://api.particle.pro/auth.md) and [`https://mcp.particle.pro/auth.md`](https://mcp.particle.pro/auth.md): the discovery walkthrough, a credential decision tree, registration steps, errors, and revocation, with the flows Particle Pro deliberately does not offer declared up front.
* **`agent_auth` block** — the [AS metadata](https://api.particle.pro/.well-known/oauth-authorization-server) now embeds a machine-readable registration summary (`register_uri`, identity and credential types, revocation). [Authentication → Agent discovery](/mcp/authentication#agent-discovery).
* **REST protected-resource metadata** — `https://api.particle.pro/.well-known/oauth-protected-resource` now serves an RFC 9728 document describing the REST API resource (previously 404). The MCP document at `https://mcp.particle.pro/.well-known/oauth-protected-resource` is unchanged.

### Skill bundles and exact-tool selection

* **[Skill bundles](/mcp/skills)** — three ready-made skills (Podcast Intelligence, Company Deep Dive, Guest & People Research): a connection URL scoped to just the tools each workflow needs, plus a copy-paste SKILL.md that teaches your agent the workflow.
* **`?tools=` selector** — pin a connection to exactly the tools you want advertised: `?tools=particle_podcast_resolve,particle_podcast_search_transcripts`. See [Tool sets & discovery](/mcp/tool-sets#selecting-exact-tools).
* **More clients in the quickstart** — Windsurf, Zed, ChatGPT developer mode, and server-side wiring examples for the Anthropic Messages API and OpenAI Responses API. [Quickstart](/mcp/quickstart).

### Connect without a browser

* **API keys as MCP credentials** — the server now accepts the same `pp_*` project API keys as the REST API (`Authorization: Bearer` or `X-API-Key`), so headless agents — cron jobs, the OpenAI Responses API, server-side harnesses — no longer need an interactive OAuth consent. OAuth remains the recommended path when a human is present. [Authentication](/mcp/authentication#api-keys-for-headless-agents).
* **One-click installs** — Cursor and VS Code install buttons in the [Quickstart](/mcp/quickstart).
* **[llms.txt](https://docs.particle.pro/llms.txt)** — now opens with instructions for LLM agents: which surface to pick, how the tools compose, and the conventions that save wasted round-trips.

### Smarter discovery on connect

* **Conventions taught up front** — connecting clients now receive server instructions covering the two things a bare tool list doesn't show: tools are lean by default and expand via `include`/`mode`/`format` parameters, and every slug a tool returns is a valid input to the other tools (resolve a name once, then traverse).
* **`particle_catalog` shows each tool's depth** — the catalog menu lists every tool's expand options (`↳ include: … · mode: …`), so an agent can see what a tool can really do before fetching its full schema.

### 25 tools, flat names, opt-in categories

* **Renames (action needed if you call tools by name)** — every tool moved to a flat `particle_*` identifier, e.g. `entities/resolve_entity` → `particle_entity_resolve`. The [tool reference](/mcp/tools/overview) lists all current names.
* **Consolidations** — `search_dialogue` and `list_clips` merged into [`particle_podcast_search_transcripts`](/mcp/tools/podcasts/podcast-search-transcripts): relevant clips now arrive inline on search matches, and a known episode's full clip list comes from `particle_podcast_get_episode` with `include: ["clips"]`. `get_entity_mentions` became [`particle_podcast_find_mentions`](/mcp/tools/podcasts/podcast-find-mentions). Boolean flags on get-tools became `include` arrays.
* **12 new tools** — people profiles and resolution, podcast guests, chart rankings, publishers, listener ratings, and political-bias and brand-suitability analytics. Browse them in the [tool reference](/mcp/tools/overview).
* **Default vs opt-in advertisement** — six tool categories advertise on a bare connection; five more (advertising, publishers, ratings, bias, suitability) advertise when you opt in with `?include=`. Every public tool stays callable by name either way, and the always-on `particle_catalog` / `particle_call` meta-tools let any connection discover and reach the full surface. [Tool sets & discovery](/mcp/tool-sets).

## May 2026

### Launch

* The Particle Pro MCP server ships at `https://mcp.particle.pro`: read-only tools over podcasts, companies, and the knowledge graph, with [OAuth 2.1](/mcp/authentication) and markdown outputs designed for agent loops.
* MCP requests and per-tool usage appear in your organization's request logs alongside REST traffic.

***

Missing something? Email [api@particle.pro](mailto:api@particle.pro).