evertrain

Returns the authenticated user's durable coaching facts: movement_restriction, preference, and current_phase entries, grouped by type. By default returns only CURRENT facts (still true today). Pass as_of (an ISO date, YYYY-MM-DD) to see the historical view as of that date, including since-superseded records that were valid then. Pass type to filter to a single fact type. Also returns pendingProposals — the count of the user's open pending proposals awaiting in-app confirmation, so you can remind them to review if it's non-zero. This is read-only awareness; this tool cannot write or propose anything.

get_coaching_facts

Returns daily notes (body metrics, cardio, sleep, mood) for a date range. body_weight is parsed from '75|kg|08:30 AM' → { value, unit }; body_fat from '18.5|08:30 AM' → { value }. Trailing time segments are stripped.

get_daily_notes

Returns exercises from the catalog visible to the user (default exercises + user's own). All enum filters take camelCase enum KEYS, matched exactly (in-memory): bodyRegion (one of: chest, back, shoulders, arms, legs, core), movementType (one of: bilateral, unilateral), equipment (a single value, one of: dumbbells, smithMachine, ankleWeights, medicineBall, machines, barbell, kettlebells, step, powerbands, resistanceBands, fitball, landmineAttachment, trapBar, trx, abWheel, plyoBox, battleRopes, stepper, crossTrainer, treadmill, bike, bosuBall, boxingGloves, chains, rower, skippingRope, sled, thickGrips), muscles (a list of camelCase muscle keys, each one of: calves, gastrocnemius, anteriorDeltoids, deltoids, elbowExtensors, pecMajor, pecs, elbowFlexors, medialDeltoids, brachialis, gluteMaximus, glutes, traps, upperTraps, hamstrings, abdominals, core, obliques, bicepLongHead, bicepShortHead, quads, rectusFemoris, vastusLateralis, vastusMedialis, gluteMedius, lats, rotatorCuff, shoulderExternalRotators, transverseAbdominis, adductors, brachioradialis, forearms, posteriorDeltoids, pecMajorClavicle, tricepLateralHead, tricepLongHead, tricepMedialHead, lowerTraps, midTraps, hipExternalRotators, hipRotators, pecMajorSternal, lowerBack, gluteMinor, soleus, shoulderInternalRotators, pecMinor, latThoracic, latLumbar, latIlliac, erectorSpinae), exerciseType (one of: resistance, cardio), and measurementType (one of: repetitions, time). The modality filters (exerciseType/measurementType) match only exercises that declare that field — an unclassified exercise is not returned by a modality filter. Default limit: 50. Each entry MAY carry exerciseType ("resistance"|"cardio") and measurementType ("repetitions"|"time") when the exercise has been classified — these two fields tell you which set-spec shape to author: a "time" or "cardio" exercise wants a `duration` set-spec (no reps needed); a "repetitions" exercise wants a `reps` set-spec. When absent, the exercise is unclassified and either shape is accepted by create_program/create_workout.

get_exercise_library

Reads a program TEMPLATE (blueprint layer) — the reusable plan, NOT the user's scheduled calendar (use get_scheduled_calendar / get_training_history for calendar days). Returns the program document with all associated workout documents resolved: trainingBlocks, goal, focus, equipment, and the full workout exercise groups with plain-string reps (no pipe format). Each workout includes `description` when one was set (the coach-authored context note visible to the athlete before they start the session). Sets are presented in the compact count form: runs of identical physical sets read as one spec with `sets: N` — the same shape create_program accepts. A set is rep-based (a `reps` key, e.g. '6-8'), timed (a `duration` key in seconds, no `reps` key), or both. Caveat: legacy documents may report counts above 15 (create_program's cap).

get_program

