AgentOnAir

Episode details

get_episode

Read-onlyIdempotent

Get one published episode by id: description, duration, listen_url, audio_url, show_url, chapters with links that start playback at each chapter, and optionally the speaker-labeled transcript. Use it after search_catalog or latest_episodes when someone wants to know what an episode covers, jump to a part, or quote it. An unknown or unpublished id returns a tool error.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "episode_id": "<episode_id>"
    },
    "name": "get_episode"
  }
}

Input Schema

Name	Required	Description
`episode_id`	Yes	Episode id from search_catalog or latest_episodes.
`include_transcript`	No	Also return the transcript. Leave off unless you need to quote or summarize it.
`max_transcript_chars`	No	Cut the transcript at this many characters; transcript.truncated says whether it was cut.

Output Schema

Name	Required	Description
`title`	Yes	Episode title.
`chapters`	Yes	Chapters in order; empty when the episode has none.
`duration`	No	Length as m:ss or h:mm:ss.
`show_url`	No	Public page for the episode's show.
`audio_url`	No	Direct MP3 URL, for players or downloads.
`show_name`	No	Show the episode belongs to.
`episode_id`	Yes	Pass to get_episode for chapters and transcript.
`listen_url`	Yes	Public web page that plays the episode in any browser. Give this to a person.
`transcript`	No	Present only when include_transcript is true; null if the episode has no public transcript.
`artwork_url`	No	Episode or show artwork.
`description`	No	Short public summary.
`published_at`	No	ISO 8601 publish time.
`duration_seconds`	No	Length in seconds.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 28, 2026

addedInput schema / properties / include_transcript / description

Added value: +"Also return the transcript. Leave off unless you need to quote or summarize it."

addedInput schema / properties / max_transcript_chars / description

Added value: +"Cut the transcript at this many characters; transcript.truncated says whether it was cut."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "artwork_url": {
+      "description": "Episode or show artwork.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "audio_url": {
+      "description": "Direct MP3 URL, for players or downloads.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "chapters": {
+      "description": "Chapters in order; empty when the episode has none.",
+      "items": {
+        "properties": {
+          "listen_url": {
+            "description": "Listen page that starts playback at this chapter.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "start": {
+            "description": "Chapter start as m:ss or h:mm:ss.",
+            "type": "string"
+          },
+          "start_seconds": {
+            "description": "Chapter start in seconds.",
+            "type": "number"
+          },
+          "title": {
+            "description": "Chapter title.",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "start_seconds",
+          "start"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "description": {
+      "description": "Short public summary.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "duration": {
+      "description": "Length as m:ss or h:mm:ss.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "duration_seconds": {
+      "description": "Length in seconds.",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "episode_id": {
+      "description": "Pass to get_episode for chapters and transcript.",
+      "type": "string"
+    },
+    "listen_url": {
+      "description": "Public web page that plays the episode in any browser. Give this to a person.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "published_at": {
+      "description": "ISO 8601 publish time.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "show_name": {
+      "description": "Show the episode belongs to.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "show_url": {
+      "description": "Public page for the episode's show.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "title": {
+      "description": "Episode title.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "transcript": {
+      "description": "Present only when include_transcript is true; null if the episode has no public transcript.",
+      "properties": {
+        "speaker_count": {
+          "description": "Distinct speakers.",
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "text": {
+          "description": "Transcript as 'Speaker: line' paragraphs.",
+          "type": "string"
+        },
+        "truncated": {
+          "description": "True when text was cut at max_transcript_chars.",
+          "type": "boolean"
+        },
+        "word_count": {
+          "description": "Words in the full transcript.",
+          "type": [
+            "integer",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "text",
+        "truncated"
+      ],
+      "type": [
+        "object",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "episode_id",
+    "title",
+    "listen_url",
+    "chapters"
+  ],
+  "type": "object"
+}

First observedSep 28, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: an unknown or unpublished id produces a tool error, chapters carry deep links that start playback at the chapter, and transcript truncation is surfaced. It does not discuss latency or transcript cost, hence a 4 rather than 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?

Two sentences, front-loaded with the operation and its return fields, then the routing/usage clause. The long field inventory is dense but each item (chapter playback links, speaker labels) informs selection or invocation. Slightly heavy for a read-one tool, so not 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?

An output schema exists, so return values need not be documented, yet the description still orients the agent on what comes back. Combined with the tool-error behavior for bad ids and the truncation flag, an agent has everything needed to call this correctly after a search step.

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 the baseline is 3. The description still adds value by characterizing the transcript as "speaker-labeled" and by framing include_transcript as an intent-driven switch (quote/summarize) rather than a raw flag. It does not explain max_transcript_chars beyond the schema's own truncation note, so it stays just above baseline.

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?

Specific verb+resource ("Get one published episode by id") followed by an explicit enumeration of the payload (description, duration, listen_url, audio_url, show_url, chapters with playback links, optional speaker-labeled transcript). It is plainly distinguishable from siblings like search_catalog and latest_episodes, which are named as the upstream feeders.

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?

Gives an explicit sequencing cue ("Use it after search_catalog or latest_episodes") plus three concrete intents that select this tool: learn what an episode covers, jump to a part, or quote it. It also carries a conditional for the optional param ("Leave off unless you need to quote or summarize it"), so the agent knows when transcript retrieval is warranted.

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

All AgentOnAir tools Inspect

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

Need Help?