The server exposes 5 Mochi API tools with complete input schemas and basic descriptions. Tool naming follows verb-noun conventions (list_decks, create_card, get_card, update_card, delete_card), which is solid. However, descriptions are minimal (1-2 sentences, mostly around 50-70 chars), parameter descriptions are largely missing from docstrings, output schemas are undocumented (tools return unstructured string responses rather than typed objects), and error handling is generic ('Error creating card: ...' with no recovery guidance). The parameter annotations visible in the schema itself are good (e.g., deck_id has description 'The ID of the deck to add the card to'), but docstrings lack any parameter documentation. All tools return plain strings, forcing LLMs to parse unstructured output. No output schema is declared. Error responses do not guide the agent on retryability or next steps.

• Convert all tool return values to structured JSON responses. E.g., mochi_list_decks should return {"decks": [{"id": "d1", "name": "French", "card_count": 120}, ...], "bookmark": "...", "has_more": true}. This enables reliable field extraction and downstream tool chaining.
• Expand tool descriptions to 150-250 characters, explicitly covering: WHAT the tool does, WHEN to use it (vs similar tools), and WHAT it returns. E.g., 'List all decks in your Mochi account. Call this first to discover available decks before creating or updating cards. Returns deck ID, name, and card count for each deck, with pagination support via bookmark.'
• Add parameter descriptions to all Python docstrings, mirroring the schema descriptions. Use the format: 'Args:\n deck_id: The ID of the deck to add the card to (string, required)\n content: Markdown-formatted card content; supports bold, italics, links, and code blocks (string, required)'
• Implement error categorization. Return error responses in a structured format: {"error": {"message": "...", "code": "INVALID_DECK_ID", "retryable": false, "recovery": "Try list_decks() to see valid deck IDs"}}. Guide the LLM on next steps for each error class.
• Add result limits and pagination guidance. Update mochi_list_decks description: 'Returns up to 50 decks per request. Use the bookmark parameter to fetch the next page if has_more is true. Typical accounts have 3-20 decks.'
• For mochi_delete_card, implement a confirmation pattern: add a dry_run=false parameter and return a success message only after explicit confirmation. Or split into delete_card_draft and delete_card_confirmed, where draft returns a confirmation token and confirmed requires that token.