Hachimo

Use this when the learner explicitly asks to change today's time budget. Shrink today's plan when the learner is short on time (e.g. "only 10 minutes today"). Keeps as many pending tasks as fit the minutes budget, skips the rest. Completed tasks are untouched.

adjust_today_plan

Use this when the learner explicitly asks Hachimo to create a structured vocabulary list, practice quiz, or pronunciation test during coaching, or to assign one to Today. Set delivery=practice_now to practice in the chat and delivery=today to place it in both the iOS Today screen and Memory library. For today's materials, create vocabulary, grammar, and pronunciation assignments with the same dueDate so the app groups them into one daily set. For multiple_choice, provide 2–6 unique plausible choices with exactly one accepted answer. For typing, include every acceptable spelling in acceptedAnswers. Grammar supports choice, fill_blank, reorder, and correction; input modes require answer and acceptedAnswers, and reorder also requires tokens. Include promptAudio for listening-led practice. Use a stable sourceReference so retries do not create duplicates. After creation, call get_learning_assignment to display the activity. For a whole completed lesson, prefer preview_lesson_bundle and save_lesson_bundle instead of creating each material separately.

create_learning_assignment

Use this when the learner asks to review vocabulary. Get private spaced-repetition cards due now and run a quick review session in chat: show the front, wait for the learner to answer, call reveal_srs_answer, then grade with submit_srs_review.

get_srs_queue

Use this before personalising a lesson or plan. Get the learner's private CEFR level, goal, interests, weaknesses, daily minutes, and preferred lesson types.

get_learner_profile

Use this when the learner asks how they are doing. Get XP total, current and longest streak, weekly XP chart data, and earned badges.

get_progress

Use this when the learner asks for today's plan or current daily progress. Get the learner's study plan for today (JST) plus their progress (XP, streak) and learner profile. If `plan` is null, design a plan from the profile and save it with save_today_plan. If `profile` is null, ask for level, goal, and daily time before offering to save a profile.

get_today_plan

Use this when the learner wants to open or resume a Hachimo learning assignment by ID. It renders the vocabulary list, quiz, or pronunciation test. Do not narrate hidden answers before the learner attempts them.

get_learning_assignment

Use this after a lesson when the learner may want to save everything to Hachimo. For a substantive lesson, aim for at least 10 genuinely useful review-card words or phrases, but never add filler or near-duplicates; saving fewer is valid when fewer are meaningful. Include the lesson record, review cards, and all vocabulary, grammar, and pronunciation materials in one draft. This tool does not save anything. It shows exactly what will be registered and a single “Save as today’s materials” action. Do not call save_lesson_bundle until the learner explicitly confirms in chat or presses that action.

preview_lesson_bundle

Use this after the learner finishes a Hachimo lesson. Record the score, summary, mistakes and new vocabulary. Awards XP and updates the streak (idempotent). For plan tasks pass planId+taskId; for spontaneous lessons omit them and pass a unique refId instead. When lesson results, review cards, and materials should be saved together, use preview_lesson_bundle and save_lesson_bundle instead.

complete_lesson

Call this only after the learner has attempted the front returned by get_srs_queue. Reveal the private answer and optional example so the learner can compare before submit_srs_review.

reveal_srs_answer