Spoken MCP demonstrates solid fundamentals: all 4 tools have clear verb-noun names (search_podcasts, get_transcript, list_episodes, get_balance), descriptions of 150-250 chars (within baseline 194 avg), and explicit input schemas with Zod validation. Error handling is notably strong, describeError() provides context-aware recovery guidance (e.g., 'No SPOKEN_API_KEY is set, so this server is using the free pt_demo key'). However, output schemas are undocumented in the tool registration, responses are returned as TextResult with unstructured text content, not structured objects. Parameter descriptions are present but minimal (e.g., 'Episode id returned by search_podcasts' lacks format/constraint details). No tool annotations (readOnlyHint, idempotentHint) despite all tools being read-only. Missing pagination guidance for list_episodes despite potential for large result sets.

• Document output schemas for each tool. Define structured return types (e.g., SearchResult with fields id, title, podcast, podcast_id, date) instead of unstructured text. Enable LLM to extract and chain results.
• Add readOnlyHint and idempotentHint annotations to all 4 tools in registerTool() calls. Agents need explicit safety signals to plan retries and concurrent execution.
• Enhance parameter descriptions with format/constraint details: 'Episode id (alphanumeric, 1-50 chars, returned by search_podcasts)' instead of bare 'Episode id returned by search_podcasts.'
• Add pagination to list_episodes: accept optional limit (default 20, max 100) and offset parameters. Document that large catalogs may require multiple calls. Return total_count and has_more in response.
• Return structured JSON objects instead of TextResult text. E.g., search_podcasts returns {results: [{id, title, podcast, podcast_id, date}], count: N} instead of formatted text lines.