Kenso

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?" / "What have I eaten today?" - "How's my protein intake?" / "Am I hitting my macros?" - "Is my cut / bulk on track?" / "Am I in a deficit?" - When fueling could explain a recovery or performance dip Reads the user's Kenso food diary. Returns today so far (totals, the user's target, and each item logged with its meal slot), yesterday, and 30-day and 7-day daily averages over the days that have logs (with how many days were logged in each window). With `date`, also returns that day's totals and items as `day`. `lastReview` is Kenso's latest weekly target review; explain it, never invent a target. Returns available=false when the user has not logged food — mention once and move on. log_food records food. Requires Kenso Pro.

get_nutrition

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`.

get_program_building_blocks

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.

get_program_detail

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`.

get_recent_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.

get_recovery_status

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.

get_signal_insights_summary

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?" - "What's my sleep trend?" Returns total hours per night with deep / REM / core hours when the source reports stages (last 7 nights in-app, last 14 for connectors), the average, and `stages` saying whether any night carries a stage breakdown. The recovery summary already includes total sleep — call this when the breakdown or sleep-as-limiter matters. Data comes from the Kenso iPhone app (Apple Health) or a connected Oura/Whoop account; users with neither get available=false and a message saying so.

get_sleep_detail

SOURCE OF TRUTH for the user's daily activity and NEAT outside of training. Steps update 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 counts for the last 7 days, the latest day's steps, recent-3-day vs prior-4-day averages and the weekly average. Data comes from the Kenso iPhone app (Apple Health) or a connected wearable; users with neither get available=false and a message saying so.

get_steps_trend

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.

get_today_summary

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.

get_training_history

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.

get_training_load

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.

get_user_profile

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`.

get_trend_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_week_plan

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"

get_workout_detail

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

get_workout_session

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).

list_personal_records

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`

get_user_programs

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.

log_freestyle_workout

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.

log_program_workout

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`.

lookup_exercise

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.

mark_workout_completed

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 compiled plan's `suggestedWeight`/`suggestedReps`/`suggestionReason` plus per-set `targetWeightBySet`/`targetRepsBySet` and `progressionAction` — the same next-session numbers the app's logger paints, 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).

get_program_session

WRITE TOOL — record a workout the user describes loosely ("did legs for 40 minutes, pretty hard", "upper body yesterday") when they did NOT give exercises with sets, reps and weights. Logs which muscle groups they trained, roughly how long and how hard. It counts toward their weekly muscle volume but not toward PRs or progression. Confirm the muscle groups with the user before calling. Prefer log_program_workout when it matches a day of their program and they gave sets, and log_freestyle_workout when they listed exact exercises with sets. Returns `outcomes` (each muscle's weekly sets before and after, against its target) — tell them in one line what this did for their week.

quick_log_workout

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.

save_program_structure

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.

search_workouts

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.

stage_workout_import

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.

start_starter_program

WRITE TOOL — generates a complete workout program preview and persists it. Requires explicit user agreement before invocation. Use for: - "Build me a new program" / "Make me a routine" / "Generate a program" - "I want to start a new mesocycle / block" - After gathering goal, level, days per week, and split (do NOT call before) Prerequisites: confirm with the user — goal (Strength / Hypertrophy / Athletic / Fat Loss / General Fitness), experience level, days per week, preferred split, progression strategy. If recommending specific exercises in the conversation, pass them via `specificExercises` so they're locked in. Use canonical Kenso names (verify via `lookup_exercise` first) — unknown names are rejected.

Kenso's synthesized COACHING REPORT — strength trajectory, per-muscle weekly volume vs MEV/MAV/MRV landmarks, readiness, adherence, and recent PRs, plus prioritized recommendations computed by Kenso's coaching engine. Call this whenever the user asks: - "How am I doing?" / "Give me my weekly report" / "Coach me" - "What should I change?" / "What should I focus on?" - "Review my training" / "Any red flags?" Present the recommendations in priority order (high → low) and use the underlying data to explain each one. This is a Pro tool: if it responds proRequired, relay the upgrade path it describes.

SOURCE OF TRUTH for the user's HRV trajectory. HRV shifts daily; always pull fresh rather than recalling. Use for: - "How's my HRV?" / "Is my HRV trending up or down?" - "Am I chronically stressed?" / "Is this fatigue acute or chronic?" - "Is autonomic recovery limiting me?" - Reasoning about whether one bad day is acute (1-day dip) or chronic (multi-week trend) Returns morning-median HRV daily for the last 14 days (in-app) / 30 days (external), plus recent-7d vs prior-7d averages. External clients derive from recovery snapshots (per-workout-day granularity) until v1.1 health_daily_metrics ships.