Skip to main content
Glama

particle-pro

by pro.particle
OverviewDiscussionsAdmin

Particle Podcast List Guests

particle_podcast_list_guests
Read-only

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. For the daily ranked guests chart, with movement since the previous edition and each guest's top clip, use particle_podcast_get_entity_chart with chart="guests".

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. occupation/field (with standing, seniority, practicing, capacity, employer) keep guests by what they know: resolve the words ("doctors", "economists") to codes with particle_expertise_resolve first, and on unresolved_reference resolve and retry rather than dropping the filter. Every row names the guest's occupation codes, standing and seniority; include: ["expertise"] adds their organization.

Guest slugs ARE person slugs — feed them into particle_podcast_get_guest for the appearance profile or particle_person_get for the person profile.

Input Schema

NameRequiredDescriptionDefault
modeNoWhat to return. 'directory' (default): the guest directory ranked by lifetime appearances. 'trends': guests trending right now — appearances on 2+ distinct podcasts in the last 30 days (cross-show press tours, not regulars).
fieldNoOnly guests listed under this ANZSRC 2020 field of research: a code, slug or title from particle_expertise_resolve (e.g. 'banking-finance-and-investment'). Directory mode only.
limitNoGuests per page (1-50, default 20).
cursorNoOpaque pagination cursor from a previous response.
includeNoOptional per-guest sections: 'expertise' (widens the occupation codes, standing and seniority every row carries to the fuller one-line read with the organization). Directory mode only.
capacityNoOnly guests who know their field in this capacity. Directory mode only.
employerNoOnly guests whose organization is this company (slug from particle_company_resolve, or a domain). Directory mode only.
standingNoOnly guests whose standing is recognized this way: 'established' (conferred by others: a credential, a position, recognition in the field), 'self_described', or 'unverified'. Directory mode only.
seniorityNoOnly guests at this seniority or above. Directory mode only.
occupationNoOnly guests listed under this occupation: a SOC 2018 or ISCO-08 code, slug or title from particle_expertise_resolve, or a SOC group or everyday name (e.g. 'cardiologists', '29-1212', 'physicians' or 'doctors'). Directory mode only.
practicingNoOnly guests who still work in the occupation. Needs a SOC 2018 occupation or group (e.g. '29-1212' Cardiologists or 'physicians'). Directory mode only.
topic_slugNoRestrict to guests with appearances on episodes classified under this topic (slug from particle_topic_browse, e.g. 'technology/artificial-intelligence'). Ignored when podcast_slug is set.
podcast_slugNoReturn one show's guest roster instead of the corpus directory: every guest who has appeared on this podcast, ranked by appearances on the show (no lifetime-appearance floor). Slug from particle_podcast_resolve. Only valid with the default directory mode. A particle.pro or Radar show link also works.
output_formatNoOutput serialization. 'markdown' (default) returns the LLM-facing rendering. 'json' returns the structured payload as JSON text — use only for programmatic chaining where exact field extraction matters; the JSON shape is larger and noisier for an LLM to read.
appeared_sinceNoOnly guests with an appearance on or after this date (YYYY-MM-DD or ISO 8601). Directory mode only.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / occupation / description
      Previous value: -"Only guests listed under this occupation: a SOC 2018 or ISCO-08 code, slug or title from particle_expertise_resolve (e.g. 'cardiologists' or '29-1212'). Directory mode only."New value: +"Only guests listed under this occupation: a SOC 2018 or ISCO-08 code, slug or title from particle_expertise_resolve, or a SOC group or everyday name (e.g. 'cardiologists', '29-1212', 'physicians' or 'doctors'). Directory mode only."
    • changedInput schema / properties / practicing / description
      Previous value: -"Only guests who still work in the occupation. Needs a detailed SOC 2018 occupation (e.g. '29-1212' Cardiologists). Directory mode only."New value: +"Only guests who still work in the occupation. Needs a SOC 2018 occupation or group (e.g. '29-1212' Cardiologists or 'physicians'). Directory mode only."
  2. Changed1 schema field changed
    • changedInput schema / properties / include / description
      Previous value: -"Optional per-guest sections: 'expertise' (each guest's standing, seniority, most specific occupation and field, and organization on one line). Directory mode only."New value: +"Optional per-guest sections: 'expertise' (widens the occupation codes, standing and seniority every row carries to the fuller one-line read with the organization). Directory mode only."
  3. Changed9 schema fields changed
    • addedInput schema / properties / appeared_since
      Added value: +{
+  "description": "Only guests with an appearance on or after this date (YYYY-MM-DD or ISO 8601). Directory mode only.",
+  "type": "string"
+}
    • addedInput schema / properties / capacity
      Added value: +{
+  "description": "Only guests who know their field in this capacity. Directory mode only.",
+  "enum": [
+    "researcher",
+    "licensed_professional",
+    "practitioner",
+    "executive_founder",
+    "public_official",
+    "journalist_analyst",
+    "creator_entertainer",
+    "athlete_coach",
+    "clergy",
+    "firsthand",
+    "layperson"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / employer
      Added value: +{
+  "description": "Only guests whose organization is this company (slug from particle_company_resolve, or a domain). Directory mode only.",
+  "type": "string"
+}
    • addedInput schema / properties / field
      Added value: +{
+  "description": "Only guests listed under this ANZSRC 2020 field of research: a code, slug or title from particle_expertise_resolve (e.g. 'banking-finance-and-investment'). Directory mode only.",
+  "type": "string"
+}
    • addedInput schema / properties / include
      Added value: +{
+  "description": "Optional per-guest sections: 'expertise' (each guest's standing, seniority, most specific occupation and field, and organization on one line). Directory mode only.",
+  "items": {
+    "enum": [
+      "expertise"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / occupation
      Added value: +{
+  "description": "Only guests listed under this occupation: a SOC 2018 or ISCO-08 code, slug or title from particle_expertise_resolve (e.g. 'cardiologists' or '29-1212'). Directory mode only.",
+  "type": "string"
+}
    • addedInput schema / properties / practicing
      Added value: +{
+  "description": "Only guests who still work in the occupation. Needs a detailed SOC 2018 occupation (e.g. '29-1212' Cardiologists). Directory mode only.",
+  "type": "boolean"
+}
    • addedInput schema / properties / seniority
      Added value: +{
+  "description": "Only guests at this seniority or above. Directory mode only.",
+  "enum": [
+    "professional",
+    "senior",
+    "distinguished"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / standing
      Added value: +{
+  "description": "Only guests whose standing is recognized this way: 'established' (conferred by others: a credential, a position, recognition in the field), 'self_described', or 'unverified'. Directory mode only.",
+  "enum": [
+    "established",
+    "self_described",
+    "unverified"
+  ],
+  "type": "string"
+}
  4. Changed1 schema field changed
    • changedInput schema / properties / podcast_slug / description
      Previous value: -"Return one show's guest roster instead of the corpus directory: every guest who has appeared on this podcast, ranked by appearances on the show (no lifetime-appearance floor). Slug from particle_podcast_resolve. Only valid with the default directory mode."New value: +"Return one show's guest roster instead of the corpus directory: every guest who has appeared on this podcast, ranked by appearances on the show (no lifetime-appearance floor). Slug from particle_podcast_resolve. Only valid with the default directory mode. A particle.pro or Radar show link also works."
  5. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, non-destructive, open-world), and the description adds substantial behavior beyond them: the 2+ appearance floor, the in-window cross-show enforcement, the 5+ minute speaking-time requirement, mononymous-person exclusion, and the 2x spike rule. It also discloses what each row contains and what `include: ["expertise"]` widens.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the mode distinction, which is the decision an agent needs first, and every sentence carries filter or routing information. It is on the long side and some sentences (the press-tour shape) are dense enough that a skimming agent could miss the enforcement rules, keeping it shy of a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter, zero-required tool with no output schema, the description covers mode semantics, filter interaction, resolution prerequisites, row contents, and downstream slug reuse. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: `podcast_slug` swaps the ranking basis and lifts the lifetime floor, `topic_slug` narrows 'either corpus mode', and expertise filters are gated behind `particle_expertise_resolve` resolution. It does not explain `limit`/`cursor` or `output_format` trade-offs, which are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Browse podcast guests across the catalog') and immediately distinguishes two concrete modes with their ranking rules. It even names the sibling tool to use for the adjacent daily chart use case, so an agent can differentiate without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use for each mode ('directory' for lifetime-ranked directory, 'trends' for cross-show press tours), plus an explicit alternative: use `particle_podcast_get_entity_chart` with `chart="guests"` for the daily ranked chart. It also gives recovery guidance ('on `unresolved_reference` resolve and retry rather than dropping the filter') and downstream routing via `particle_podcast_get_guest` / `particle_person_get`.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All particle-pro toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources