Skip to main content
Glama
Sign In

particle-pro

by pro.particle
OverviewDiscussionsAdmin

Particle Podcast Get Rankings

particle_podcast_get_rankings
Read-only

Podcast chart rankings from Apple Podcasts and Spotify, in four modes:

  • chart (default): the current chart for a source/country/category slot, or — with podcast_slug — every chart slot that podcast currently holds.

  • movers: the biggest rank changes over window_days (risers, fallers, entries, exits). Most change=new entries are established shows returning to the chart; for new podcasts, launches, or debuts use change=debut — shows on that chart slot for the first time since tracking began (May 2026). A debut is per slot: a show can debut on the overall chart after months in a category, so read its episode count and, when shown, its first-episode date before calling it brand-new.

  • history: past snapshots for a chart slot, or — with podcast_slug — one podcast's chart history over time, newest first. Per-podcast history defaults to country=us; pass country for other markets. For one chart's trajectory pass source, country, and category_slug too (omit category_slug for the overall chart plus every category): 90 days of one slot fits in one page of 100, where the unfiltered history of a popular show runs to hundreds of rows. History begins in May 2026.

  • slots: the valid slot values — every source, country, and category_slug with live chart data — so filter values are discovered, not guessed. source narrows the country/category listings; other filters are ignored.

Each row carries the matched podcast_slug when the chart entry is in the catalog — feed it into particle_podcast_resolve or any podcast tool. For a single podcast's at-a-glance chart presence, particle_podcast_resolve with include: ["rankings"] is one call instead of two.

Input Schema

NameRequiredDescriptionDefault
modeNoWhat to return. 'chart' (default): the current chart — or, with podcast_slug, every chart slot the podcast currently holds. 'movers': biggest rank changes over window_days (risers, fallers, debuts, exits). 'history': past chart snapshots for a slot — or, with podcast_slug, one podcast's chart history. 'slots': the valid chart-slot values — every source, country, and category_slug with live data — for discovering filter values before a chart/movers/history call.
limitNoRows per page (1-100, default 25).
sinceNoMode=history only: only snapshots captured on or after this ISO 8601 timestamp.
untilNoMode=history only: only snapshots captured on or before this ISO 8601 timestamp.
changeNoMode=movers only: filter by change type. Defaults to all. 'debut': shows on this chart slot for the first time since tracking began (May 2026) — use it for 'new podcasts', 'just launched', 'debuted'. 'new': every entry, mostly established shows returning. 'reentry': only the returning ones.
cursorNoOpaque pagination cursor from a previous response.
sourceNoRanking source platform. Defaults to apple.
countryNoISO 3166-1 alpha-2 country code (e.g. 'us', 'gb', 'jp'). Defaults to us.
window_daysNoMode=movers only: comparison window in days (1-30, default 1 = vs. yesterday).
podcast_slugNoPodcast slug, internal ID, or numeric iTunes ID. With mode=chart: that podcast's current chart appearances across every slot. With mode=history: that podcast's chart history. A particle.pro or Radar show link also works.
category_slugNoCategory slug (e.g. 'comedy', 'business'). Omit for the overall chart.
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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / change / description
      Previous value: -"Mode=movers only: filter by change type. Defaults to all."New value: +"Mode=movers only: filter by change type. Defaults to all. 'debut': shows on this chart slot for the first time since tracking began (May 2026) — use it for 'new podcasts', 'just launched', 'debuted'. 'new': every entry, mostly established shows returning. 'reentry': only the returning ones."
    • changedInput schema / properties / change / enum
      Previous value: -[
-  "all",
-  "up",
-  "down",
-  "new",
-  "exit"
-]New value: +[
+  "all",
+  "up",
+  "down",
+  "new",
+  "debut",
+  "reentry",
+  "exit"
+]
  2. Changed1 schema field changed
    • changedInput schema / properties / cursor / description
      Previous value: -"Opaque pagination cursor from a previous response. Not supported by mode=movers."New value: +"Opaque pagination cursor from a previous response."
  3. Changed1 schema field changed
    • changedInput schema / properties / podcast_slug / description
      Previous value: -"Podcast slug, internal ID, or numeric iTunes ID. With mode=chart: that podcast's current chart appearances across every slot. With mode=history: that podcast's chart history."New value: +"Podcast slug, internal ID, or numeric iTunes ID. With mode=chart: that podcast's current chart appearances across every slot. With mode=history: that podcast's chart history. A particle.pro or Radar show link also works."
  4. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnly=true and destructive=false, yet the description still adds substantial behavior: tracking begins May 2026, per-podcast history silently defaults to country=us, category_slug omission means 'overall chart plus every category', slots ignores other filters, and 90 days of one slot fits in a single 100-row page. The per-slot caveat on debuts ('read its episode count and, when shown, its first-episode date before calling it brand-new') is exactly the kind of semantic trap an agent would otherwise fall into.

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 a mode list before any detail, and the bulleted structure maps one bullet per mode, which is easy to scan. It is long and some clauses (the debut episode-count aside, the page-of-100 justification) are dense, but each carries a real disambiguation an agent needs, so little is truly wasted.

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

Completeness4/5

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

Covers mode selection, defaults, historical boundaries, pagination behavior, and one row-level fact (matched podcast_slug fed into other tools) despite having no output schema and 12 parameters. The return shape is still only partly described — rank fields, whether movers rows show deltas, and exit rows' contents are left implicit — which keeps it short of fully self-contained.

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 mode, change, source, country, category_slug and output_format are already documented and repetition earns no credit. The description does go beyond the schema on cross-parameter interactions — that history needs source+country+category_slug to describe one slot's trajectory, that source narrows but other filters are ignored in slots mode — which is genuine value. Remaining parameters (since/until/cursor/limit) get no extra semantics in the prose.

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?

Names a specific verb and resource and then splits it into four named modes with distinct returned content, so an agent can tell chart from movers from history from slots without opening the schema. It also distinguishes itself from the sibling particle_podcast_resolve by noting that the at-a-glance case is one call there instead of two here.

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 routing for every mode: slots exists to discover filter values 'not guessed'; history should be pinned to source/country/category_slug because unfiltered history of a popular show runs hundreds of rows; change=debut is prescribed for 'new podcasts/launches' while change=new is warned as mostly returning shows. It also names the alternative tool for the single-podcast case.

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