The LingoChunk MCP server connects a coding agent to your LingoChunk account, enabling it to act as a personalized language tutor grounded in your personal listening and learning history.
Access Personal Learning Data
Browse vocabulary – List your words with FSRS maturity states (known/learning/new/due), filterable by language, status, or CEFR level, with incremental sync support.
Look up words – Get detailed context (translation, gender, CEFR, FSRS state) for a specific word, with fallback to a shared lexicon.
List episode library – Browse ready-to-study episodes from your own submissions and followed collections, with cursor pagination.
Fetch transcripts – Get timestamped sentences with translations for any episode, sliceable by sentence position or time range.
Search examples – Find example sentences across your library by lemma or text substring.
Manage Audio
Get audio URLs – Retrieve short-lived presigned URLs for full native episode audio (supports HTTP Range for streaming).
Download audio clips – Cut and save native-audio snippets (up to 60s) to a local file, suitable for embedding in lessons.
Create & Manage Learning Materials
List decks – View all study decks with card counts (total/new/due) to select a target for card additions or exports.
Add flashcards – Insert vocabulary or custom front/back cards into your FSRS review queue.
Export Anki decks – Export a deck as an Anki .apkg file, with built-in polling; returns a download URL when ready.
Save lessons – Store a self-contained HTML lesson (up to 10 MB) in your private LingoChunk library with a short-lived view URL.
AI-Driven Workflows (via skills)
lingochunk-lesson – Build comprehensive HTML lessons with exercise types like gap-fill, multiple-choice, listening, and blur-reveal.
lingochunk-discuss – Engage in conversational discussions about episodes.
Allows exporting Anki decks from LingoChunk vocabulary and adding review cards.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@LingoChunk MCP look up 'perro' in my vocabulary"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server (and Claude Code plugin) that turns a coding agent into a language tutor grounded in your own LingoChunk listening history: your FSRS-graded vocabulary, native-audio transcripts and clips, and your library.
It is a thin client over the LingoChunk public API (/api/v1): read-only tools
for your vocabulary, transcripts and audio, plus write tools to add review cards,
export Anki decks and save lessons. The app stays closed source; this repo is
the client, the committed API spec, and the skills - and the skills are open to
contributions (see CONTRIBUTING.md).
Install:
/plugin marketplace add lingochunk/lingochunk-mcpin Claude Code (server plus lesson skills), ornpx -y @lingochunk/mcpas a standalone MCP server.
A creator rather than a coder? If you make audio (a podcast, a YouTube channel, classes) and want your episodes to become annotated transcripts, lessons, courses and multi-language study guides your audience can use, start with LingoChunk for creators - no programming required, everything happens by talking to an AI assistant.
Forty tools. Nineteen read from your account; nineteen write to it; two serve
guidance: whats_possible answers "what can I do here?" with a short menu
and an example prompt per area, and get_authoring_guide serves the full
authoring craft guides so remote clients that never see the skills still
compose good lessons, cards and annotations.
Tool | Scope | What it does |
| none | The quick tour: every area this connection covers (discuss, vocabulary, lessons, courses, cards, languages, creator notes, publishing), one example prompt each. The agent answers short and offers to go deeper per area. |
|
| Your vocabulary, aggregated per word with FSRS maturity (known/learning/new/due). Filterable; incremental sync via |
|
| One word: your own context plus a shared-lexicon gender/CEFR fallback. Grounds an LLM's guesses. |
|
| Your ready-to-study episodes (own + followed collections), cursor-paginated. |
|
| A submission's timestamped sentences + translations, sliceable by sentence or time range. |
|
| A short-lived presigned URL to the full native audio (Range-capable). |
|
| Example sentences across your library, by word ( |
|
| Cuts a short native-audio snippet, saves it to a local file, and returns |
| none | Returns the full craft guide for |
|
| Your study decks with card counts, for picking a |
|
| Adds a card to your review queue (FSRS, starts new). Preferred: the |
|
| Exports a deck to Anki |
|
| Dry-run validates a |
|
| Saves a lesson to your private library (100 max). Preferred: a structured |
|
| Your saved lessons, newest first (id, title, language, format, source episode, and |
|
| Reads back a saved |
|
| Revises a saved |
|
| Permanently deletes one saved lesson by id (destructive; owner-scoped server-side). For lessons the user is done with - revision is |
|
| Creates a course: a named, ordered series to file lessons under. Returns its id, for |
|
| Your courses, newest first, each with its lesson count - for finding a |
|
| Deletes one course by id (destructive to the grouping, idempotent). Its lessons SURVIVE - their |
|
| An episode's target languages and how to add more: the fan-out group so far (each with its own submission id + status), |
|
| Pages the primary's sentences to translate yourself: source text, the pivot-language gloss per sentence and per token (which fixes each word's sense). Feeds the draft flow. Empty glosses throughout mean a bare episode, awaiting a cold fill. |
|
| Fans an episode out into 1-10 extra ordinary target languages server-side (Groq, no tokens of yours); returns a job per language. Leveled same-language codes are rejected here - use the draft flow. |
|
| Uploads a batch (1-100) of agent-written draft sentences (whole-sentence translation + one meaning per token) for a target or leveled language; returns per-sentence rejections to repair. Targeting a bare episode's OWN language is the cold fill, and takes optional per-token |
|
| Validates a complete draft and applies it, minting the sibling deck; polls the job and returns the new submission id when ready. A cold fill applies in place instead - no sibling, no language slot - and un-bares the episode. |
|
| Deletes the in-progress draft rows for a language (destructive; never a committed sibling). |
|
| Everything needed to translate ONE lesson into one language: its meta-language strings as path-addressed units (each |
|
| Saves your translated units as a language EDITION of the lesson on the sibling submission - target text, structure and answers stay byte-identical by construction. A 400 lists every problem at once; |
|
| The same for a whole guided path: the plan's units plus per-section state ( |
|
| Mints the sibling's guided plan from the master's translated plan units - once, before any section. Structure (positions, order, focus, minutes) is copied server-side. |
|
| Attaches ONE translated guided part to the sibling's plan, keyed by the section's |
|
| An episode's creator annotations (each a markdown note on a transcript sentence span), plus |
|
| Attaches a markdown creator note to a sentence span (Unicode code-point offsets into the sentence's |
|
| Replaces one annotation's note in place (the anchor stays put). |
|
| Deletes one annotation (destructive); also how you fix a mis-anchored span before re-creating it. |
|
| Starts (or reports) the server-side plan for a guided study path over an episode: the sections, their sentence ranges and their teaching focus. Poll it; calling twice while one is in flight is safe. |
|
| The current guided path: plan status, every section with its bounds, focus and whether a part has been written for it yet. |
|
| Claims one section and returns the runtime brief for it: the sentences, the target vocabulary, the audio windows and the pedagogy this part must follow. The brief - not this repo - is where the guided craft rules live. |
|
| Submits the written part back against its brief; the server validates it and renders it in the app exactly like an internally generated one. |
Plus nine skills:
lingochunk-overview - the "what can I do?" tour: a short menu of
every area (with an example prompt each) and instructions to answer
briefly, then expand whichever area the user picks.
lingochunk-lesson - composes a coursebook-style lesson.v1 document
(listen, text, vocabulary, one grammar point, graded exercises, review)
from the tools above, filtering out words you already know; the app
renders it natively and can export an offline HTML worksheet.
lingochunk-course - plans a multi-lesson series: slices an episode (or
collection) into coherent parts, creates a course, then builds N lessons via
the lesson skill with a different grammar point and ramping difficulty per
lesson, each filed under the course in order.
lingochunk-guided - writes the parts of a guided study path yourself,
following the plan-brief-compose-submit loop, so they render exactly like
internally generated ones. It teaches only the loop: the pedagogy for each
part arrives inside its brief at runtime.
lingochunk-cards - builds native-grade flashcards with the card.v1
kinds: verbatim transcript anchors, per-kind guidance (grammar =
production cloze of the morpheme with a hint), and a quality rubric
distilled from the known failure modes of AI-generated cards.
lingochunk-discuss - a lighter, conversational "talk me through this
episode" workflow.
lingochunk-add-language - adds another language to one of your episodes
as a new sibling deck: either the server-side Groq fan-out for an ordinary
target, or an agent-supplied translation you write sentence by sentence and
commit - the only way to build a leveled same-language deck (e.g.
"German (A2)", German audio glossed in simpler A2 German). It also covers
the cold fill: finishing an episode processed without the server's AI,
by writing its word meanings yourself in its own language.
lingochunk-annotate - finds the genuinely useful expressions in one of
your episodes (idioms, phrasal verbs, collocations, discourse markers,
culture-bound references) and attaches a short markdown creator note to each
exact span: an iris tint + note sheet for you, a forward-only note card for
your followers.
lingochunk-skill-author - the meta-skill: generalises a lesson you
have refined (say, through the app's Co-edit mode) into a NEW reusable
skill - structure and voice kept, episode content replaced by
fetch-and-quote instructions - which you keep private in your own AI's
context or contribute here as a PR (see CONTRIBUTING).
The Claude Code plugin installs these as skills. Every client also gets the
same guidance two other ways that need no plugin: as MCP prompts (one per
skill, named lingochunk-lesson, lingochunk-cards, ...) in the client's
prompt/slash picker, and via the get_authoring_guide tool the model can
call itself before composing.
Related MCP server: wisdom-store
Node.js >= 18.
A LingoChunk personal access token: in LingoChunk, open Settings -> API
access, create a token, and grant the scopes you need (vocab:read +
content:read cover the read tools; add cards:write, decks:export,
lessons:write, translations:write and annotations:write for the write
tools). The token is shown once and starts with lcp_. The 403 errors from
the tools name the exact scope you are missing.
This repo is its own plugin marketplace. In Claude Code:
/plugin marketplace add lingochunk/lingochunk-mcp
/plugin install lingochunk@lingochunk-mcpThe plugin's .mcp.json runs the published server via npx, pinned to the
exact version the plugin was released with (no build step needed), and reads
your token from the environment, so export it in the shell you start Claude
Code from:
export LINGOCHUNK_TOKEN=lcp_your_token_hereThe skills/ (lesson builder and episode discussion) are picked up
automatically with the plugin.
claude mcp add --scope user lingochunk --env LINGOCHUNK_TOKEN=lcp_... -- npx -y @lingochunk/mcpFor development against a local checkout, run the built server directly:
npm install # installs deps and builds dist/ via the prepare script
claude mcp add lingochunk --env LINGOCHUNK_TOKEN=lcp_... -- node /absolute/path/to/lingochunk-mcp/dist/index.jsThe same server also runs hosted at https://lingochunk.com/mcp as a
standard remote MCP server (Streamable HTTP). Nothing to install - paste
the URL into any client that supports custom remote MCP servers and sign in
with your LingoChunk account when the client prompts you (OAuth 2.1 with a
consent screen; the grant appears in Settings -> API tokens, revocable like
any token). Clients with a token field can instead send a personal access
token as a Bearer credential:
Client | Where |
claude.ai (web/desktop/mobile, incl. Free) | Settings -> Connectors -> Add custom connector -> URL |
Claude Code |
|
ChatGPT (paid plans) | Settings -> enable Developer mode -> Apps -> "+" -> URL (OAuth), or URL + your token |
Mistral Le Chat | + Add Connector -> Custom MCP Connector -> URL (auth auto-detected) |
Perplexity (Pro/Max), Grok, Manus | add a custom connector/MCP server by URL, sign in or paste an API key |
Differences from the local server: get_audio_clip is unavailable (it writes
files, which only makes sense on your own machine - use get_audio_url), and
skills don't auto-load (the server exposes each skill as an MCP prompt,
and agents can pull the same guidance through the get_authoring_guide tool).
If your client offers neither OAuth nor a token field, embed the token in
the URL: https://lingochunk.com/mcp/t/lcp_.... That URL then IS a
credential - treat it like a password, prefer a token with only the scopes you
need, and revoke it in Settings if it ever leaks. OAuth sign-in or a header,
when your client supports one, is always preferred (URLs end up in access
logs).
Nothing in the server is Claude-specific: it is a standard stdio MCP server,
so any MCP-capable agent can run it. The recipe is always the same - run
npx -y @lingochunk/mcp with LINGOCHUNK_TOKEN in its environment - and
most clients express it as JSON like this:
{
"mcpServers": {
"lingochunk": {
"command": "npx",
"args": ["-y", "@lingochunk/mcp"],
"env": { "LINGOCHUNK_TOKEN": "lcp_your_token_here" }
}
}
}Where that config lives per client (differences noted):
Client | Where |
Claude Desktop | Settings -> Developer -> Edit Config ( |
Cursor |
|
Windsurf |
|
VS Code (Copilot agent mode) |
|
Gemini CLI |
|
Codex CLI |
|
Where your client supports it, prefer referencing an environment variable
over pasting the token into the config file (VS Code can prompt for it via
inputs; CLI clients usually inherit your shell environment).
The skills are not Claude-specific either: each one is a plain-markdown
playbook (skills/<name>/SKILL.md). Claude Code auto-loads them through the
plugin; with any other agent, point it at the file (or paste it as context)
and ask for a lesson. Every hard guarantee - the schema, verbatim transcript
quoting, sentence positions - is enforced server-side on save, so the
quality contract holds no matter which agent is driving.
Two artefacts ship from this repo and version separately:
Artefact | Carries | Check the version with |
Claude Code plugin | the skills + the server launcher |
|
npm package | the MCP server (the tools) |
|
/plugin marketplace update lingochunk-mcp
/reload-pluginsThe first refreshes the marketplace; the second activates updated skills in the RUNNING session (new sessions load them automatically). To compare the installed version against what the marketplace offers:
claude plugin list --json --availableSet-and-forget alternative: /plugin -> Marketplaces -> select
lingochunk-mcp -> Enable auto-update (third-party marketplaces have it
disabled by default; official ones are on). With it enabled, Claude Code
refreshes at startup and prompts /reload-plugins when something changed.
An update only appears when the plugin's version was bumped - Claude Code
uses it as the cache key, which is why our release rule (CONTRIBUTING.md)
bumps it on every user-visible change.
The plugin pins the exact server version in its .mcp.json, so updating
the plugin updates the server too - no separate step. A running session
keeps its old server process; /reload-plugins (or a new session)
reconnects to the new one.
Standalone installs (claude mcp add ... npx -y @lingochunk/mcp, or the
other-agents configs above) are exposed to an npx trap: npx caches packages
in ~/.npm/_npx and does NOT re-check the registry once cached, so an
unpinned @lingochunk/mcp can run a stale server indefinitely. To check and
fix:
npx -y @lingochunk/mcp --version # what npx actually runs
npm view @lingochunk/mcp version # latest published
rm -rf ~/.npm/_npx # blunt fix: clear the npx cache, relaunchOr make your config always-fresh by using @lingochunk/mcp@latest (checks
the registry on every launch: ~1-3 s extra startup and a registry
dependency), or pin @lingochunk/mcp@<version> and move the pin yourself
when you want the update.
Variable | Required | Default | Meaning |
| yes | - | Your personal access token ( |
| no |
| API origin override (for self-host/testing). |
| no |
| Where |
The token is only ever sent as an Authorization: Bearer header to the
configured origin; it is never written to disk or logged.
node dist/index.js --http serves the same tools over Streamable HTTP for
remote MCP clients (see Option C). The process is stateless and multi-user:
LINGOCHUNK_TOKEN is not read - every request must carry its own
Authorization: Bearer lcp_... header, which is forwarded verbatim to the
API (the API stays the sole authority; the server stores nothing). A
Dockerfile is included.
Variable | Required | Default | Meaning |
| no |
| Listen port ( |
| no |
| API origin; co-located deployments should point at the loopback origin. |
Endpoints: POST /mcp (the MCP wire), GET /health (liveness).
Ask your agent something like "build me a lesson from yesterday's German episode"
or "quiz me on the words I'm learning". The lingochunk-lesson skill drives the
workflow: pick the source, pull a transcript slice, gather and filter your
vocabulary (never quizzing you on mastered words), then compose a structured
lesson.v1 document that the app renders natively - real episode audio, live
word state, crosslinks, Ask AI - with an offline HTML export available in-app.
A submission can hold many lessons, so different skills (or repeated runs) add
lessons side by side under the episode's Lessons tab. See
skills/lingochunk-lesson/.
src/ the MCP server (TypeScript, stdio)
skills/lingochunk-overview/ the "what can I do?" tour skill
skills/lingochunk-lesson/ the coursebook lesson skill
skills/lingochunk-course/ the multi-lesson course planner skill
skills/lingochunk-guided/ the guided-path writer-loop skill
skills/lingochunk-cards/ the flashcard (card.v1) skill
skills/lingochunk-discuss/ the "discuss an episode" skill
skills/lingochunk-add-language/ the add-language / draft-translation / cold-fill skill
skills/lingochunk-annotate/ the useful-expression annotation skill
skills/lingochunk-skill-author/ the meta-skill: lesson -> reusable skill
skills/*/examples/ example lesson.v1 documents (CI-validated)
docs/creator-guide.md the guide for content creators (start here if you make audio)
docs/skill-authoring.md how to write a new skill
docs/skill-template.md SKILL.md starting point
docs/integrations/fluent.md how to plug this into the fluent tutor plugin
spec/openapi-public-v1.json the committed public API spec (the contract)
scripts/validate-lesson.ts validate a lesson.v1 document against the spec
scripts/smoke.ts live smoke test (run by hand, never in CI)
test/ vitest unit tests (mocked fetch) + example validation
.claude-plugin/plugin.json Claude Code plugin manifest
.mcp.json MCP server definition for the pluginSkills are markdown pedagogy, not code: a SKILL.md playbook plus an example
lesson.v1 document that CI validates against the committed spec. Anyone can
contribute one - a dictation drill, an exam rehearsal, a due-words review
session - and AI-drafted skills are explicitly welcome. Start with
CONTRIBUTING.md and
docs/skill-authoring.md.
npm install # deps + build (prepare)
npm run build # compile src/ -> dist/
npm run typecheck # type-check without emitting
npm test # vitest unit tests (mocked fetch; no network) + skill example validation
npm run validate:lesson -- <doc.json> # validate a lesson.v1 document (Node 22.6+)spec/openapi-public-v1.json is the source contract; it is exported from the
LingoChunk repo (make generate-openapi-public) and refreshed here on each API
release. This copy was taken from LingoChunk commit 505af49a.
scripts/smoke.ts exercises a real API and is not part of npm test. Build
first, then run it by hand with a real token:
npm run build
LINGOCHUNK_TOKEN=lcp_... [LINGOCHUNK_BASE_URL=http://localhost:8000] \
node --experimental-strip-types scripts/smoke.tsMIT.
Add a card to the user's LingoChunk review queue (FSRS; it starts as 'new'). kind=vocab adds a word the user ALREADY has in their vocabulary, resolved by lemma against their own content (404 if the lemma is not in their vocabulary; 409 code=ambiguous_lemma if it occurs in several episodes or under several parts of speech, so pass submission_id or pos as the message names). kind=custom adds a freeform card and REQUIRES front, back and submission_id (the episode it anchors to); pass sentence_position to anchor its example to a specific transcript sentence. Omit deck_id and the card goes to the deck for its own submission (the same deck the app builds, reviews and exports that episode from, so it is immediately visible and exportable); an explicit deck_id must belong to that submission (400 otherwise). A 409 code=duplicate_card means the card already exists: expected, not worth retrying. NOTE: deleting the anchoring episode deletes the card (cascade), and a card added while the app's Words tab is open on that episode may be overwritten by the app's own save, so add cards when the app is not actively editing that deck. Requires the cards:write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| pos | No | Part of speech, to disambiguate the lemma (kind=vocab); case-insensitive. | |
| back | No | Back/answer text (kind=custom; max 500 chars). | |
| kind | Yes | vocab = a word from your vocabulary; custom = freeform front/back. | |
| note | No | Optional note shown on the card (kind=custom; max 300 chars). | |
| front | No | Front/prompt text (kind=custom; max 200 chars). | |
| lemma | No | Dictionary form to add (kind=vocab). | |
| deck_id | No | Target deck id from list_decks; omit to use the deck for the card's own submission. When given, it must belong to that submission. | |
| submission_id | No | Disambiguate the lemma to one episode (kind=vocab); the episode the card anchors to (REQUIRED for kind=custom). | |
| sentence_position | No | 1-based transcript position (see get_transcript) to anchor a custom card's example; defaults to the submission's first sentence. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the card starts as 'new', uses FSRS, and explains cascade deletion, overwrite risks, and required scope (cards:write). Minor omissions like rate limits or response format prevent a 5.
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 a single dense paragraph that front-loads the core purpose. While comprehensive, it could benefit from breaking into sections for readability. Every sentence adds value, but the length is slightly high for the amount of information.
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's complexity (9 params, two modes, error handling, cascade behavior), the description covers most aspects but omits the success response structure. Without an output schema, the agent might need to guess what the response contains, which is a gap for a creation tool.
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?
Schema description coverage is 100%, but the description adds significant context: for kind=vocab it explains resolution by lemma and error conditions; for kind=custom it clarifies required fields; deck_id behavior is fully detailed. This goes well beyond the schema's minimal descriptions.
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 the tool's purpose: 'Add a card to the user's LingoChunk review queue'. It distinguishes between two card types (vocab and custom) with specific behaviors, setting it apart from sibling tools like list_decks or get_transcript.
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?
The description provides explicit when-to-use guidance for each kind, including error handling (404, 409) and a warning about app interference. However, it lacks explicit alternatives or when not to use this tool, though siblings are sufficiently different.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export one of the user's decks to an Anki .apkg and return a download URL. Running it costs nothing (no LLM). This starts the export and polls status for up to ~60s, absorbing rate limits with a Retry-After backoff and never starting a second job while one is already in flight. It returns {status:'ready', download_url} when the file is ready, {status:'pending'} (call again shortly to keep checking) while it generates, {status:'failed'} to retry, or {status:'none'} (nothing to download; call again to trigger a fresh export). A deck with no linked source episode cannot be exported (400). Use list_decks to find a deck_id. Requires the decks:export scope.
| Name | Required | Description | Default |
|---|---|---|---|
| deck_id | Yes | The deck to export (from list_decks). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: polling up to ~60s, rate limit backoff, no concurrent jobs, and all possible return statuses.
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?
Every sentence adds value, front-loaded with purpose, then behavior, status codes, and error cases. No redundant or wasted words.
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 no output schema, the description fully explains all possible return values and statuses. It also covers prerequisites, error conditions, and behavioral guarantees, making it completely informative for an agent.
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?
Schema already covers the single parameter (deck_id) with description 'The deck to export (from list_decks).' The tool description adds context by telling the user to use list_decks to find a deck_id, providing helpful linkage beyond the schema.
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?
Clearly states it exports a user's deck to an Anki .apkg and returns a download URL. Distinguishes from siblings by referencing list_decks as a prerequisite tool.
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?
Explicitly tells when to use (export a deck), prerequisites (needs decks:export scope, use list_decks), and conditions when export fails (no linked source episode → 400).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cut a native-audio snippet [start, end] (seconds, max 60s) from a submission and SAVE IT to a local file, returning the file path. Use these small clips to embed audio in a self-contained HTML lesson (e.g. as a data URI). Rate limited.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Clip end in seconds (start < end). | |
| start | Yes | Clip start in seconds. | |
| submission_id | Yes | The submission id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Reveals key behaviors beyond schema: saves to local file (side effect), max 60s duration, and rate limiting. No contradictions with annotations (none provided).
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?
Two concise sentences, front-loaded with action and key details. No extraneous information.
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?
Covers all essential aspects: what it does, input constraints, output (file path), use case, and rate limit. No output schema needed; description adequately explains return value.
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?
Adds the 60-second maximum duration constraint not present in schema, though schema already describes parameters. High schema coverage (100%) reduces burden but extra constraint is valuable.
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?
Clearly states cutting a native-audio snippet and saving to a file, specifying the source (submission) and output (file path). Differentiates from sibling tool 'get_audio_url' which returns a URL.
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?
Provides a specific use case (embedding audio in HTML lessons) and implicit guidance that clips are small and rate-limited. Does not explicitly exclude alternatives like get_audio_url.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a short-lived presigned URL to a submission's full native audio (supports HTTP Range). Use for streaming; for a durable snippet to embed in a lesson, use get_audio_clip instead.
| Name | Required | Description | Default |
|---|---|---|---|
| submission_id | Yes | The submission id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses that the URL is short-lived and supports HTTP Range, which helps with streaming. However, the exact lifetime is not specified, which could be important.
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?
Two sentences, front-loaded with core action, no wasted words.
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 one parameter and no output schema, the description adequately explains the return value and use case. Slight gap on URL duration, but overall complete.
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?
Sole parameter submission_id is fully described in the schema. The description adds no extra meaning beyond what the schema provides, so baseline score applies.
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 the tool gets a short-lived presigned URL for a submission's full native audio, and explicitly distinguishes it from the sibling get_audio_clip tool.
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?
Explicitly tells when to use this tool (for streaming) and when not (for durable snippets), directing users to the alternative get_audio_clip.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a submission's transcript: timestamped sentences with translations. Sliceable by sentence-position range (from_sentence/to_sentence) or time range in seconds (from_time/to_time) so you can pull an excerpt instead of a whole episode. transcript_state tells you if it is ready, still processing, or unavailable.
| Name | Required | Description | Default |
|---|---|---|---|
| to_time | No | End of window (s). | |
| from_time | No | Start of window (s). | |
| to_sentence | No | ||
| from_sentence | No | ||
| submission_id | Yes | The submission id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It reveals that transcripts are timestamped and sliceable, and includes transcript_state for status. However, it does not detail error handling or behavior when state is not ready.
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?
Three concise sentences, front-loaded with purpose, then slicing, then state. No unnecessary words.
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?
Lacks output schema but describes core return elements (timestamped sentences, translations, state). Could be more specific about the exact structure, but sufficient given tool complexity.
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?
Description explains slicing parameters (from_sentence/to_sentence and from_time/to_time) and their purpose for excerpting, adding value beyond schema descriptions. Schema coverage is 60%, and description compensates well.
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 the tool fetches a submission's transcript with timestamped sentences and translations, distinguishing it from sibling tools like get_audio_clip or get_vocabulary.
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?
The description implies when to use the tool (for transcript retrieval) and how to slice excerpts, but does not explicitly mention when not to use it or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's vocabulary, aggregated per word with FSRS maturity (state/stability/due/reps). Grounded in the user's real listening history. Filter by language, status (known|learning|new|due), or CEFR; use 'since' (an ISO 8601 time from a prior 'updated_at') plus 'cursor' for incremental sync. Sync is additive-only, so full-resync periodically. The list is cursor-paginated (limit up to 200); follow next_cursor until it is null to read the complete set.
| Name | Required | Description | Default |
|---|---|---|---|
| cefr | No | Filter by CEFR level; one of A1-C2 (normalised to uppercase). | |
| limit | No | ||
| since | No | Return only words changed at/after this date or datetime. | |
| cursor | No | Opaque cursor from a previous page's next_cursor. | |
| status | No | Filter by learning status derived from FSRS state. | |
| language | No | Filter to one learning language, ISO 639-1, e.g. 'de' (normalised to lowercase). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description covers key behaviors: additive-only sync, cursor pagination with limit up to 200, and grounding in listening history. Missing output schema details but adequate.
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?
Two sentences packed with information, front-loaded with core purpose, then usage and pagination. No fluff.
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?
Lacks explicit return schema, but mentions next_cursor and FSRS fields. For a list tool, more detail on response structure would improve completeness.
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?
Adds context beyond schema: 'since' as ISO 8601 from prior updated_at, 'cursor' as opaque, 'status' from FSRS, 'language' as ISO 639-1. Schema coverage is 83%, and the description fills remaining gaps.
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 the tool lists the user's vocabulary aggregated per word with FSRS maturity details, distinguishing it from sibling tools like 'lookup_word' or 'list_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?
Explicitly explains when to use filters, incremental sync via cursor and since, and notes that full-resync is needed periodically. Does not compare directly to siblings but provides clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's study decks so you can pick a deck_id before adding cards (add_card) or exporting (export_anki_deck). Each deck reports its language and card counts (total / new / due). Requires the cards:write or decks:export scope.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains it lists decks, returns language and card counts, and requires specific scopes. It does not mention pagination, ordering, or error behavior, but the basic behavior is covered.
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 two sentences, each earning its place: first sentence states purpose and usage, second details output content. No fluff or repetition.
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?
The description covers the purpose, usage context, scopes, and return fields. It could mention ordering or empty state, but for a simple list tool with no parameters or output schema, it is sufficiently complete.
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?
There are no parameters, so schema coverage is 100% trivially. The description adds value by explaining what the response contains (language and card counts), compensating for the lack of an output schema.
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 it lists decks, specifies the purpose (to pick a deck_id before using add_card or export_anki_deck), and details what each deck reports (language, card counts). This distinguishes it from sibling tools by tying it to specific workflows.
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?
The description explicitly tells when to use the tool (before adding cards or exporting) and lists required scopes. It does not explicitly state when not to use, but the context is clear and no exclusions are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's ready-to-study episodes (their own submissions plus collections they follow), newest first. Cursor-paginated. Use the returned submission ids with get_transcript / get_audio_url / get_audio_clip.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | Opaque cursor from a previous page's next_cursor. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers pagination behavior and the contents of the list (submissions and collections). It does not mention auth or rate limits, but provides sufficient behavioral context for a listing operation.
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 two sentences, front-loaded with the main purpose. Every sentence adds value without redundancy.
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?
No output schema is provided, and the description does not specify the return structure (e.g., contains submissions, next_cursor). It implies the output includes submission IDs, but more detail would improve completeness.
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?
Schema coverage is 50% (only cursor has a description). The description mentions cursor-pagination but does not explain limit or cursor format beyond what the schema states. It partially compensates but could be more detailed.
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 the verb (list), resource (ready-to-study episodes), and scope (user's own submissions plus collections they follow, newest first). It also mentions cursor-pagination, distinguishing it from retrieval tools like get_transcript.
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?
The description tells the user to use returned submission IDs with related tools (get_transcript, get_audio_url, get_audio_clip). It does not explicitly contrast with list_decks but the context implies different resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up one word: the user's own context (translation, gender, CEFR, FSRS state) if they have cards for it, backed by the shared enrichment lexicon as a gender/CEFR fallback. Use this to ground an LLM's guesses about a word rather than inventing them.
| Name | Required | Description | Default |
|---|---|---|---|
| pos | No | Part of speech, if known (e.g. NOUN). | |
| lemma | Yes | Dictionary (base) form to look up. | |
| language | Yes | Language of the word, ISO 639-1 (normalised to lowercase). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool returns user-specific context if cards exist, with fallback to a shared lexicon. It also lists the types of information (translation, gender, CEFR, FSRS state). This is reasonably transparent, though it does not specify read-only status or error conditions.
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 two sentences with no wasted words. The first sentence defines the tool's function and scope, and the second provides a clear usage directive. Information is front-loaded and efficient.
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 3 parameters, no output schema, and no annotations, the description covers the essential aspects: what the tool does, what it returns (user context with fallback), and when to use it. It does not explain the output format or error handling, but for a straightforward lookup tool this is sufficient.
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?
Schema coverage is 100%, so the baseline is 3. The description does not add new parameter-level details beyond what the schema provides. However, it adds overall context about what the parameters are used for (e.g., looking up a word with personal context), which is helpful but does not extend the semantic meaning of individual parameters.
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 the verb 'look up' and the resource 'one word', and specifies that it returns the user's personal context (translation, gender, CEFR, FSRS state) with a fallback to a shared lexicon. This distinguishes it from sibling tools like search_examples (which searches through examples) and get_vocabulary (which retrieves a list).
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?
The description explicitly tells when to use the tool: 'to ground an LLM's guesses about a word rather than inventing them.' It provides clear context but does not explicitly mention when not to use it or list alternatives, which prevents a score of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a single self-contained HTML lesson to the user's private LingoChunk library (10 MB max, up to 100 lessons, private by default). Returns the lesson metadata plus a short-lived view URL to open it now; its durable home is the app's library, where it opens on any device. Use this to keep a lesson the lingochunk-lesson skill produced. Requires the lessons:write scope.
| Name | Required | Description | Default |
|---|---|---|---|
| html | Yes | The complete self-contained HTML document. | |
| title | Yes | Lesson title. | |
| language | Yes | Target language, ISO 639-1. | |
| source_submission_ids | No | Optional provenance: the episode ids the lesson was built from. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses size limits (10 MB max, 100 lesson cap), privacy default, return value (metadata plus short-lived view URL), and scope requirement (lessons:write). There is no contradiction.
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?
Two sentences, front-loaded with purpose and key constraints. Every sentence adds value. No fluff.
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 4 parameters and no output schema, the description covers purpose, constraints, return, usage context, scope, and durability. It is complete for an agent to decide to invoke the tool.
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?
Schema coverage is 100%, so baseline is 3. The description does not add per-parameter details beyond what the schema provides, but it does add overall constraints (max size, max lessons) that are not in the schema. This is adequate but not exceptional.
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 explicitly states the verb 'Save', the resource 'single self-contained HTML lesson', and the destination 'user's private LingoChunk library'. It also lists key constraints (10 MB max, up to 100 lessons, private by default). This clearly distinguishes the tool from siblings like list_library or add_card.
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?
The description says 'Use this to keep a lesson the lingochunk-lesson skill produced', providing clear context for when to use. It also mentions the required scope 'lessons:write'. While it doesn't explicitly state alternatives or when not to use, the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the user's readable library for sentences. 'lemma' returns the curated example sentences for that word; 'q' does a case-insensitive substring match on sentence text. At least one is required, and 'lemma' takes precedence when both are given. Results are a capped sample, not exhaustive.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Case-insensitive substring match on sentence text. | |
| lemma | No | Find example sentences for this dictionary form. | |
| limit | No | ||
| language | No | Restrict to one language (normalised to lowercase). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It accurately portrays a read-only search operation and mentions the non-exhaustive nature of results, but could additionally clarify permissions or rate limits.
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?
Three concise sentences with no redundancy, each sentence adds essential information: purpose, parameter behavior, and result limitations.
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?
Covers key aspects given no output schema or annotations, but lacks details on return format or how to handle the capped nature (e.g., pagination). Still largely complete for a search tool.
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?
The description adds significant meaning beyond the schema: clarifies the role of 'lemma' vs 'q', states the requirement of at least one, precedence rule, and sampling behavior, complementing the 75% schema coverage effectively.
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 the tool searches for sentences, specifies two distinct search modes ('lemma' for curated examples, 'q' for substring match), and distinguishes them, making the purpose unambiguous.
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?
Provides explicit guidance on when to use each parameter, states at least one is required, explains precedence when both are given, and notes that results are a capped sample, covering usage context well.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.1add_cardexport_anki_deckget_audio_clipget_audio_urlget_transcriptget_vocabularylist_deckslist_librarylookup_wordsave_lessonsearch_examplesScored across 11 tools
Each tool serves a distinct purpose: card management, export, audio, transcripts, vocabulary, decks, library, lessons, and search. There is clear differentiation even for similar operations like get_audio_clip vs get_audio_url (snippet vs stream) and get_vocabulary vs lookup_word (list vs single word with context).
All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_card, get_audio_clip, list_decks, lookup_word). No mixed conventions or ambiguous verbs.
With 11 tools, the server covers essential functionalities for a language learning app without being excessive. Each tool has a clear role and contributes to a coherent workflow.
The tool surface covers core operations: card addition, export, audio retrieval, transcript access, vocabulary management, and lesson saving. Minor gaps exist (e.g., no explicit card update/delete tool), but the set is functional for the intended use case.
Turn any recording or document into notes, flashcards and quizzes your agent can read and act on
Free: turn your AI chats into spaced-repetition vocabulary. 13 tools, reads and writes.
Build and study spaced-repetition flashcards with your agent.
The media memory layer for AI agents and their humans. Your AI client gets 29 tools to search your collection, add items, update ratings, preview music, and find patterns across everything you've read, watched, and listened to.