Returns the user's UPCOMING scheduled calendar days for a date range — the live forward plan with completion status, NOT the completed-log history (use get_training_history for past logs). startDate defaults to today, endDate to a 4-week forward window. Each day carries clean programId/workoutId/date join keys and a completed flag so the AI can target not-done sessions. Completed days in the window are included with completed:true — the AI decides which ones to act on. Applies the same visibility rule the app itself applies: a day is only omitted if its programId is not present at all in the user's calendar root (fully deleted / never-scheduled). A previous run's day after a program restart, and days belonging to an archived program, are still returned — the human user sees them too. The response's `hidden` field reports how many entries were dropped as orphans ({orphans}) — this is never silent.

get_scheduled_calendar

Returns the user's training history (live calendar layer) for a date range, as a list of days. Each day has a clean array of scheduled program-days carrying programId and the day's date (dayMs), with workoutId on each workout inside — the raw composite storage key is never exposed. Set fields (reps, rest) are parsed from pipe format into { planned, actual } objects; rir is a separate integer; rpe = 10 - rir is computed. No raw pipe strings in the response. Applies the same visibility rule the app itself applies: a day is only omitted if its programId is not present at all in the user's calendar root (fully deleted / never-scheduled). A previous run's day after a program restart, and days belonging to an archived program, are still returned — the human user sees them too. The response's `hidden` field reports how many entries were dropped as orphans ({orphans}) — this is never silent.

get_training_history

Returns the authenticated user's training profile: first name, age, role, isOnboarded (computed from 4 onboarding sub-objects), personal stats, training experience, and facility/schedule preferences. Does not include contact details or account identifiers. accessToFacilities.facilities is one of: 'fullGym' (a fully-equipped gym — barbells, racks, machines, and cables), 'limitedEquipment' (free weights and a bench, but no machines or cables — e.g. a home or garage setup), or 'noEquipment' (bodyweight only, typically training at home or outdoors). Program the user's available movements accordingly.

get_user_profile

Lists the user's program TEMPLATES (blueprint layer) available to the authenticated user (from users/{uid}/available_programs) — the plans they can view or schedule, not their calendar days. Each entry includes programId, name, and imagePath.

get_user_programs

Reads a single workout TEMPLATE (blueprint layer) — the reusable plan, not a scheduled calendar day. Returns the workout document with exercise groups and sets. Includes `description` when one was set (the coach-authored context note visible to the athlete before they start the session). Set reps are plain strings (e.g. '6-8') — no pipe format on the blueprint side. Sets are presented in the compact count form: runs of identical physical sets read as one spec with `sets: N` — the same shape create_workout accepts. A set is rep-based (a `reps` key, e.g. '6-8'), timed (a `duration` key in seconds, no `reps` key), or both. Caveat: legacy documents may report counts above 15 (the write-side cap).

get_workout

CALENDAR-layer mutation of the live plan: inserts an empty REST week after afterDate by shifting every scheduled day strictly after that date forward exactly 7 days. Days with any logged training are NEVER moved — a logged day after afterDate refuses the insert. The gap is created EMPTY and STAYS empty: no tool can place a new session on a new calendar date (create_workout only edits the template; update_future_workout needs a day doc that already holds the workout). You may move an existing scheduled day into the gap with reschedule_workout. If the user wants a lighter week rather than none, author a block with create_program + schedule_program instead. Not idempotent — calling twice inserts two weeks. Returns { success: true, movedDays } on success.

insert_week

Health-check tool. Returns {pong:true}. readOnly, idempotent.

ping

Publishes a daily AI activity card summarising this session. Provide a headline (≤80 chars) and rationale (≤2000 chars) describing what you accomplished and why. The changes[] list is derived automatically from the server's record of this token's write operations today — do NOT supply a changes field. An empty changes list is valid (reasoning-only sessions). Same-day calls revise the card; prior versions are preserved in history. Returns { success: true, dayMs } on success, or a structured error object on failure.

post_activity

