Skip to main content
Glama

apple_podcasts_followers

Read-onlyIdempotent

Track Apple Podcasts follower trends over a date range to determine if a show’s following is growing, with per-period values and the change across the window.

Instructions

Follower trend for the show on Apple Podcasts over a date range: one value per period plus the change across the window. Use it for 'is my Apple following growing'. Read the resolvedColumn field in the response before interpreting the numbers: Apple's follower column has been both a running total and a per-period count, and which one you get changes what 'change' means.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "apple_podcasts_followers"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoEnd of the range, YYYY-MM-DD (or YYYY-MM for Monthly). Defaults to 2 days ago, because Apple publishes reports on a lag.
startNoStart of the range, YYYY-MM-DD (or YYYY-MM for Monthly). Defaults to 7 days back for Daily, 7 weeks for Weekly, 6 months for Monthly — each sized to fit the default max_periods of 7.
periodNoReporter period. Daily and Weekly take YYYY-MM-DD dates; Monthly takes YYYY-MM. Weekly dates are Apple's week-ending Sundays.Daily
max_periodsNoHow many periods to fetch, an integer from 1 to 31. Reporter has no range query, so each period is a separate call to Apple and a wide range will hit their throttle. Default 14. Ranges longer than this are truncated to the most recent periods.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.2.1
    • removedInput schema / additionalProperties
      Removed value: -false
    • changedInput schema / properties / max_periods / description
      Previous value: -"How many periods to fetch, cap 31. Reporter has no range query, so each period is a separate call to Apple and a wide range will hit their throttle. Default 14. Ranges longer than this are truncated to the most recent periods."New value: +"How many periods to fetch, an integer from 1 to 31. Reporter has no range query, so each period is a separate call to Apple and a wide range will hit their throttle. Default 14. Ranges longer than this are truncated to the most recent periods."
    • addedInput schema / properties / max_periods / maximum
      Added value: +31
    • addedInput schema / properties / max_periods / minimum
      Added value: +1
  2. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already cover read-only, idempotent, and non-destructive, but the description adds a genuinely important caveat the annotations cannot: Apple's follower column has historically been either a running total or a per-period count, so the agent must read resolvedColumn before interpreting 'change'. That is real behavioral context. Throttling and pagination behavior are disclosed in the schema rather than the description, so it is not a 5.

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?

Three sentences, well ordered: purpose, use case, then the interpretive caveat. The resolvedColumn warning is long but each clause is load-bearing, so nothing is 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?

With no output schema, the description takes on the burden of explaining returns and does so at a high level (one value per period, a change value, a resolvedColumn field to check). Minor gaps remain about other response fields and error behavior, but an agent has enough to invoke and interpret the tool correctly.

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

Parameters3/5

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

Schema coverage is 100% and the parameter descriptions are already rich (defaults, date formats, throttling rationale, truncation behavior), so the schema carries the parameter burden. The description only gestures at 'a date range' and adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

Purpose4/5

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

States a specific resource (Apple Podcasts follower trend) plus output shape: one value per period and the change across the window. It effectively distinguishes itself from apple_podcasts_summary and apple_podcasts_episodes by naming followers and trend explicitly, though it does not call out the siblings by name.

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

Usage Guidelines4/5

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

Gives a concrete trigger question ('is my Apple following growing'), which tells the agent exactly which analyst intent maps here. It stops short of naming the sibling tools to use for other intents, so the routing is clear but not exhaustive.

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