references/tool-contract.md

# Learner MCP Tool Contract

Use only these learner-scoped tools.

| Goal | Tools | Guardrail |
|---|---|---|
| Start coaching / return from app | `get_learner_context` | Read only; connected learner only. Follow `coach_instruction`. |
| Confirm saved preferences | `get_learning_profile`, `get_current_learning_state` | Do not overwrite from one chat message. |
| Select a course | `list_courses` → `preview_learning_profile` → `apply_learning_profile` | Apply only after explicit confirmation. |
| Placement level | `save_ai_grammar_exam` (`purpose=placement`) → Mynawoo handoff → `get_generated_exam_detail` → `apply_placement_result` | Or `apply_placement_result` with `mode=start_a1` after an explicit A1 choice. Never invent CEFR. |
| Find lesson material | `get_course_structure`, `search_lessons`, `get_lesson_detail`, `get_lesson_progress` | Chat may teach from structure titles when detail is locked. |
| Lesson-grounded grammar practice | `get_grammar_screen_content` → `save_ai_grammar_exam` (`purpose=lesson_practice`) | Confirm target first; private questions only. |
| Locked lesson practice | `get_course_structure` | Teach from title metadata in chat; use `save_ai_grammar_exam` only after resolving an accessible lesson with a valid grammar screen. |
| Review learning evidence | `get_learning_weakness_context`, `get_learning_analytics`, `get_previous_grammar_mistakes` | Explain uncertainty if records are limited. |
| Review vocabulary | `get_leitner_sets`, `get_today_leitner_cards`, `get_hard_vocabulary` | Learner’s sets/cards only. |
| Manage private study content | `preview_ai_vocabulary_card` → `add_ai_vocabulary_card`, `save_learning_suggestion` | Save only on explicit request. |

Do not use `delete_generated_grammar_exam`, `edit_vocabulary_card`, or `delete_vocabulary_card` unless the learner explicitly identifies an item to change or remove.

When `get_grammar_screen_content` returns `FREE_LESSON_LIMIT`, use the locked-lesson teaching fallback in `SKILL.md`. Do not call `save_ai_grammar_exam` until an accessible lesson with a valid grammar screen has been resolved.

## Onboarding states

- `not_started`: no confirmed learning profile → run Flow A course selection.
- `placement_pending`: course selected; do not claim a CEFR level until `apply_placement_result` returns one.
- `active`: use saved course, `placement_level`, and progress to coach continuation.

## Placement exam contract

- Save with `purpose=placement`.
- Anchor to the first A1 lesson codes from `get_course_structure` even if teaching later happens in chat.
- Prefix every question `focus_area` with `A1`, `A2`, `B1`, `B2`, or `C1` so backend scoring can validate the level.
- After Mynawoo completion, call `apply_placement_result` (`mode=from_exam`). Use only the returned `placement_level`.

## Handoff UX

Every navigable result should prefer the returned `open_url`. Ask the learner to finish the action in Mynawoo, then return to chat for the next coaching step.