Kenso

SOURCE OF TRUTH for active mesocycle / training block progress. Sessions and PRs accumulate continuously — pull fresh rather than recalling. Use for: - "How's this block / mesocycle going?" / "How many sessions in?" - "How many PRs this block?" / "What did I hit in this meso?" - "How much volume have I done on this program?" - "What's left in this meso?" Defaults to the active program. Returns sessions completed since meso start, total volume + sets, PRs achieved during the block, per-workout completion counts, and a `kensoSays` summary line.

SOURCE OF TRUTH for the user's next scheduled workout. Pulls live from their CURRENT active program — do not infer the next workout from conversational memory, because the user may have switched programs or completed sessions since you last spoke. Call this whenever the user asks: - "What's my next workout?" / "What's up next?" / "What am I doing tomorrow?" - "What's today's workout?" (after get_today_summary, if they want the exercise list) - "What exercises am I doing?" / "What's on deck?" - "What day of my program am I on?" Returns workout name, day index within the program rotation, total days in rotation, and the full exercise list (name, primary muscle, target sets, target rep range, exercise_library_id). Returns null if no active program.

SOURCE OF TRUTH for the user's diet, calories, and macros. Always pull fresh — don't recall earlier intake numbers, daily totals shift continuously. Use for: - "How are my calories?" / "Am I eating enough?" / "What did I eat yesterday?" - "How's my protein intake?" / "Am I hitting my macros?" - "Is my cut / bulk on track?" / "Am I in a deficit?" - Whenever fueling could explain recovery or performance dips (proactively pull this) Returns 30-day and 7-day daily averages plus yesterday (and how many days were actually logged in each window). Returns available=false when nutrition tracking isn't connected — mention once and move on. External MCP/REST clients currently get available=false (data lives on the iOS client until the v1.1 sync ships).

Preflight for designing a new Kenso program. Returns the full exercise library (names + ids + muscle + equipment + tier), canonical rep ranges, allowed program/split/level enums, and the structure schema. Use for: - Always call ONCE before `save_program_structure` — saves you from guessing names that won't match the library - "What rep ranges does Kenso support?" / "What's the structure schema?" - Filter by muscle when designing a single workout day to keep payload small Use this once → design the program → call `save_program_structure`.

SOURCE OF TRUTH for a program's template structure: workouts, exercises, prescriptions (sets × reps × rest × progression). Always call this rather than recalling earlier conversation — the user can edit their program at any time and template-from-memory goes stale fast. Use for: - "What's in my program?" / "Show me Lower A" / "What are my prescribed sets?" - "Walk me through my routine" / "What's the structure?" - "What's my progression set up as?" / "What's the rep range for X?" Returns the program TEMPLATE, not what the user actually logged. When the user trains, they can swap exercises (Pendulum Squat → Linear Leg Press) or add freestyle exercises on top. To see what was actually logged, use `get_workout_session` for a specific sessionId. Template-vs-actual divergence is normal — don't treat it as a bug.

SOURCE OF TRUTH for running a workout from the user's active program: pick a day, view its exercises, and get prefill numbers for logging. Call this whenever the user wants to START or REVIEW a specific day of their program to train: - "Let me log today's workout" / "I'm about to train — pull up Upper A" - "What am I lifting today and what weights?" (targets + suggested loads) - "Which day should I do?" (returns the full rotation with the next-up flagged) Returns `workouts` (the whole rotation to pick from, each with `isNextUp`) and `selected` (the chosen or next-up day). Each selected exercise includes `targetSets`, `targetReps`, and the progression engine's `suggestedWeight`/`suggestedReps`/`suggestionReason` — the recommended next-session load, ready to prefill a logging UI. Pass `workoutId` to open a specific day; omit it for next-up. Pair with `log_program_workout` to record what the user actually did (that advances the program and progression).

SOURCE OF TRUTH for the last N days of training (default 14). Volume, intensity, and signal anomalies all shift with each session — pull fresh, don't recall. Call this whenever the user asks: - "How was my last week / two weeks?" / "What's my recent volume?" - "Am I hitting enough sets?" / "How's my training the last X days?" - "What muscles have I hit recently?" / "Did I do enough chest/back/legs?" - "Any red flags in my last 2 weeks?" / "Have my signals shifted?" Returns sessions, volume + hard sets per muscle, volume Δ vs prior window, signal anomalies (HRV / RHR / sleep / RPE trend), plus a `kensoSays` paragraph. For today specifically use `get_today_summary`; for longer-term (6+ weeks) use `get_trend_summary`.