STAGES a current-training-phase proposal for the user to confirm in-app (e.g. 'hypertrophy block 2/4', 'deload week', 'peaking for a meet'). This does NOT commit anything — it only queues a pending item; the fact only becomes real coaching context after the user explicitly confirms it in the app. Propose SPARINGLY: only when the training phase has genuinely changed — not every session. Bias strongly toward NOT proposing; an empty pending queue is the win condition, not a failure. phase is a short label (max 64 chars); rationale is an optional short explanation (max 280 chars). There is only ever ONE current phase — confirming this proposal will retire the previous current phase fact, if any (would_supersede reflects that when applicable). Returns { success: true, proposal_id, would_supersede, expires_at } — would_supersede is null or { fact_id, summary } describing the current phase this would retire on confirmation.

propose_current_phase

STAGES a training-preference proposal for the user to confirm in-app. This does NOT commit anything — it only queues a pending item; the fact only becomes real coaching context after the user explicitly confirms it in the app. Propose SPARINGLY: only durable, programming-relevant preferences the user has clearly stated (e.g. 'I always want to superset arms' or 'I dislike running') — not a one-off mood comment. Bias strongly toward NOT proposing; an empty pending queue is the win condition, not a failure. text is freeform (max 280 chars) since preferences are consumed by the brain, not executed by the app. Optional tags reference equipment the preference relates to. Preferences are ADDITIVE — this never supersedes an existing preference (would_supersede is always null). Returns { success: true, proposal_id, would_supersede: null, expires_at }.

propose_preference

STAGES a movement-restriction proposal for the user to confirm in-app. This does NOT commit anything — it only queues a pending item; the fact only becomes real coaching context after the user explicitly confirms it in the app. Propose SPARINGLY: only durable, programming-relevant restrictions the user has clearly stated (e.g. a real injury or a hard no-go movement) — not passing comments, not every mention of soreness. Bias strongly toward NOT proposing; an empty pending queue is the win condition, not a failure. Provide at least one of exclude_exercise_ids (catalog exercise ids) or exclude_body_regions (chest|back|shoulders|arms|legs|core). An unknown exercise id is rejected and nothing is staged. Do not include diagnosis, cause, or medical detail — only the training consequence (what to avoid) and an optional short note. Returns { success: true, proposal_id, would_supersede, expires_at } — would_supersede is null or { fact_id, summary } describing the current restriction this would retire on confirmation.

propose_restriction

CALENDAR-layer mutation of the live plan: moves a single not-yet-completed workout from one calendar day to another. The workout to move is identified by its REQUIRED instanceId (the per-instance id from a get_scheduled_calendar read — the read-then-write flow); two workouts scheduled from one template share a workoutId but have distinct instanceIds, so instanceId (never workoutId) selects the instance. workoutId is validation context — a mismatch with the located instance is rejected with code:'invalid_argument'. toDayMs is the date you are naming, so it must be a UTC-midnight epoch-ms day-doc id (as returned by get_scheduled_calendar); non-midnight values are rejected, never rounded. toDayMs must also be on/after the program's scheduled start date — a date before it is refused with code:'before_program_start', because the app never renders pre-start days (pick a later date, or re-schedule the program at the earlier start). fromDayMs is a handle on a day doc that already exists and stays permissive — that is what lets you move a legacy non-midnight day onto a clean date, the recovery calendar_day_misaligned asks for. The move is transaction-atomic — the logged-set check and both writes are serialized, so a set logged while the move is in flight can't be lost. Rejects if the slot or workout is completed (immutable), and rejects a workout with ANY logged set (workout_has_logged_sets, naming loggedSets) — logged training is NEVER relocated to a date it wasn't performed. To move such a day anyway the user must explicitly agree to DISCARD the partial log: retry with force: true and confirmLoggedSets echoing the refusal's exact count; the actuals are then reset and the clean planned workout moves. If the partial is worth keeping, leave the day in place and author the session fresh on the target day instead. Returns { success: true, instanceId } on success — instanceId is the moved workout's resulting id (re-minted if it collided on the target day), so you can keep addressing it without a re-read.

reschedule_workout

