Kick off transcription on an episode ALREADY in the library. Use only when the episode row exists and transcription_status is not "completed". Inherits the episode's existing show, artwork, and feed linkage automatically — no need to pass podcast context. For audio not yet in the library, use transcribe_url. COSTS 1 CREDIT (or subscription quota).
| Name | Required | Description | Default |
|---|---|---|---|
| episode_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses a key behavioral trait: 'COSTS 1 CREDIT (or subscription quota).' It also explains automatic inheritance of show, artwork, and feed linkage, which is useful context. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the core purpose. Each sentence adds value, though the inheritance explanation could be slightly more compact. Overall it is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and no output schema, the description covers all necessary invoking context: prerequisites, exclusions, alternatives, cost, and automatic linkage. It is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 0%, the description compensates by clarifying that the episode_id must refer to an episode already in the library, and that no podcast context is needed. The schema already provides the format (uuid), so the meaning and constraints are sufficiently clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Kick off transcription on an episode ALREADY in the library.' It highlights that the episode must already exist and distinguishes this tool from transcribe_url and transcribe_feed, which are for audio not yet in the library.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage conditions are provided: 'Use only when the episode row exists and transcription_status is not "completed".' It also names the alternative for audio not in the library: 'For audio not yet in the library, use transcribe_url.' This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Tools are largely distinct, covering separate actions (search, get, list, generate, transcribe, save). The main potential confusion is between list_episodes and list_feed_episodes, but descriptions clearly separate local from external.
All tools follow consistent verb_noun snake_case patterns (get_, list_, search_, generate_, transcribe_, save/remove), with no mixed conventions or unexpected styles.
25 tools is at the high end for a server of this scope. The broad domain justifies many functions, but the count feels heavy and some tools could be consolidated without losing clarity.
Discovery, ingestion, transcription, lesson generation, and user account management are all well covered. Minor gaps exist, such as no way to delete or update lessons beyond save/remove.