Suplla

Get a grammar topic's explanation (content), description, and learning goals, plus the logged-in user's status (learningStatus/learningStatusLabel/learningStatusOrder/reviewStage/lastReviewedAt/readingStatus). When topicId is omitted, `mode` controls what you get: 'next' (default) returns the next topic in curriculum order the user hasn't finished reading yet; 'review' returns an already-started topic, ordered by how due it is for review. Use mode='next' for a guided walkthrough of new material, or mode='review' when the user wants to look back at what they've studied — call this repeatedly with topicId omitted to go topic by topic. learningStatusOrder: higher means further along. `readingStatus` ('unread'/'learning'/'completed', from update_topic_reading_status) is a separate, simpler signal from `learningStatus` — it tracks whether the topic is recorded as in progress or read, not quiz mastery. Unread may already be familiar; completed does not prove ability or a previous AI explanation. Adapt support to the current conversation rather than using this flag to force stricter drilling. For mode='next' (topicId omitted), `readingStatus` is also what drives topic selection now — a topic already marked 'completed' is never re-selected, regardless of official quiz mastery. `url` links to the page on suplla.com — point users there if they want to see it on the web. Use this to explain a topic before quizzing, or to check what a topic covers before calling get_question. Each goal's `id` can be passed as get_question's `goalId` (topicId is required alongside it — grammar_topic_goal.id is only unique within its topic, not globally) to target questions at that specific goal instead of the whole topic. Each goal's `url` deep-links straight to that goal's section on suplla.com — prefer it over the topic-level `url` when pointing the user at one specific goal.

get_topic

Get a lesson from suplla's structured '/lesson' course path — a curated, ordered sequence of activities (grammar explanation/reading, exercises, word practice, phrase scenes) built from the same underlying content as get_topic/get_question/get_word, plus the user's own progress on it. Call without lessonId to get the next lesson in the user's roadmap (resuming from their most recently completed lesson, or from the start if none). Work through `steps` in order, resolving each one via the tool named in its `type` description. completion.mode tells you what finishing means: 'test' -> grade the exercise steps and report accuracy via update_lesson_progress; 'check'/'read' -> call update_lesson_progress once all steps are done, no grading needed.

get_lesson

Get one or more suplla English exercises. The correct answer is included, so use it to grade the user's response during the conversation. topicId/level/goalId/exerciseType/count are all optional. If both topicId and exerciseType are omitted, this first checks whether the user has words due for SRS review and prefers those; otherwise it returns a random multiple-choice question. Set count to get several at once in a single call. To target a specific topic, look up its ID with list_topics first. To target a specific learning goal within a topic (instead of a random mix from the whole topic), pass goalId from get_topic's goals[].id.

get_question

Get how the user's cumulative progress (memorized words, perfect words, completed grammar topics) has changed over time, as a series of points bucketed by day/week/month depending on range. This is the same trend chart shown on suplla's mypage — use it to talk about the user's trajectory over sessions (e.g. 'この1ヶ月で覚えた単語が20個増えたね'), which get_learning_status alone can't show since it only reflects today. Each point's counts are cumulative as of that bucket's date, not per-bucket deltas — subtract consecutive points yourself if you need the change within a period.

get_learning_growth

Get the logged-in user's learning status: how many words/grammar topics are due for review, how many they've already studied today, their current daily streak, and their daily goals (words/lessons). `url` links to the progress page on suplla.com — point users there if they want more detail. Note: wordReviewedToday/dueWordCount only reflect suplla's real DB progress, which for word review specifically only persists for premium users — a free user practicing with you won't move these numbers even though they're genuinely studying, so don't treat a low number as proof they've done nothing today. currentStreak is unaffected by this — it's a simple daily-activity counter that updates for every user regardless of premium.

get_learning_status

Get the user's most recent word-review sessions done directly on the suplla website (not through you) — format used, score, and which words were covered. Use this when the user refers back to something they just did on the site (e.g. 'I just did a review round, how'd I do?') so you can react to the actual result instead of asking them to describe it. This data is short-lived (auto-deleted after 24 hours) — it's for catching up on very recent activity, not a long-term history; for that, use get_word/get_learning_status instead. Returns an empty list if nothing recent.

