Loading ToolBench
MCP server for Vocabit — let an AI assistant build flashcard sets inside a real language-learning app and read back how the learner actually did.
vocabit-mcp demonstrates solid tool design with clear naming, comprehensive parameter schemas, and structured output. All 8 tools follow verb_noun convention (create_, list_, get_, update_, delete_, notify_). Descriptions are detailed (100-300 chars) and explain WHEN to use each tool. Input schemas use Zod with proper type constraints, enums, and minLength/maxLength bounds. Output schemas are documented via structuredContent. However, some parameter descriptions lack actionable constraints (e.g., 'imageUrl' has no format guidance), and error handling relies on generic VocabitApiError wrapping without recovery hints. Tool composition is clean, each tool has one responsibility, and outputs chain well (setId returned by create/list flows into get/update/delete). Security is sound: no secrets in params, server-side injection via config. Pagination is present (limit, offset) with reasonable defaults.
Build a flashcard set and publish it to the learner's Vocabit app. Returns a deep link that opens the set on their device. Prefer one focused topic and 8-15 cards per set — long sets get abandoned. Use the notes field for what you want to check afterwards; the learner never sees it.
Delete a set. The learner's progress on it is not affected — they can still review it in the app, but it will not appear in their list of active sets.
Read back real study results for a set: which cards the learner marked hard (weakCards), which they never reached (untouchedCards), and per-card review counts. This is the feedback half of the loop — read it before writing the next set, and build the follow-up out of weakCards.
Read the full contents of a set — every card, plus the topic and notes you attached when you created it.
List the sets you created for this learner, newest first, each with a progress summary. Use it to find a setId, or to see at a glance which sets were never opened.
update_study_set has mutually exclusive parameters (cards vs addCards) but no explicit validation or error guidance. LLMs may pass both, causing silent failure or ambiguous API behavior.
Error handling returns generic VocabitApiError with hint text, but hints are not visible in source. No recovery guidance for common failures (auth, rate limit, network timeout). LLMs cannot self-correct.
imageUrl parameter in create_study_set lacks format constraint (URL pattern, max length guidance). LLMs may pass invalid URLs without validation.
notify_learner requires VOCABIT_TELEGRAM_ID env var but tool description does not warn what happens if unset. LLMs will call it expecting success and get cryptic failure.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 63 | 2025-06-18+ | v2 |
Send the learner a Telegram message that a set is ready. Requires VOCABIT_TELEGRAM_ID to be set on the server.
Change a set in place: retitle it, retag it, or add cards. Pass addCards to append (the usual case after reviewing results) or cards to replace the list wholesale — never both. Replacing the cards resets what the learner has already studied.
Verify the server can reach Vocabit and report which mode it is in (live backend or in-memory demo). Call this first if anything else fails.
list_study_sets returns sets array but no documented structure for each set object. LLMs cannot predict which fields are available (e.g., does each set include progress summary or only if includeProgress=true?).