> ## 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.

# Tool reference

> Every tool the Particle Pro MCP server exposes, grouped by exposure category.

The Particle Pro MCP server exposes **32 tools across 13 exposure categories**. Each tool wraps an existing REST handler — the per-tool pages link to the analogous REST endpoint when one exists.

Tools belong to **default** categories (advertised on a bare connection) or **opt-in** categories (advertised only when selected via the `?include=` selector). Either way, every public tool is **callable by name** regardless of what was advertised — see [Tool sets & discovery](/mcp/tool-sets) for the selector mechanics and the always-callable contract.

Most tools advertise `readOnlyHint: true`. The exception is the `alerts` category: [`particle_alert_create`](/mcp/tools/alerts/alert-create) and [`particle_alert_update`](/mcp/tools/alerts/alert-update) mutate your project's alerts, and [`particle_alert_delete`](/mcp/tools/alerts/alert-delete) is a destructive soft delete — these act on the single project your credential is scoped to. Inputs use snake\_case JSON; outputs are a single markdown text block (`content[].text`), and passing `output_format: "json"` swaps that block for the compact JSON form of the same response. Tool names are flat `particle_*` identifiers.

Read this list through two conventions (the server states both in its `initialize` instructions): tools are **lean by default** — `include` arrays and `mode`/`format` switches expand them well beyond their one-line summaries — and **slugs are edges**: any slug one tool returns is a valid input to the others, so resolve a name once, then traverse the graph (company → its people → a person's appearances → that episode's transcript and entities). See [How the tools compose](/mcp/overview#how-the-tools-compose).

## System

Always-on discovery meta-tools — the surface is self-expanding from a bare connection.

<CardGroup cols={2}>
  <Card title="particle_catalog" icon="list-tree" href="/mcp/tools/system/catalog">
    Browse the full tool catalog; with a category, full input schemas.
  </Card>

  <Card title="particle_call" icon="code" href="/mcp/tools/system/call">
    Dispatch any public tool by name (fallback for un-advertised tools).
  </Card>
</CardGroup>

## Podcasts <Tooltip tip="default">default</Tooltip>

Resolve podcasts, list and fetch episodes, search transcripts, and find entity mentions.

<CardGroup cols={2}>
  <Card title="particle_podcast_resolve" icon="podcast" href="/mcp/tools/podcasts/podcast-resolve">
    Find a podcast by title, slug, iTunes ID, or RSS URL; optional hydrations.
  </Card>

  <Card title="particle_podcast_get_episode" icon="play" href="/mcp/tools/podcasts/podcast-get-episode">
    Bundled episode overview — speakers, entities, segments, clips, topics, transcript.
  </Card>

  <Card title="particle_podcast_find_mentions" icon="quote-left" href="/mcp/tools/podcasts/podcast-find-mentions">
    Every dialogue line where a person or company is named.
  </Card>

  <Card title="particle_podcast_search_transcripts" icon="magnifying-glass" href="/mcp/tools/podcasts/podcast-search-transcripts">
    Semantic, keyword, or hybrid search over dialogue, segments, and clips.
  </Card>

  <Card title="particle_podcast_list_episodes" icon="list" href="/mcp/tools/podcasts/podcast-list-episodes">
    Filter-driven episode discovery across the catalog.
  </Card>

  <Card title="particle_podcast_get_episode_timeseries" icon="chart-line" href="/mcp/tools/podcasts/podcast-get-episode-timeseries">
    Time-bucketed episode and mention counts — trend lines per day, week, or month.
  </Card>

  <Card title="particle_podcast_list_clips" icon="scissors" href="/mcp/tools/podcasts/podcast-list-clips">
    Highlight clips ranked by engagement, with per-clip detail and transcript.
  </Card>
</CardGroup>

## People <Tooltip tip="default">default</Tooltip>

Resolve people and entities to canonical handles and fetch person profiles.

<CardGroup cols={2}>
  <Card title="particle_entity_get" icon="diagram-project" href="/mcp/tools/people/entity-get">
    One knowledge-graph entity's profile — confirm what a slug refers to.
  </Card>

  <Card title="particle_entity_resolve" icon="user-magnifying-glass" href="/mcp/tools/people/entity-resolve">
    Union resolver — person, company, place, or other, with a typed handle.
  </Card>

  <Card title="particle_person_resolve" icon="user-magnifying-glass" href="/mcp/tools/people/person-resolve">
    People-only resolver — canonical person slug.
  </Card>

  <Card title="particle_person_get" icon="id-badge" href="/mcp/tools/people/person-get">
    Person profile — role, bio, external links, appearances, role history.
  </Card>
</CardGroup>

## Companies <Tooltip tip="default">default</Tooltip>

Resolve companies and fetch company profiles with people, products, and competitors.

<CardGroup cols={2}>
  <Card title="particle_company_resolve" icon="building-magnifying-glass" href="/mcp/tools/companies/company-resolve">
    Resolve a company by name, ticker, domain, CIK, or QID.
  </Card>

  <Card title="particle_company_get" icon="building" href="/mcp/tools/companies/company-get">
    Bundled company profile — identifiers, people, products, competitors.
  </Card>
</CardGroup>

## Alerts <Tooltip tip="default">default</Tooltip>

Create and manage alerts that watch entities for podcast mentions or speaker appearances, preview match frequency, and review what an alert has caught. The only **writable, project-scoped** category — these act on the single project your credential is bound to.

<CardGroup cols={2}>
  <Card title="particle_alert_create" icon="bell-plus" href="/mcp/tools/alerts/alert-create">
    Create an alert watching entity slugs for mentions or speaker appearances.
  </Card>

  <Card title="particle_alert_list" icon="list" href="/mcp/tools/alerts/alert-list">
    List your project's alerts, newest first, with their ids.
  </Card>

  <Card title="particle_alert_get" icon="magnifying-glass" href="/mcp/tools/alerts/alert-get">
    One alert's full config; optional embedded matches and deliveries.
  </Card>

  <Card title="particle_alert_update" icon="pen" href="/mcp/tools/alerts/alert-update">
    Retitle, change cadence, pause/resume, or replace the watch list.
  </Card>

  <Card title="particle_alert_delete" icon="trash" href="/mcp/tools/alerts/alert-delete">
    Soft-delete an alert; past matches and deliveries are retained.
  </Card>

  <Card title="particle_alert_preview" icon="eye" href="/mcp/tools/alerts/alert-preview">
    Preview how often an alert would fire before creating it.
  </Card>

  <Card title="particle_alert_list_matches" icon="inbox" href="/mcp/tools/alerts/alert-list-matches">
    What an alert caught — episode edges, optional transcript windows.
  </Card>
</CardGroup>

## Topics <Tooltip tip="default">default</Tooltip>

Browse the hierarchical topic taxonomy used to classify podcast episodes.

<CardGroup cols={2}>
  <Card title="particle_topic_browse" icon="folder-tree" href="/mcp/tools/topics/topic-browse">
    Navigate the topic taxonomy — roots and direct children.
  </Card>
</CardGroup>

## Podcast rankings <Tooltip tip="default">default</Tooltip>

Podcast chart rankings: current charts, movers, and ranking history.

<CardGroup cols={2}>
  <Card title="particle_podcast_get_rankings" icon="chart-line" href="/mcp/tools/podcast_rankings/podcast-get-rankings">
    Apple/Spotify charts in three modes — chart, movers, history.
  </Card>
</CardGroup>

## Podcast guests <Tooltip tip="default">default</Tooltip>

Podcast guest directory, trending guests, and per-guest appearance profiles.

<CardGroup cols={2}>
  <Card title="particle_podcast_list_guests" icon="users" href="/mcp/tools/podcast_guests/podcast-list-guests">
    Guest directory (lifetime) or trending guests (last 30 days).
  </Card>

  <Card title="particle_podcast_get_guest" icon="microphone-lines" href="/mcp/tools/podcast_guests/podcast-get-guest">
    A guest's appearance profile, per-podcast rollup, suitability exposure.
  </Card>
</CardGroup>

## Podcast advertising <Tooltip tip="opt-in">opt-in</Tooltip>

Sponsor analytics — per-company, per-podcast, and across the catalog. Add `?include=podcast_advertising` to advertise these on `tools/list`.

<CardGroup cols={2}>
  <Card title="particle_company_get_podcast_ad_presence" icon="bullhorn" href="/mcp/tools/podcast_advertising/company-get-podcast-ad-presence">
    Where company X shows up as a sponsor.
  </Card>

  <Card title="particle_podcast_get_sponsors" icon="handshake" href="/mcp/tools/podcast_advertising/podcast-get-sponsors">
    Who sponsors podcast Y, plus aggregate stats.
  </Card>

  <Card title="particle_podcast_get_sponsor_leaderboard" icon="ranking-star" href="/mcp/tools/podcast_advertising/podcast-get-sponsor-leaderboard">
    Top advertisers across the catalog — and the publishers carrying the most ads.
  </Card>

  <Card title="particle_podcast_get_episode_ads" icon="rectangle-ad" href="/mcp/tools/podcast_advertising/podcast-get-episode-ads">
    Every detected ad read inside one episode, with exact offsets.
  </Card>

  <Card title="particle_podcast_get_ad_trends" icon="arrow-trend-up" href="/mcp/tools/podcast_advertising/podcast-get-ad-trends">
    Sponsors ramping up or pulling back, and one company's ad volume over time.
  </Card>
</CardGroup>

## Podcast publishers <Tooltip tip="opt-in">opt-in</Tooltip>

Publisher profiles with their shows, bias profile, and suitability profile. Add `?include=podcast_publishers`.

<CardGroup cols={2}>
  <Card title="particle_podcast_get_publisher" icon="buildings" href="/mcp/tools/podcast_publishers/podcast-get-publisher">
    A publisher's profile — shows, bias profile, suitability profile.
  </Card>
</CardGroup>

## Podcast ratings <Tooltip tip="opt-in">opt-in</Tooltip>

Listener review ratings for podcasts. Add `?include=podcast_ratings`.

<CardGroup cols={2}>
  <Card title="particle_podcast_get_ratings" icon="star" href="/mcp/tools/podcast_ratings/podcast-get-ratings">
    Aggregate summary, per-platform breakdown, sentiment, recent reviews.
  </Card>
</CardGroup>

## Podcast bias <Tooltip tip="opt-in">opt-in</Tooltip>

Corpus-wide political-bias views. Add `?include=podcast_bias`.

<CardGroup cols={2}>
  <Card title="particle_podcast_get_bias_leaderboard" icon="scale-unbalanced" href="/mcp/tools/podcast_bias/podcast-get-bias-leaderboard">
    Rank publishers by political-bias metrics.
  </Card>

  <Card title="particle_podcast_list_bias_publishers" icon="filter" href="/mcp/tools/podcast_bias/podcast-list-bias-publishers">
    Which publishers have the most podcasts in one bias bucket.
  </Card>
</CardGroup>

## Podcast suitability <Tooltip tip="opt-in">opt-in</Tooltip>

Corpus-wide GARM brand-suitability views. Add `?include=podcast_suitability`.

<CardGroup cols={2}>
  <Card title="particle_podcast_get_suitability_leaderboard" icon="shield-check" href="/mcp/tools/podcast_suitability/podcast-get-suitability-leaderboard">
    Rank publishers by IAB/GARM brand-suitability composition.
  </Card>

  <Card title="particle_podcast_list_suitability_category_publishers" icon="triangle-exclamation" href="/mcp/tools/podcast_suitability/podcast-list-suitability-category-publishers">
    Publishers most (or least) exposed to one GARM category.
  </Card>
</CardGroup>

## Tiers

Every tool carries a billing tier, surfaced in [`particle_catalog`](/mcp/tools/system/catalog):

| Tier         | Tools                                                                                                                                                                                                                                                      |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Free**     | The `system` meta-tools — `particle_catalog`, `particle_call` (the dispatched inner tool meters at its own tier). Discovery never costs anything.                                                                                                          |
| **Standard** | Everything not listed below — all resolvers, `particle_person_get`, `particle_company_get`, `particle_podcast_get_episode`, `particle_podcast_list_episodes`, `particle_topic_browse`, guests, publisher, ratings, and all seven `particle_alert_*` tools. |
| **Premium**  | `particle_podcast_get_rankings`, the five `podcast_advertising` tools, both `podcast_bias` tools, and both `podcast_suitability` tools.                                                                                                                    |

Premium tools require a plan that includes premium endpoints; on plans without them the call returns an `isError` result with code [`premium_required`](/errors/premium_required) and upgrade guidance. See [Errors](/mcp/errors) for how billing failures surface.

## Safety

Almost every tool is read-only (`readOnlyHint: true`) — no read tool mutates your Particle Pro data, spends money beyond metered usage, or acts on external systems. The exception is the `alerts` category: [`particle_alert_create`](/mcp/tools/alerts/alert-create) and [`particle_alert_update`](/mcp/tools/alerts/alert-update) write alerts, and [`particle_alert_delete`](/mcp/tools/alerts/alert-delete) is a destructive soft delete — all confined to the single project your credential is scoped to, with no way to reach another project's alerts. Tool *outputs* also contain third-party content (transcripts, reviews, show notes), so when you combine this server with other MCP servers that **can** take actions, keep your client's human confirmation enabled for those action tools to avoid prompt-injection chains from untrusted content.

<Note>
  Missing a tool you need? Email [api@particle.pro](mailto:api@particle.pro) — the surface grows in the direction people pull it.
</Note>

## Choosing the right tool

| I want…                                                                | Use this                                                                                                             |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| To turn a name into a slug (any kind)                                  | [`particle_entity_resolve`](/mcp/tools/people/entity-resolve)                                                        |
| To turn a person's name into a slug                                    | [`particle_person_resolve`](/mcp/tools/people/person-resolve)                                                        |
| To turn a ticker, domain, or CIK into a company                        | [`particle_company_resolve`](/mcp/tools/companies/company-resolve)                                                   |
| Watch an entity for podcast mentions or speaker appearances            | [`particle_alert_create`](/mcp/tools/alerts/alert-create)                                                            |
| Preview how often an alert would fire before creating it               | [`particle_alert_preview`](/mcp/tools/alerts/alert-preview)                                                          |
| See what an alert caught                                               | [`particle_alert_list_matches`](/mcp/tools/alerts/alert-list-matches)                                                |
| Every line where a person or company is named                          | [`particle_podcast_find_mentions`](/mcp/tools/podcasts/podcast-find-mentions)                                        |
| Dialogue *about* a topic (paraphrase or exact), with overlapping clips | [`particle_podcast_search_transcripts`](/mcp/tools/podcasts/podcast-search-transcripts)                              |
| Episode-level discovery with rich filters                              | [`particle_podcast_list_episodes`](/mcp/tools/podcasts/podcast-list-episodes)                                        |
| A full episode overview (segments, clips, topics, transcript)          | [`particle_podcast_get_episode`](/mcp/tools/podcasts/podcast-get-episode)                                            |
| A podcast's chart movers or history                                    | [`particle_podcast_get_rankings`](/mcp/tools/podcast_rankings/podcast-get-rankings)                                  |
| Who's a frequent or trending podcast guest                             | [`particle_podcast_list_guests`](/mcp/tools/podcast_guests/podcast-list-guests)                                      |
| "Where does company X advertise"                                       | [`particle_company_get_podcast_ad_presence`](/mcp/tools/podcast_advertising/company-get-podcast-ad-presence)         |
| "Who sponsors podcast Y"                                               | [`particle_podcast_get_sponsors`](/mcp/tools/podcast_advertising/podcast-get-sponsors)                               |
| Catalog-wide top advertisers                                           | [`particle_podcast_get_sponsor_leaderboard`](/mcp/tools/podcast_advertising/podcast-get-sponsor-leaderboard)         |
| A publisher's bias / suitability profile                               | [`particle_podcast_get_publisher`](/mcp/tools/podcast_publishers/podcast-get-publisher)                              |
| Which publishers lean hardest left/right                               | [`particle_podcast_get_bias_leaderboard`](/mcp/tools/podcast_bias/podcast-get-bias-leaderboard)                      |
| The safest / riskiest publishers to advertise on                       | [`particle_podcast_get_suitability_leaderboard`](/mcp/tools/podcast_suitability/podcast-get-suitability-leaderboard) |
| To discover or call a tool you haven't seen advertised                 | [`particle_catalog`](/mcp/tools/system/catalog) / [`particle_call`](/mcp/tools/system/call)                          |