> ## 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 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.
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.
## 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. |
A bare connection advertises **`system` plus every default category**. The five 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
Append `?include=` (and/or `?exclude=`) to the connection URL. Values are **comma-separated** category names, case-insensitive.
```bash theme={"dark"}
# 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:
```bash theme={"dark"}
# 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](/mcp/skills): 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`](/mcp/tools/system/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.
Browse the full catalog. No arguments → the category menu; with a `category` → full input schemas for that category's tools.
Dispatch any public tool by name — the fallback for harnesses that block un-advertised tool names.
### `particle_catalog`
```text theme={"dark"}
# 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`
```text theme={"dark"}
# 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
Every tool, grouped by category, with inputs and outputs.
Connect a client and run a first call.