Skip to main content
Glama

particle-pro

by pro.particle
OverviewDiscussionsAdmin

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, debuts, exits).

  • history: past snapshots for a chart slot, or — with podcast_slug — one podcast's chart history over time.

  • 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

TableJSON 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.
cursorNoOpaque pagination cursor from a previous response. Not supported by mode=movers.
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.
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. First observed

TDQS

A4.7/5.0
Behavior5/5

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

The readOnlyHint annotation is consistent with the description, and the description adds substantial behavior beyond the annotation: slots mode ignores other filters, cursor is unsupported in movers mode, since/until apply only to history, and returned rows carry podcast_slug for chaining into other tools. It also discloses the markdown-vs-json output_format tradeoff.

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?

The description is long but well-structured with bulleted modes and a clear closing paragraph, which is appropriate for a complex 12-parameter tool. It loses a point because the mode bullets partially restate the mode parameter's schema description, but there is no fluff or irrelevant detail.

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?

For a tool with no output schema, the description covers mode interactions, parameter constraints, filter discovery, podcast_slug chaining, and output-format behavior—strong coverage for a read-only tool. The main gap is that the full return row shape beyond podcast_slug is left implicit, which an output schema or a clarifying sentence would close.

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 description coverage is 100%, so all 12 parameters are already individually documented. The description adds valuable cross-parameter semantics, such as how podcast_slug alters chart/history behavior, which parameters are mode-specific, and how source narrows country/category listings in slots mode.

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?

The description opens with a clear resource ('Podcast chart rankings from Apple Podcasts and Spotify') and immediately enumerates the four modes, making the tool's function unmistakable. It also differentiates itself from sibling podcast tools by explicitly routing single-podcast chart lookups to particle_podcast_resolve.

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?

It gives concrete when-to-use and when-not-to-use guidance: for at-a-glance chart presence, use particle_podcast_resolve with include:['rankings'] instead of this tool. It also instructs the agent to use slots mode first to discover valid filter values rather than guessing them.

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