SOURCE OF TRUTH for whether the user is recovered enough to train hard today. Recovery shifts daily based on sleep, HRV, and training load — do NOT answer from memory or assume yesterday's state still applies. Call this whenever the user asks: - "Am I recovered?" / "How recovered am I?" / "Should I push today?" - "Should I lift?" / "Should I rest?" / "Should I back off?" - "How's my readiness?" / "How am I feeling?" (when in training context) - "Am I overreaching?" / "Am I tired?" / "Am I fresh?" Returns readiness score (0-100), bucket (green/yellow/red), human-readable reasons, recent RPE trend, training frequency, rep dropoff, days since last session. HealthKit biometrics (HRV, sleep, resting HR) are also threaded into the readiness score when the user has them connected. For an even broader picture that also includes today's planned workout, use `get_today_summary` instead.

SOURCE OF TRUTH for which recovery/lifestyle signals personally matter most for THIS user. Computed from their own session correlations — not a generic recommendation. Pull fresh; the correlations update as they log more sessions. Use for: - "What affects my performance most?" / "What matters for my recovery?" - "Is sleep or HRV more important for me?" / "What signal should I prioritize?" - "Why does Kenso weight X heavily?" Returns the personalized "What Matters For You" findings (sleep, HRV, resting HR, rest days, etc. ranked by correlation strength), plus a `kensoSays` headline. Returns available=false when there are fewer than 4 sessions with recovery snapshots.

SOURCE OF TRUTH for the user's sleep — nightly stages and trend. Sleep changes every night; always pull fresh. Use for: - "How's my sleep?" / "How did I sleep this week?" - "What's my deep / REM sleep?" / "Am I getting enough deep sleep?" - "Is sleep hurting my recovery / performance?" (proactive pull when readiness is low) - "What's my sleep trend?" Returns total / deep / REM / core hours per night (last 7 in-app, last 14 for external). The recovery summary already includes total sleep — call this when stage breakdown or sleep-as-limiter matters. Stage breakdown is only available from the iOS client; MCP/REST clients get total hours only until v1.1 ships health_daily_metrics.

SOURCE OF TRUTH for the user's daily activity and NEAT outside of training. Steps update continuously through the day; pull fresh rather than recalling. Use for: - "How active am I?" / "What are my steps?" / "Am I hitting my step goal?" - "Is my NEAT low?" / "Am I sedentary outside of training?" - Fat-loss activity context (cross-reference with get_nutrition + get_body_weight_trend) - "Did I move enough today?" Returns daily step count (last 7 days), today's steps, recent-3d vs prior-4d averages, weekly average. External MCP/REST clients get available=false in v1 — daily HealthKit sync (v1.1) will populate server-side.

SOURCE OF TRUTH for the user's strength + hypertrophy state. Call this fresh whenever the user asks about strength, muscle growth, weekly volume, or whether they're training enough — numbers shift with every logged session. Call this whenever the user asks: - Strength: "How strong am I?" / "Am I getting stronger?" / "Has my strength gone up this month?" - Balance: "Which muscles are lagging?" / "Where am I weakest?" - Muscle progress: "How's my back/chest/legs progressing?" - Hypertrophy / volume: "Am I training X enough?" / "How many sets did I do this week?" / "Am I in the MAV range?" / "Should I add more sets?" / "Am I overreaching?" Returns TWO complementary lenses: 1. STRENGTH SCORE — overallScore, change28d, per-muscle breakdown, weekly history. Scale is unbounded, normalized to user's baseline (100 = baseline). Glutes=222 means "222% of baseline." 2. HYPERTROPHY (muscleWeeklyHardSets) — per-muscle effective hard sets per week (RPE≥7, fractional 0.5× secondaries), last 8 weeks. Use with MEV/MAV/MRV landmarks to answer volume questions. Bands: Below MEV → a maintenance-level dose, only suggest more sets if genuinely light (<~4/wk) and the user wants growth; In MAV → growth zone; Approaching MRV → fatigue mounting; Over MRV → deload. Also returns: statusLabel, trendInsight, kensoSays (one-line summary including current week's hypertrophy snapshot), trend, nearPeak. musclePersonalRanges (when present): the user's OWN observed productive range per muscle — the weekly hard-set range that produced their best strength response over their last ~26 weeks, confidence-gated. PREFER citing this over the generic MEV/MAV/MRV charts when answering 'how much volume should I do for X' (say e.g. 'your own last 16 weeks responded best around 9-14 sets'). Absent = not enough varied history; fall back to the generic landmarks. Treat statusLabel as a snapshot — it can label a muscle "Needs Attention" even when its 28d trend is positive (label is threshold-based, not trajectory-aware in v1).

