FastMCP server exposing podcast retrieval as three typed tools with ranked, timestamped, cited passages
Three well-named, read-only tools with complete input schemas and clear descriptions. search_podcast has excellent parameter documentation (query, k with range 1-20, mode with enum). list_episodes and episode_detail are simpler but properly defined. Output schemas are documented in descriptions. No security issues (read-only, no secrets). Main gaps: no error handling guidance (e.g., what if episode_id doesn't exist?), no pagination support for search_podcast results, and descriptions could be more concise (search_podcast is 380+ chars, exceeds 200-char LLM-optimized baseline). Tool composition is sound, each does one thing. Per-tool scores: search_podcast 75, list_episodes 70, episode_detail 70.
Return one episode's chunks in timestamp order. Args: episode_id: The episode id, e.g. 'ep02'.
List every episode in the archive with its chunk count.
Search the podcast archive and return ranked, cited passages. Args: query: A natural-language question or phrase. k: How many passages to return (1-20). mode: One of 'bm25_raw', 'bm25_stem', 'dense', 'hybrid'. Default hybrid. Returns a dict with the query, the mode used, and a list of results. Each result carries its chunk id, episode, timestamp, source layer (notes vs transcript), a citation tag, the passage text, and the retrieval score.
search_podcast lacks error handling guidance. Code returns error dict for invalid mode (silently defaults to 'hybrid') but does not document what happens if query is empty or k is out of range. LLM cannot infer recovery steps.
episode_detail returns bare error dict on unknown episode_id ('error': 'unknown episode_id: ...') without suggesting available episodes. LLM has no path to self-correct.
search_podcast description is 380+ characters, exceeding LLM-optimized baseline of 50-200 chars. Verbose docstring wastes tokens and buries key details.
search_podcast returns unbounded result list. No pagination (limit/offset/cursor) or cap documented. If k=20 and each result is ~200 tokens, response could exceed 4K tokens for a single call.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 62 | 2026-07-28+ | v2 |
list_episodes and episode_detail lack explicit output schema documentation in code. Descriptions mention structure but no formal schema block. Harder for LLM to plan downstream calls.