Retrieve a student's basic identity and enrollment information.

This tool does NOT return parent contact details, raw assessment data, or any internal scoring/routing fields — only what's needed to personalize Coach's tone and respect age-appropriate framing.

Args:

• student_id (string): The student's unique identifier.

Returns: JSON object with schema: { "studentId": string, "displayName": string, // safe display name only "gradeBand": "elementary" | "middle" | "high" | "young_adult", "hasLinkedParent": boolean, // presence only, never parent identity "enrolledAt": string // ISO 8601 date }

Error Handling:

• Returns "Student not found" if no profile exists for the given student_id.

Retrieve a student's current XP, level, streak, and points balance.

Reads from Firestore (users/{studentId}), which is the system of record for gamification/progress data. Does NOT include quiz-level detail — use get_assessment_results for that.

Args:

• student_id (string): The student's unique identifier.

Returns: JSON object with schema: { "studentId": string, "xp": number, "level": number, "streakCount": number, "streakStatus": "active" | "at_risk" | "broken", "pointsBalance": number }

Error Handling:

• Returns "Student not found" if no Firestore user document exists for student_id.

Retrieve a student's recent quiz/assessment attempts, most recent first.

Reads from Firestore (users/{studentId}/quizAttempts). Paginated since this collection grows unbounded over a student's tenure — always check has_more.

Args:

• student_id (string): The student's unique identifier.

• limit (number): Max results to return, 1-50 (default 20).

• cursor (string, optional): Pagination cursor from a previous call's next_cursor.

Returns: JSON object with schema: { "studentId": string, "results": [ { "attemptId": string, "topic": string, "score": number, // 0-100 "completedAt": string, // ISO 8601 "attemptNumber": number } ], "hasMore": boolean, "nextCursor": string // present only if hasMore is true }

Examples:

• Use when: "How did this student do on their last few quizzes?" -> default limit

• Use when: "Show me everything" -> paginate using next_cursor until has_more is false

Error Handling:

• Returns an empty results array (not an error) if the student has no attempts yet.

Retrieve a student's completion status across Wealthi's financial literacy topics (saving, budgeting, tradeoffs, delayed gratification, goal setting, decision making, financial confidence, future thinking, credit basics).

Derives completion from passing quiz attempts (score >= 70) grouped by topic and module, mapped against the same topic taxonomy used by Coach's content library (coachContent.ts) — so results align with what's shown in-app.

Args:

• student_id (string): The student's unique identifier.

Returns: JSON object with schema: { "studentId": string, "topics": [ { "topicId": string, "topicLabel": string, "status": "not_started" | "in_progress" | "completed", "completedModules": number, "totalModules": number } ] }

Error Handling:

• Always returns all 9 topics, even if the student hasn't started any (status will be "not_started" with completedModules: 0).

Retrieve behavioral signals that inform what Coach should show a student next.

Composes data from two sources: Supabase (profiles.routing_signals, for already-seen content) and Firestore (last activity timestamp, for momentum). Returns translated behavioral labels only — never raw dormancy-decay scores or internal routing fields. This mirrors the translation Coach already does internally via behaviorLabels.ts.

Args:

• student_id (string): The student's unique identifier.

Returns: JSON object with schema: { "studentId": string, "momentumState": "building" | "steady" | "dormant" | "returning", "seenContentIds": string[], // content already shown, for dedup "daysSinceLastSession": number, "recommendedInteractionType": "read" | "decide" | "reflect" }

Examples:

• Use when: "What should Coach show this student right now?" -> check recommendedInteractionType and filter coachContent.ts by seenContentIds

• Use when: deciding whether to show comeback/re-engagement copy -> check momentumState === "returning"

Error Handling:

• A student with no activity history returns momentumState: "dormant" and daysSinceLastSession: 999 (sentinel for "never active"), not an error.

Retrieve everything Coach needs to open a session with a student, in one call.

This is the primary entry point for AI Coach sessions — composes profile, progress, learning signals, and curriculum progress into a single object, so the Coach client doesn't need to know that two separate databases (Firestore and Supabase) are involved. Use the individual tools (get_student_profile, get_student_progress, get_learning_signals, get_curriculum_progress) only when you need just one piece, or for debugging a specific data source.

Args:

• student_id (string): The student's unique identifier.

Returns: JSON object with schema: { "profile": { studentId, displayName, gradeBand, hasLinkedParent, enrolledAt }, "progress": { studentId, xp, level, streakCount, streakStatus, pointsBalance }, "signals": { studentId, momentumState, seenContentIds, daysSinceLastSession, recommendedInteractionType }, "curriculum": { studentId, topics: [...] } }

Examples:

• Use when: "Start a Coach session for this student" -> call this first, every time, before generating any Coach response

• Don't use when: you only need one field (e.g. just streak count) and want to minimize Firestore/Supabase reads -> use the specific tool instead

Error Handling:

• Returns "Student not found" if get_student_profile finds no record. Progress/signals/curriculum default to safe empty states for new students who have a profile but haven't started any activity yet.