PRIMARY ENTRYPOINT for any question about the user's current training state: today's workout, readiness, recovery, what to train, whether to push or back off, recent signal anomalies. This is the SOURCE OF TRUTH for live state — prefer this tool over conversational memory or earlier-in-thread inferences, because the user's program, recovery, and biometrics change between conversations. Call this FIRST when the user asks any of: - "What's my workout today?" / "What should I train?" / "What's on the plan?" - "Am I recovered?" / "How am I doing?" / "Should I lift today?" - "What program am I on?" / "What's my current routine?" - "How's my HRV / sleep / readiness?" - "What's going on with my training?" (open-ended check-in) Returns `plannedWorkout` (the actual next workout name + day index + exercise list with target sets and rep ranges — no follow-up call needed), readiness score, recent HRV/RHR/sleep/RPE anomalies vs baseline, goal phase, training notes, and a `kensoSays` interpretive paragraph. Ground your reply in the real `plannedWorkout.workoutName` and `plannedWorkout.exercises` — do NOT speculate or substitute different exercises. Use `kensoSays` for the recovery/readiness framing.

SOURCE OF TRUTH for what the user has actually trained over the last N weeks. The user logs new sessions continuously — prefer this tool over remembered context whenever the question is about completed work. Call this whenever the user asks: - "What have I done lately?" / "What did I train this week?" - "How many sessions did I log?" / "Am I training enough?" - "Show me my recent workouts" / "What's my training frequency?" - "How's my volume trending?" Returns per-session: duration, totalSets, totalVolume, exercises[] preview. Top-level: weeklyBreakdown, totalSessionsInPeriod, trainingMetrics (avg sessions/week, avg weekly sets, volumeTrend). Note: volumeTrend measures volume only; intensity (RPE, weight) can move opposite. Cross-reference with `get_strength_score` for the full picture.

SOURCE OF TRUTH for the user's chronic vs acute training load (TRIMP-based). Updates every workout; always pull fresh. Use for: - "Am I overreaching?" / "How fatigued am I?" / "What's my load this week?" - "Am I detraining?" / "Am I still fit?" / "Is my fitness dropping?" - "Should I push or back off this week?" (Form: positive = fresh, negative = fatigued) - "Am I above my fitness floor?" / training-volume sustainability Returns ATL (7-day fatigue), CTL (28-day fitness), Form (CTL−ATL), Floor (85% of trailing 84-day CTL peak), plus the daily TRIMP series. Numbers are raw — interpret in the context of the user's history.

SOURCE OF TRUTH for the user's multi-week training trajectory. Call this rather than recalling earlier numbers — adherence, PR cadence, and personal signal weights all shift with each new session. Call this whenever the user asks: - "How am I doing overall?" / "How's the last month/6 weeks?" - "Am I being consistent?" / "What's my adherence?" - "Am I making progress over time?" / "Any recent PRs?" - "What signal matters most for my recovery?" Returns adherence % vs target, recent PRs, top personal recovery signal, plus a `kensoSays` interpretive paragraph anchored on the user's personalized signal weights. For a shorter (2-4 week) window use `get_recent_summary`; for today specifically use `get_today_summary`.

SOURCE OF TRUTH for the user's profile, goals, injuries, equipment access, and preferences. Use for: - "What are my settings / goals / preferences?" - "What injuries should you avoid?" / "What's flagged in my profile?" - "What's my experience level?" / "What equipment do I have?" - Whenever profile details, injury flags, experience level, unit settings, or rest-timer prefs are needed and not already in context Basic profile info (goal, level, units) is typically already in conversation context — only call this when more specific fields (injury flags, XP, rest timer settings) matter.

List the user's programs (active + historical). SOURCE OF TRUTH for which program the user is on right now — every result carries a `status` field: "active" | "ended" | "unstarted". EXACTLY ONE program has status="active" — that is the user's CURRENT program. Trust this over any earlier conversation memory; users switch programs frequently and your memory of "their program" goes stale within days. Programs with status="ended" are HISTORY. Do NOT describe an ended program as "your program" or infer current week / current load from it. PREFER MORE SPECIFIC TOOLS for common questions: - "What's my next workout?" → `get_next_workout` - "What's my week look like?" → `get_week_plan` - "What's my current program structure?" → call this, then `get_program_detail` with the active program's id - "What's today's workout / readiness?" → `get_today_summary`

