Tool sets & discovery

How Particle tools are grouped into exposure categories, how the include/exclude selectors shape your tools/list, and why every public tool stays callable by name.

At the standard https://mcp.particle.pro endpoint, every Particle MCP tool belongs to exactly one exposure category. Categories are the unit of tools/list advertisement: some advertise on a bare connection (default), others only when you ask for them (opt-in). But the advertisement is just a menu — every public tool is always callable by name, no matter what was advertised. Discovery is free; execution is metered and plan-gated.

Fixed surface for plugin packages

https://mcp.particle.pro/plugins uses a fixed set of 36 individually exposed operations for plugin packages. It exposes research, Radar cards, existing alert reads and historical previews, and alert deletion. particle_alert_create, particle_alert_update, particle_call, and particle_catalog are unavailable on this connection. Newly added standard-endpoint tools do not join it automatically.

The same fixed list applies to anonymous discovery and authenticated calls. Query and header selectors are ignored: they cannot add or hide tools. Read each exposed input schema through tools/list, then call the named operation directly. Tool calls require an existing eligible account outside its convertible credit/trial phase. Existing authentication scopes, plan gates, usage prices, previously enabled overage, and safety annotations still apply. Per-request payment credentials are rejected; this connection cannot start subscriptions, buy add-ons, or create or resume alerts. Metered account usage can still incur charges.

This connection shares the existing OAuth resource https://mcp.particle.pro; keep that resource value when changing a package’s server URL. The canonical API-host endpoint is https://api.particle.pro/mcp/plugins. A trailing slash is accepted. Configure a package at this URL only after the corresponding server release is deployed.

Plugin discovery uses compact instructions and descriptions to fit clients that limit tool metadata. The 36 tool names, input constraints, and safety annotations are unchanged.

Speaker expertise is on the standard endpoint only, for the same metadata budget. particle_expertise_resolve, particle_expertise_get and particle_podcast_get_share_of_voice are not among the 36 operations. The expertise filters are not advertised in the plugin input schemas: the guest_ filters on particle_podcast_find_mentions, particle_podcast_list_episodes, particle_podcast_search_transcripts and particle_podcast_get_episode_timeseries; guest_occupation, guest_field and the guest-share bounds on particle_podcast_resolve; and the directory filters and include on particle_podcast_list_guests. The expertise include values on particle_person_get (expertise), particle_podcast_get_guest (in_field_appearances), particle_podcast_get_episode and particle_podcast_resolve (guest_expertise) are advertised. Use the bundled Particle skill for workflow guidance. Clients can impose additional exposure limits; after deployment, refresh discovery and check that the research and Radar tools are callable.

SAFE podcast content

This connection enforces the existing SAFE show assessment for podcast discovery and content reads. Resolve and related-show searches use SAFE regardless of an omitted, empty, or different suitability_tier. Direct show, episode, and clip identifiers do not bypass the policy. Unassessed shows and shows with any other tier are excluded. If a direct content target is excluded, you receive content_not_safe; if its assessment cannot be verified, you receive content_suitability_unavailable.

The policy covers episode detail, transcripts in every format, mention dialogue, search excerpts, clips and their audio links, episode ad reads, and related episodes. Related-show expansions are checked independently. Lists can contain fewer results after filtering, including an empty page with has_more=true. Use the returned cursor to continue; an empty page does not mean the remaining pages contain no SAFE results.

Guest and person analytics, publisher and advertising aggregates, recommendation includes, rankings, ratings, and alert previews retain their existing scope. Their totals are not SAFE-only totals, and their show or episode references can identify excluded content. Following those references into a content tool applies the SAFE check. Detailed alert history omits transcript windows from excluded shows, while retaining match summaries and counts. Company ad presence retains totals and placements but filters its optional ad-read segment summaries.

SAFE is a show-level advertiser-risk assessment over sampled episodes, not a guarantee about every episode or passage or certification of suitability for under-18 users. Profile text, listener reviews, historical summaries, recommendations, and caller-authored Radar cards are not individually classified by this policy. Standard MCP and REST retain their existing optional filtering behavior.

The standard endpoint remains available with its existing selectors and full public registry. The fixed surface applies to requests made through the plugin connection; it does not revoke tools from other connections. The category and selector behavior below describes the standard endpoint.

Categories