Materializes a program TEMPLATE onto the user's actual CALENDAR (calendar layer), starting from the given date. This is what STARTS a program: it writes calendar day documents for all workout slots in the program's training blocks — until you call this, a created program is just an un-started template that puts nothing on the user's calendar. The program must be accessible to the user (owned, purchased, or in store). Day keys are weekdays, not offsets: day1=Monday…day7=Sunday, and each dayN lands on the NEXT occurrence of that weekday on or after startDate — a start date that doesn't match the program's first day key rolls forward (a Wednesday start on a day1-led program trains nothing until Monday), so tell the user when their first session actually is. Re-scheduling the same program replaces its PRISTINE planned days only: any slot that already holds logged training — even a single logged set — is kept, and its date is returned in preservedDates. A date can be in preservedDates and still have other, pristine slots on it rescheduled, so relay it as 'kept your logged sessions on these dates', not 'these whole days were untouched'. If the program is CURRENTLY ACTIVE (already scheduled with at least one future, not-completed day of that run remaining), this call is refused with code:'program_already_scheduled' and no write — re-scheduling an active run would strand its remaining days. Tell the user to quit or archive the active run first, or let it finish, then re-schedule. startDate must be this week's Monday (UTC) or later — a fully-past start is refused with code:'start_date_in_past' and no write, since it would schedule days born already-missed. An ARCHIVED program is refused with code:'program_archived' and no write — tell the user to unarchive it first with archive_program {unarchive:true}, then schedule. A program whose training blocks reference no workout under any day key has nothing to schedule and is refused with code:'nothing_to_schedule' and no write — add workouts to the training blocks first. Returns { scheduledDays, preservedDays, preservedDates } on success, plus a non-fatal `warnings` array (rule + message) when the schedule wrote successfully but degraded in a way worth relaying: a dangling workout reference scheduled as an empty session, an exercise ID with no catalog name (shown as a raw ID), or the app-library journal entry failing to write (program may not appear in the user's list until refreshed). If this program was previously scheduled at a DIFFERENT start date (a finished or quit run — an ACTIVE run is refused above, not silently moved), the response also includes `previousRun: {startDate, loggedDates}`: the earlier run's start date and the dates it holds logged training on. Those logged days still render on the calendar and in get_training_history, but no longer count toward this new run once this call moves the start pointer — tell the user their old logged sessions are still there, just detached from the new run.

schedule_program

CALENDAR-layer mutation of the live plan: pushes a contiguous block of the program's upcoming scheduled days forward or back by ±N days (travel, illness). Anchors at the first not-yet-completed day on or after fromDate and moves that contiguous run; days with any logged training are NEVER moved. Refuses (with a structured code) if a logged day sits inside the range, a moved day would land on an occupied date for the same program, or a backward shift would overlap logged history or land before the program's scheduled start date. NOTE the shift is not bounded by today: a backward shift can land days in the past, and a program left with no day after today disappears from the app's Current Programs while its days still show on the calendar. This is surfaced structurally: a successful shift that leaves the program with no unlogged day strictly after today returns programStillCurrent: false — tell the user rather than assuming the tool prevents it. Call get_scheduled_calendar first to confirm the live schedule. Not idempotent — calling twice shifts twice. Shifts spanning more than ~249 days commit in multiple batches (typical programs are atomic). On any failure read the flags before acting: retryable: true means the write provably never started (safe to retry); partial: true with committedDays means that many days ARE moved; outcomeUnknown: true means the write was in flight and may or may not have landed. For the last two, re-read get_scheduled_calendar and re-plan from what you see — never retry blindly. Returns { success: true, movedDays } on success, plus programStillCurrent: false when applicable.

shift_from

Submits a problem-first feature request to the Evertrain product owner when you (the agent) hit a capability gap — a tool that doesn't exist, a field that isn't exposed, a workflow you cannot complete. Use this INSTEAD of simply telling the user you can't do something. Describe the GAP, not just a solution: provide userGoal (what the user was trying to accomplish), situation (relevant context about the user — training phase, program, goal), currentLimitation (what specifically cannot be done today), and desiredOutcome (what success would look like). proposedSolution is optional and secondary — only include it if you have a concrete, well-formed suggestion. contactConsent must reflect whether the user has EXPLICITLY agreed to be contacted about this request; do not assume consent. Submissions are rate-limited to one per user per topic per 24 hours — resubmitting the same underlying problem within that window is rejected. Returns { success: true, requestId } on success, or a structured error object. The request is still persisted even if the owner's Slack notification fails to send — that failure surfaces as warnings: [{rule: 'slack_notification_failed', message}] alongside success:true (the same {rule, message} shape create_program and schedule_program use), since Slack is the triage surface and the request may otherwise go unseen.

submit_feature_request

Replaces one exercise slot on a single future calendar day. The workout to act on is identified by its REQUIRED instanceId (the per-instance id from a get_scheduled_calendar read — the read-then-write flow); two workouts scheduled from one template share a workoutId but have distinct instanceIds, so instanceId (never workoutId) selects the instance. workoutId is validation context — a mismatch with the located instance is rejected with code:'invalid_argument'. Provide programId, dayMs (UTC-midnight epoch-ms from get_scheduled_calendar), instanceId, workoutId, group (the group's key as returned by get_scheduled_calendar — a minted numeric-string index such as '0', '1', '2', NOT a letter), oldExerciseId (the exercise to replace), and newExerciseId (the replacement, resolved server-side from the exercise catalog). For same-type swaps (reps→reps or time→time): planned reps/duration and rest are preserved; logged set data (weight, actual reps, RIR, completed) is cleared since the movement has changed. Do NOT supply 'sets' on a same-type swap — it is rejected with code:'invalid_argument' since a same-type swap always preserves the existing planned values. For cross-type swaps (repetitions↔time): you MUST supply a 'sets' array (one entry per set) specifying reps (string, e.g. '10') or duration (seconds, integer) for the new exercise type. Omitting 'sets' on a cross-type swap returns code:'invalid_argument'. Single-day scope only — does NOT propagate to other calendar days or the program template. Rejects with code:'immutable' if the slot or workout is completed, or if any set in the target exercise has logged data. Rejects with code:'duplicate_exercise' if newExerciseId is already present elsewhere in the same group — substituting would create two entries with the same exercise; pick a different exercise or remove the existing one first. Rejects with code:'not_found' if oldExerciseId is not in the named group (calling twice is safe — the second call returns not_found without writing). Returns { success: true }.

substitute_exercise

CALENDAR-layer merge-patch of one not-yet-completed workout on the live plan. The workout is identified by its REQUIRED instanceId (the per-instance id from a get_scheduled_calendar read — the read-then-write flow); two workouts scheduled from one template share a workoutId but have distinct instanceIds, so instanceId (never workoutId) selects the instance. workoutId is validation context — a mismatch with the located instance is rejected with code:'invalid_argument'. dayMs is the UTC-midnight epoch-ms day-doc id (from get_scheduled_calendar). Rejects if the workout is completed, and rejects STRUCTURAL patches (setPatches/groupPatches) once the workout has any logged set — logged training is never restructured or truncated; name/notes edits remain allowed on a started session. Changes are additive — only provided fields are updated. Returns { success: true }, or { success: true, unchanged: true } when a name/notes-only request (no setPatches/groupPatches) already matched the stored workout — no write occurred and no activity-feed entry was created for it.

update_future_workout

Edits a program TEMPLATE (blueprint layer) owned by the user — for NEVER-SCHEDULED programs only (rename/retune before go-live). Uses merge semantics — only provided fields are changed; unmentioned fields are preserved. Once a program has been scheduled onto the calendar this tool is rejected with code 'scheduled_program': the calendar is then the single source of truth, and structural changes to the live plan happen on the calendar layer via update_future_workout, shift_from, insert_week, or append_week. Returns { success: true } on success, or { success: true, unchanged: true } when every requested field already matched the stored value — no write occurred and no activity-feed entry was created for it.

update_program