get_recent_word_review_session

Get where the user last left off in grammar study (saved by save_study_session), so a new conversation can resume there instead of asking the user to recap or guessing from readingStatus/get_weak_topics alone. This is a single most-recent checkpoint, not a session history — separate from readingStatus, official mastery/SRS, and the AI-understanding notes in save_topic_understanding/get_weak_topics; it only points at 'what was being worked on and what's next'. Call this when the user wants to continue where they left off. Afterward, still call get_topic(topicId) to refresh goals/content/status before actually resuming — don't treat the checkpoint's own copy of goal IDs/topic details as current, since the topic may have changed since it was saved. If `resumeAvailable` is false, the referenced topic or goal no longer exists (deleted or restructured) — `unavailableReason` says which. You can still read `summary`/`nextAction` for context, but don't call get_question or update progress using `nextGoalId`/`topicId` in that case; fall back to get_topic/get_weak_topics instead.

get_last_study_session

Get a small batch of words the user hasn't started yet (no learning_status at all — this is for introducing brand-new vocabulary, not review; use get_weak_words for that). Two modes, matching get_topic's mode pattern — see OFFER_VOCABULARY_STUDY_MODES for when to offer which to the user rather than picking silently: 'level' (default) scopes to their target_level (or study_level if no target is set) and prioritizes words connected — synonym, antonym, derivation, or shared etymology — to a word they've already solidly learned (memorized/perfect), returned as `connection`; connecting new vocabulary to what's already known helps it stick (elaborative encoding). 'topic' (pass topicId) returns words tied to that specific grammar topic instead, returned as `reason` explaining the tie (e.g. 'be動詞の基本'); not every topic has these tagged, so an empty list means untagged, not that the topic has no relevant vocabulary — fall back to 'level' mode. Whichever mode gives you a `connection` or `reason`, use it explicitly when introducing the word rather than presenting it cold — but always be clear about which word is the new one to actually remember versus just context, since blurring that raises cognitive load instead of lowering it. If `harderThanConnection` is true, say so plainly rather than treating it as equally easy. Keep batches small (the default) — introducing too many new words in one go hurts retention more than it helps; don't raise the limit just to cover more ground faster.

get_next_words

Get a compact summary of which grammar the logged-in user has already studied, for shaping the AI's own sentence complexity during free conversation practice (not quizzing). `currentLevel` is a curriculum position derived from recorded mastery, not a placement-test result or an ability ceiling. `levelProgress` gives known/total topic counts per level. `knownTopics` lists every topic the user has started, in curriculum order, each with its `englishForm` (the grammar structure itself, e.g. 'have been doing') and learningStatus so you know how solid it is. Missing records, including an empty `knownTopics`, mean ability is unknown, not that the user is a beginner. Reading completion is stored separately and is not reflected here. Use these records as a starting hint alongside diagnosis results, the user's requested practice, and their actual responses; adjust sentence complexity as needed.

get_grammar_level

Get the level the user is aiming to eventually reach (targetLevel, as opposed to get_grammar_level's currentLevel — where they actually are now) and how they want you to approach the gap (studyStyle). These two are set together as one group in suplla's settings screen, never by you — both come back null if the user hasn't set a goal yet. Levels run junior-high-1/2/3, then high-school-1/2/3. Rough Eiken (English proficiency test) equivalence, if the user talks about Eiken instead of a grade: junior-high-3 ≈ Eiken grade 3, high-school-2 ≈ Eiken pre-2. studyStyle 'forward' means work sequentially from currentLevel toward targetLevel; 'backward' means start from content near targetLevel and identify specifically what's missing, backfilling earlier topics only when a gap surfaces. settingsUrl is where the user sets or changes either value — hand them that link (see DONT_READ_URLS_LITERALLY) rather than describing where to find it.

get_study_goal