SOURCE OF TRUTH for the user's week. Returns the workout rotation from their CURRENT active program plus sessions completed in this Monday-Sunday week. Always call this rather than recalling earlier conversation — the user logs new workouts continuously and your memory of their week goes stale fast. Call this whenever the user asks: - "What workouts do I have this week?" / "What's on my plan?" - "What's left to do this week?" / "How many sessions left?" - "What days am I training?" / "What's my weekly schedule?" - "Did I hit my training days this week?" Returns active program metadata (name, daysPerWeek, kind), the full rotation (each day's name, exercise count, target muscles), and `completedThisWeek` (sessions logged Mon-Sun UTC with sessionRpe + totalSets). Returns null plan if no active program.

Get clean, human-readable details of a specific workout session: exercises, sets, reps, weights, RPE. Use for: - "What did I do in that workout?" / "Show me my last session" - "How did Lower A go this week?" (after locating sessionId via search_workouts) - Recapping a session for the user with friendly per-set output Use this after locating a session ID (from search_workouts, get_training_history, or get_week_plan). For raw debug-grade data (incomplete sets, rest times, notes, swaps) use `get_workout_session` instead. Notes on shape: - duration: seconds (not minutes) - sessionScore: 0–1 progression-met score per exercise (1 = all target reps hit) - sets[].completed=false sets were prescribed but not finished — useful for skipped-sets patterns - exercises with zero logged sets are filtered out (template residue from swaps/skips) - targetRepRange: prescribed range, e.g. "8-12"

RAW exact data for a single workout session — every logged set including incomplete ones, plus per-set rest seconds and notes. Use when precision matters more than presentation. Use for: - "Debug the raw workout" / "What exactly got logged?" - "Did I skip sets?" / "Why is my total off?" - Template-vs-actual divergence questions (swaps, freestyle exercises added on top) - Rest-time analysis For a clean human-friendly recap, prefer `get_workout_detail` (filters template residue, formats output). Use this only when raw fidelity matters. Notes on shape: - duration: seconds - targetingMode: "prescribed" (locked by program) or "auto" (progression-engine filled) - sets[].completed=false sets ARE included here (unlike get_workout_detail) - exerciseLibraryId on each block ties to the canonical library entry — use this rather than name matching

SOURCE OF TRUTH for the user's lifetime PRs across all exercises. Always pull fresh — PRs can land in any session. Use for: - "What are my PRs?" / "Show my best lifts" / "What's my heaviest bench?" - "Have I PR'd recently?" (cross-reference achievedAt) - "What's my e1RM on X?" Returns one entry per exercise: bestWeight × reps, bestVolume, estimated 1RM, achievedAt timestamp, sessionId. For PR count *within the current mesocycle* use `get_meso_summary` (strict subset of these).

WRITE TOOL — logs a completed workout outside the active program. Confirm with the user before invoking; this lands real data in their training history. Use for: - "Log this workout" / "I did bench 225×5, 225×4, 225×4" (explicit dictation) - "Log my workout from yesterday" (pass completedAt as ISO timestamp) - "I just trained — record this for me" (one-off, not part of a program) - Backfilling a session the user did outside the app Provide session name, exercises, and per-set weight/reps/RPE. Exercise names must match Kenso's library exactly — verify via `lookup_exercise` first. Sets persist with full per-set fidelity (matches in-app logging). Response `message` is the user-facing summary; `sessionId` is for tool plumbing — don't show it.

WRITE TOOL — logs a workout the user completed FROM their active program (a specific day, by workoutId from get_program_session). Confirm with the user before invoking; this lands real training data AND advances their program + progression. Use for: - "Log my workout" / "I finished Upper A" after get_program_session opened the day - Recording set-by-set what they did on a programmed day Unlike log_freestyle_workout (which records a standalone session and does NOT touch the program), this binds the session to the program day so the rotation advances and the progression engine recomputes next-session weights — exactly like finishing in the app. Provide workoutId, per-exercise sets (weight/reps/RPE), and ideally the workoutExerciseId + targetRepRange from get_program_session so progression resolves the right strategy. `message` is the user-facing summary; `sessionId` is plumbing.