Category	Exposure	Summary
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.
alerts	default	Create and manage alerts that watch entities for podcast mentions or speaker appearances, preview match frequency, and review the matches an alert has caught.
podcast_advertising	opt-in	Podcast advertising intelligence: sponsor rosters, ad presence, and sponsor leaderboards.
podcast_publishers	opt-in	Podcast publisher profiles with their shows, bias profile, and suitability profile.
podcast_ratings	opt-in	Listener review ratings for podcasts: summaries and recent rating lists.
podcast_bias	opt-in	Corpus-wide political-bias views: publisher leaderboards and publishers by bias result.
podcast_suitability	opt-in	Corpus-wide GARM brand-suitability views: publisher leaderboards and category exposure.
radar	opt-in	Present selected research results as embedded cards, with a complete Markdown fallback. Rendering is free.

A bare connection advertises system plus every default category. The six opt-in categories advertise only when selected.

Selecting categories

The selector lives on the connection — it shapes what tools/list advertises, nothing else.

Query parameters

For embedded result cards, add ?include=radar. The free particle_radar_render_cards tool presents data you already retrieved. Its static UI resource is readable regardless of the tool selector; clients without UI support receive the same selected evidence as Markdown.

Append ?include= (and/or ?exclude=) to the connection URL. Values are comma-separated category names, case-insensitive.

# Advertise the opt-in advertising + bias categories on top of the defaults.
https://mcp.particle.pro?include=podcast_advertising,podcast_bias

# Advertise everything.
https://mcp.particle.pro?include=all

# Hide a default category you don't want cluttering the list.
https://mcp.particle.pro?exclude=podcast_rankings

# Combine: add an opt-in category, drop a default one.
https://mcp.particle.pro?include=podcast_ratings&exclude=topics

• include=all selects every declared category.
• The active set is computed as defaults ∪ include − exclude.
• Unknown tokens are ignored — a typo in a selector never errors tools/list; you just see the default surface for that token.
• system is irremovable — exclude=system is silently ignored, so the discovery meta-tools never disappear.

Headers

Clients that can’t append query strings can send the same values as headers:

X-Particle-Include: podcast_advertising,podcast_bias
X-Particle-Exclude: podcast_rankings

The query parameter wins when both are present (query > header precedence), resolved independently for each direction (include and exclude).

Selecting exact tools

When a category is still too broad — a curated workflow that needs exactly four tools, say — the ?tools= selector pins tools/list to a comma-separated list of tool names:

# Advertise exactly these tools (plus the always-on system meta-tools).
https://mcp.particle.pro?tools=particle_podcast_resolve,particle_podcast_search_transcripts,particle_podcast_get_episode

• A non-empty ?tools= selection overrides include/exclude entirely.
• Named tools advertise regardless of category exposure — an opt-in tool named here shows up without its category.
• The system meta-tools are always advertised alongside the selection, so discovery never disappears.
• Unknown names are ignored; if every name is unknown, the selection is empty and the connection falls back to the category selectors above (defaults ∪ include − exclude).
• Same header fallback (X-Particle-Tools) and query-over-header precedence as the category selectors.
• And the same contract: this shapes advertisement only — every public tool stays callable by name.

This is the mechanism behind the pre-built skill bundles: each skill embeds a ?tools= URL so the agent sees only the tools its workflow needs.

Every public tool is callable by name

The selector only governs the menu (tools/list). tools/call is selector-independent: every public tool stays executable by name whether or not it was advertised on your connection.

That separation is deliberate:

• Discovery is free. A bare connection can learn the entire surface via particle_catalog and call any of it — no reconnection, no selector change.
• Execution is metered and plan-gated. Calling a tool runs the same billing meter, pricing gate, and premium-tier gate regardless of how you reached it. Advertisement changes visibility, never entitlement.

So the opt-in categories exist to keep a default agent’s tool list focused, not to lock anything away. If your harness lets you call tools it didn’t see advertised, just call them. If it doesn’t, use the meta-tools below.

Meta-tools

Two always-on system tools make the surface self-expanding.

particle_catalog

Browse the full catalog. No arguments → the category menu; with a category → full input schemas for that category’s tools.

particle_call

Dispatch any public tool by name — the fallback for harnesses that block un-advertised tool names.

particle_catalog

# See every category and its tools.
particle_catalog {}

# Get the full input schema for an opt-in category before calling it.
particle_catalog { "category": "podcast_bias" }

particle_call

# Reach an opt-in tool when the harness blocks un-advertised tool_use names.
particle_call {
  "tool": "particle_podcast_get_bias_leaderboard",
  "arguments": { "metric": "most_right_leaning", "limit": 10 }
}

Identical metering and plan gating apply whether you call a tool directly or through particle_call.

Next steps

Tool reference

Every tool, grouped by category, with inputs and outputs.

Quickstart

Connect a client and run a first call.