Flashcards Space

Use this right after the user answers the current card’s front, or says they remember or forgot it. Compare the answer with the card’s back by meaning: an equivalent meaning, or the saved word with minor inflection or spelling differences, is remembered; a different meaning or “I don’t know” is forgotten; the user’s own assessment wins. Do not use it for a start or resume request, a request to see the answer, a side question, or an unclear or empty reply; ask a clarifying question when unclear. Pass the current card id and version and the latest startedAt and timeZone. In the reply that calls it, say whether the answer was right and ask the next front the latest result named for that outcome, before the result arrives; never say the grade was saved before the result confirms it. Then follow the result. If the call fails, say the grade could not be confirmed and call getReviewSession before continuing; do not retry the grade blindly.

gradeReviewCard

Use this when the user asks which decks, native languages, or learning languages they have, or before creating flashcards so you can fetch valid deck slugs.

getUserPreferences

Use this when the user wants to review, practice, study or be quizzed on their flashcards or a deck. Starts or resumes today’s review of the deck the user named, by its slug from getUserPreferences, and shows the review widget. Start one review per request. If they named no deck, ask which one first, even if they have only one; seeing one deck in getUserPreferences is not their choice, so never pick it for them. Do not use it for translations, explanations or general lessons. The result has the current card’s front, which you ask, and its back, which is the answer key: keep it hidden until the user answers or asks to see it. Each result also names the next front for each grade, so you can ask it while the grade saves. Omit startedAt on the first call. Pass timeZone only when you know the user’s IANA time zone; otherwise omit it. Then reuse the returned startedAt, timeZone and current card id on later review calls. Never pass an empty timeZone.

getReviewSession

Use this to save new flashcards into a known deck. When multiple decks exist, provide a valid deck slug from getUserPreferences. Do not use it to edit or delete existing flashcards.

createFlashcards

Use this only when the user asks to undo or correct the most recent grade in this review. Each call undoes one more assessment made since startedAt, newest first, including its schedule and progress. If the user wants to change an earlier card’s grade, explain that undo goes newest first and ask before undoing. Pass the latest startedAt and timeZone. Confirm only after the tool succeeds.

undoReview