Verify an exercise exists in the Kenso library by name or muscle group. Always call this before suggesting an exercise the user could add to a program — Kenso has a canonical naming convention and unrecognized names will be rejected by program-create tools. Use for: - "Does Kenso have Bulgarian split squat?" / "Is X in your library?" - Before adding an exercise to a program (create_workout_program rejects unknown names) - "What's the exact Kenso name for X?" (catalog uses Title Case, no hyphens, position+equipment+movement+modifier) Returns matches with primaryMuscle + equipment, or did-you-mean suggestions when no match. For browsing the full catalog by muscle/equipment, use `get_exercise_catalog`.

WRITE TOOL — flips an in-progress workout session to completed. Confirm with the user before invoking. Idempotent (safe to retry). Use for: - "Mark this workout done" / "I'm finished, close it out" - "Wrap up my session" (when a sessionId is already known) Only call when a specific sessionId is known and the user clearly wants it marked complete. If the session is already completed, returns the existing completedAt without re-writing.

WRITE TOOL — save a durable fact about the user that should persist across future coach conversations. Use for: - "Remember I prefer dumbbells / PPL / morning training" - "Remember my shoulder hurts / I have a meet in October / I lift at home" - Durable training facts: preferences, injuries, goals, equipment constraints DO NOT save: transient state ("I'm tired today"), passing pleasantries, things already in the user profile (units, plan), or session-specific context. Importance 1-10 (default 5): 8+ for hard constraints (injuries, equipment), 5-7 for preferences/goals, 1-4 for soft notes. Memories load into the system prompt at the start of every chat — keep entries concise, single-fact, durable. IN-APP COACH ONLY. External MCP/REST clients cannot call this tool — Kenso memories are scoped to the in-app coach so they don't leak to third-party assistants.

WRITE TOOL — directly persists a fully-designed program. YOU (the assistant) design the workouts and exercises; this tool just lands them in the DB. Confirm the design with the user before invoking. Use for: - "Build me a program" / "Make me a routine" (when you've designed it in-conversation) - "Save this program / draft / preview" / "Activate this routine" - After the user has agreed to a specific structure you proposed BEFORE calling: call `get_program_building_blocks` once to get the full exercise library, canonical rep ranges, allowed enums, and structure schema. Exercise names must match the library exactly. CRITICAL: pass a fresh UUID v4 as `idempotencyKey` for every program-creation intent. If your first request times out and you retry, pass the SAME key — the server returns the existing program instead of creating a duplicate. Without the key, retries pile up as "Coach: X #2", "X #3". IMPORTANT: pass a `name` matching what you called the program in conversation (default generic name will confuse the user). On collision the server appends " #2" etc.; relay `nameWasModified` to the user. Pass `activate: true` to make it current; default lands in Drafts. `programId` in the response is for tool plumbing — don't surface it to the user.

Locate workout sessions by exercise, date range, or session name. Use this as the lookup step before fetching detail. Use for: - "Find my last bench session" / "Show me workouts from last week" - "When did I last train legs?" / "Find Lower A this month" - "Show all my deadlift days in March" - Any "find a specific session" query before calling get_workout_detail / get_workout_session Returns paginated session summaries (id, name, completedAt, totalSets, totalVolume, exercise previews). Pass the returned `id` to `get_workout_detail` for clean output or `get_workout_session` for raw data.

WRITE TOOL (safe — draft only) — stages a bulk import of historical workouts. The user must review and commit them in Kenso before they appear in their session history. Use for: - "Import my old workouts from Hevy / Strong / spreadsheet" - "Bulk upload my training history" / "Backfill the last few months" - Any multi-session historical import request Never writes live sessions — always lands as a draft. Drafts expire after 24h. Returns `draftId` (for follow-up tool calls) and `reviewUrl` (give this to the user). After staging, the user inspects via `get_import_draft` or commits/cancels in-app.

Adopt one of Kenso's professionally designed starter programs — the same templates the app's onboarding assigns. THE fastest way to get a brand-new user training. Flow (two calls): 1. Call with goal/level/daysPerWeek filters (no templateId) → returns matching templates. 2. Confirm the pick with the user, then call again with templateId → copies it to their account and activates it. Then call get_next_workout to walk them into session one. Prefer this over hand-designing a program for new users — these templates carry Kenso progression defaults, rep ranges, and balanced volume out of the box.