Skip to main content
Glama

Spoken

by io.github.spokenmd
OverviewDiscussionsAdmin

List a show's episodes

list_episodes
Read-onlyIdempotent

List a podcast's entire back-catalog (every episode, newest first). Pass a podcast_id from a search_podcasts result. Returns each episode's id, title, and date — fetch any with get_transcript. Use this to transcribe a whole show. Does not consume credits itself; transcribing the returned episodes costs 1 credit each (repeat fetches are free), so make sure the key has enough credits before looping.

Input Schema

NameRequiredDescriptionDefault
podcast_idYesShow id (the podcast_id field from a search_podcasts result).

Output Schema

NameRequiredDescriptionDefault
countYesEpisodes listed; fetching all of them costs up to this many credits.
podcastYesShow name.
episodesYes
podcast_idYesShow id; pass it to list_episodes or follow_podcast.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "count": {
+      "description": "Episodes listed; fetching all of them costs up to this many credits.",
+      "type": "number"
+    },
+    "episodes": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "date": {
+            "description": "Release date, ISO 8601.",
+            "type": "string"
+          },
+          "id": {
+            "description": "Episode id; pass it to get_transcript.",
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "date"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "podcast": {
+      "description": "Show name.",
+      "type": "string"
+    },
+    "podcast_id": {
+      "description": "Show id; pass it to list_episodes or follow_podcast.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "podcast_id",
+    "podcast",
+    "count",
+    "episodes"
+  ],
+  "type": "object"
+}
  2. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), but the description adds behavior none of them express: it consumes no credits itself, transcribing returned episodes costs 1 credit each, repeat fetches are free, and the agent should verify the key has enough credits before looping. This credit/cost disclosure is genuinely load-bearing context.

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-loads what the tool returns and its ordering, then appends the credit caveat. Four sentences all carry weight, though the credit-warning clause is slightly verbose relative to the rest.

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?

With an output schema present, return values need not be enumerated, yet the description still summarizes them (id, title, date). For a single-param read tool it supplies the upstream source, downstream consumer, and cost model — everything needed to call it 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 description coverage is 100% and the single podcast_id parameter is already documented as 'the podcast_id field from a search_podcasts result'. The description repeats this provenance without adding format, validation, or edge-case detail beyond 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 and resource ('List a podcast's entire back-catalog') with scope and ordering ('every episode, newest first'), which cleanly distinguishes it from the sibling list_new_episodes. An agent can identify it without opening the schema.

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?

Explicitly routes the agent: pass a podcast_id from a search_podcasts result, and fetch episodes with get_transcript to 'transcribe a whole show'. It names the upstream and downstream tools but never states the inverse condition (e.g. when to prefer list_new_episodes over this back-catalog listing), so it stops short of full when/when-not guidance.

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

All Spoken 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