Joules

<usecase> Returns the athlete's CTL (fitness), ATL (fatigue), TSB (form), and daily load as a time series across a window — one point per calendar day. Use this whenever the user asks about a trend ("how has my fitness changed", "am I building or losing fitness", "what's my fitness trajectory"). The summary includes start/end CTL, peak CTL, and the net change so you can cite real deltas instead of inferring them from the latest snapshot. When called with `endDate` alone, the window is anchored to that date instead of today — used to reconstruct fitness state going into a past event. Pass `startDate` + `endDate` together for a precise calendar range (training blocks, seasons). Optionally request a comparison series in the same call to answer year-over-year or block-over-block questions. </usecase> <instructions> Range inputs (pick one style): omit both for a rolling window ending today; pass `endDate` alone with `window` to anchor a rolling window's end to a past date (use the activity's startDate from `findActivities` to answer "what was my fitness going into <event>" — pair with `eventLabel` for an event marker); pass `startDate` + `endDate` together for an explicit calendar range (do not also pass `window`). Comparison inputs (pick at most one): `comparisonStartDate` + `comparisonEndDate` for an explicit comparison range; `comparisonMode: "same_dates_previous_year"` for the identical calendar dates one year earlier; `comparisonWindow: "previous_<28d|90d|180d|1y>"` for the block of that length immediately preceding the current range. When a comparison is requested, `data.comparison` holds its window + points and `summary` carries the comparison-aware deltas (`comparisonCtlDelta`, `ctlDeltaVsComparison`, `comparisonTotalLoad`, `totalLoadDeltaVsComparison`). For any anchored response (a call with `endDate`), `summary.eventSnapshot` reports both `preEvent` (end-of-day stats from the day BEFORE the anchor — the true going-in state) and `postEvent` (end-of-day stats ON the anchor day, including that day's load). Use `preEvent` when reasoning about how the athlete entered the day. Days with no training-load data are omitted (no zero-padding). If `summary.pointCount` is 0 the athlete has no fitness history in the current range — say so and stop. </instructions>

getFitnessHistory

<usecase> Opens a weekly-planning conversation. Returns the planning system prompt, the previous week's actuals for opening the conversation, the target week's bounds and TSS target, which days are off-limits because they're already completed or time-off, scheduled races to plan around, and the season-block context. Read-only — no server-side session is created; the conversation itself carries the draft state until you call `buildWeek` to persist a committable proposal. </usecase> <instructions> `weekOf` is optional — pass a YYYY-MM-DD inside the desired ISO week and the tool snaps to Monday. Default is the upcoming planning week (Mon–Thu → this Monday, Fri–Sun → next Monday). Requires the `joules.write` OAuth scope and an active Joules subscription. Always start the conversation by reading the `previousWeek` field and acknowledging what the athlete actually did before asking what's different this week — do not skip that step. `buildWeek` takes `weekStart` as a parameter; you can pass the same `weekStart` returned here. </instructions>

getPlanningContext

<usecase> Returns the athlete's mean-max power curve — best average watts at standard durations from 5 seconds to 3 hours — over a window, plus the latest fitted CP/W' model. Optionally returns a second curve for any chosen comparison range so a single call can answer "how does my power profile compare to <this time last year | the prior block | a specific season>". Also supports the durability read: pass `afterKj` as an array of cumulative-work thresholds (any of 1000, 2000, 3000 alongside the default 0) to compare fresh and fatigued curves in a single call — "how does my 5-min power hold up after 2000 kJ of riding?". Use to answer "am I getting stronger", "where am I improving", or "how durable am I". </usecase> <instructions> Range inputs (pick one style): omit `startDate`/`endDate` for a rolling window via `window` ("28d", "90d" default, "180d", "1y", "all"); pass `startDate` + `endDate` together for an explicit calendar range (do not also pass `window`). Comparison inputs (pick at most one): `comparisonWindow` (legacy) for the immediately preceding block of that length; `comparisonMode` for a named helper — "previous_period" (same length as current, immediately preceding), "same_dates_previous_year" (identical calendar dates one year earlier), "same_calendar_month_previous_year" (the calendar months the current range overlaps, one year earlier), "custom_range" (requires `comparisonStartDate`+`comparisonEndDate`); or `comparisonStartDate`+`comparisonEndDate` directly. When a comparison is returned, both `current` and `comparison` carry their own `cp` (the most recent fitted CP/W' model at or before that range's end), and `summary.criticalPowerDeltaWatts` is current.cp − comparison.cp. `summary.pointCount` of 0 means no power-meter rides in the current range — say so directly. CP/W' fields are null when the athlete has no fitted model in that period. Pass `afterKj: [0, 2000]` (or `[0, 1000, 2000, 3000]` for the full spread) for durability: each entry of the array becomes one curve in `data.curves`, sharing the same date window. `data.current` mirrors `data.curves[0]` so existing readers continue to work. When the request includes threshold 0 alongside at least one fatigued threshold, `summary.durabilityDelta` reports retention at the anchor durations (5s/1min/5min/20min/60min). A low `pointCount` for a fatigued threshold means the athlete has done few rides past that much accumulated work. </instructions>

getPowerProfile

<usecase> Returns the athlete's rider phenotype — sprinter, puncheur, diesel, or all-rounder — together with strength/limiter flags for the five canonical duration buckets (sprint, anaerobic, VO2, threshold, durability). Use this to tailor reads and recommendations to the kind of cyclist the athlete actually is: a sprinter and a diesel rider need very different training emphases even at the same FTP. `summary.topStrengths` and `summary.topLimiters` are the quick-reference lists for prose answers; `data.buckets` carries the per-duration ratios behind the classifications. </usecase> <instructions> No inputs. Profile is derived from the athlete's current mean-max power curve over the last 90 days; falls back to all-time when 90 days is too sparse. `summary.hasEnoughData` is false when fewer than 3 standard durations have a best effort even after the fallback — in that case `data.phenotype.type` is null and the model should say so plainly. `data.phenotype.confidence` is "high"/"medium"/"low" (bucketed from the underlying 0–1 score, which itself discounts when anchor durations are missing). `summary.powerCurveWindow` echoes "90d" or "all" so the model knows which window the read used. For the underlying watts at each duration, follow up with `getPowerProfile`. </instructions>

getRiderProfile

<usecase> Returns the athlete's training program settings (name, notes, principles, available days) plus the live plan — blocks in calendar order, each with its phase, week range, coach notes, and the per-week intent + load target (TSS) that defines the ramp. The shared planContext (current week position, current block, racing season, taper flag) rides on every plan-tool response, so call `getPlan` only when you need the deeper view: full block structure, full ramp, program-level settings. For one week's prescribed training, call `getTrainingWeek` instead. </usecase> <instructions> No arguments. The plan is implied by the authenticated athlete. When `summary.hasPlan` is false, the athlete hasn't set one up yet — direct them to call `setPlan` (or use the planning-session flow). `data.plan.blocks[]` is ordered first-to-last; each block's `startWeek`/`endWeek` are 1-indexed inclusive bounds into the plan, and each week carries `weekStart` (Monday YYYY-MM-DD — the natural key under the new schema), `intent` (base/build/recovery/peak/taper), and `targetLoad` (TSS). Each block exposes `id` (e.g. `blk-42`); pass it to `updateBlock` to rename the block, change its phase, or refresh its notes. Per-week TSS edits go through `setPlan`. </instructions>

getPlan

<usecase> Returns one ISO week (Monday–Sunday) of *prescribed* training keyed by the week's Monday: each day's events (workouts, races, vacation/sick/ injured days) with planned load, intensity, focus, and the interval structure for each workout inline. The week is identified by `weekStart` (the natural key under the new training data model — the `(app_account_id, week_start)` pair on `training_weeks`). The shared planContext (current block, racing season, taper flag) rides on every response. Use whenever the athlete asks "what's on this week", "what's left", "walk me through Thursday's session", or to read a specific session before discussing whether to do it. </usecase> <instructions> `weekOf` is required and must be a YYYY-MM-DD inside the desired ISO week — the tool snaps to the Monday. Resolve "this week" / "last week" against the briefing's current-date context before calling. Any week overlapping the live plan is fair game (past, present, future); weeks outside the plan return `summary.hasPlanWeek: false` (the request is still served — the day-by-day events still appear, just without the plan-level fields). `includeNonWorkoutEvents` defaults to true so races and time-off days appear on the calendar — set false only when the athlete asked specifically about workouts. For the actual ride on a completed workout, follow up with `getActivityDetail` using `linkedActivity.activityId`. For aggregate completed-side comparison, call `getWeekSummary` for the same week. Numbers belong in charts — describe the week qualitatively in prose. </instructions>

getTrainingWeek

<usecase> Returns one ISO week (Monday–Sunday) of training: per-day load and ride count, weekly totals (load, moving time, rides, average IF), the start/end CTL/ATL/TSB snapshot, and the prior 4-week mean for comparison. Use whenever the user asks about "this week", "last week", or a specific week. </usecase> <instructions> `weekOf` is required and must be a YYYY-MM-DD inside the desired ISO week — the tool snaps to the Monday. Resolve "this week" / "last week" against the briefing's current-date context before calling. The `priorMean` block is computed from the 4 weeks immediately before the requested week; `summary.loadDeltaVsPriorMean` is null when no prior data exists. For drill-in on individual rides, follow up with `findActivities` filtered to the same date range. </instructions>

getWeekSummary

<usecase> Returns the athlete's time-in-zone distribution summed across all rides in a window — 7-zone power and 5-zone HR. Use this whenever the user asks how polarized their training has been, whether they're spending enough time in Z2, whether they're doing too much threshold work, or whether the distribution is appropriate for where they are in the training block. `polarizationRatio` is (Z1+Z2) / (Z5+Z6+Z7) by time on the power axis: a high ratio indicates polarized training, a low ratio indicates threshold-heavy training. Pair the read with the athlete's own training phase context — the appropriate distribution differs across base, build, and peak. </usecase> <instructions> Range inputs (pick one style): omit both for a rolling `window` ending today (default "90d"); pass `startDate` + `endDate` together for an explicit calendar range. Sport filter: pass `sport` (a single canonical activity type, e.g. "MountainBikeRide", or an array of them) to scope to specific disciplines. Omit `sport` to scope to the canonical "all ride" bucket — MTB / gravel / virtual surface alongside road. Power and HR aggregates are independent: a ride that has FTP-derived zones contributes to power even if it has no HR signal, and vice versa. `data.power` is null when fewer than 3 rides in the window carry power-zone data — `summary.hasEnoughData` reports the same flag. `data.hr` follows the same gate at 3 rides. `polarizationRatio` is null when the high-intensity bucket (Z5+Z6+Z7) is zero or when power data is sparse. `summary.dominantZone` is the highest-share power zone (or HR zone when power is unavailable). For drill into a single ride, follow up with `findActivities` filtered to the same window and `getActivityDetail` on the ride id. </instructions>

getZoneDistribution

<usecase> Records a stretch of time off (vacation, sick, or injured) on the athlete's calendar from `from` to `to` inclusive, and soft-deletes any non-completed workouts already scheduled inside that range — the calendar reflects the truth immediately. Use when the athlete reports they'll be away or unable to train, or when they're returning from a period off and want it logged retroactively. </usecase> <instructions> `from` and `to` are YYYY-MM-DD calendar dates (UTC); `to` must not be before `from`. Single-day off → pass the same date for both. `type` is one of `vacation`, `sick`, `injured`. `notes` is an optional short label shown on the calendar; defaults to the capitalized type. Idempotent on the same range — repeating the call returns the same `eventId` with `wipedWorkoutCount` of 0. Overlapping ranges of the same type are merged into the existing event rather than duplicated. Completed workouts are never touched. </instructions>

markTimeOff

<usecase> Surfaces a week built by `buildWeek` to the athlete as a week-preview card with an Accept button. Takes only the `proposalId`; the committable draft already lives server-side. Call this once the draft is in tolerance — it is the step that actually shows the athlete the plan. The card's Accept button commits directly, so no further model turn is needed. </usecase> <instructions> `proposalId` is the `wp_…` token returned by `buildWeek`. Present only a pending proposal; a superseded/expired/committed draft is refused — rebuild with `buildWeek` first if needed. </instructions>

presentWeek

<usecase> Removes a race from the athlete's calendar (soft-delete). Pair with `addRace` when an athlete cancels a signup or signed up to the wrong event. Refuses to delete completed races — those are part of training history. </usecase> <instructions> `eventId` is the value returned by `addRace`'s `data.eventId`, or the race row's id from any read tool. Only race events owned by the caller can be removed; workouts and time-off use other deletion paths. Requires the `joules.write` OAuth scope and an active Joules subscription. </instructions>

removeRace

<usecase> Renders a chart inline in the user's chat. Relevant when the user asks to see a chart, visualization, or trend — for example a fitness trajectory plot, weekly load shape, or year-over-year comparison they've requested. Pairs with the data tools, which return the underlying numbers for narration. </usecase> <instructions> Pass `metric` (one of ctl, atl, tsb, daily_tss, cumulative_tss, weekly_tss), `ranges` (1-4 items, each `{label, start, end}` with YYYY-MM-DD dates), and optional headline copy (`eyebrow`, `name`, `stats`). Chart type is decided by the metric: `daily_tss` and `weekly_tss` render as bars; the rest render as lines. `align` controls how multiple ranges overlay: - "absolute" (default for one range) — true calendar dates on x-axis. Use for sequential ranges that share a timeline ("last 90d" alone, or "last 90d" vs "prior 90d"). - "doy" — day-of-year overlay so Jan 1 of one year sits on top of Jan 1 of another. Use for year-over-year comparisons. Headline copy guidance — keep all three short, the model narrates the rest. Always use plain terms, never acronyms: "Fitness" (not CTL), "Fatigue" (not ATL), "Form" (not TSB), "Load". - `eyebrow` — small context line, e.g. "Last 90 days · Fitness", "Apr 27 – May 3". - `name` — qualitative phrase, e.g. "Productive build", "Ahead of last year". - `stats` — one anchored number you'll cite in chat, e.g. "Now 67 · +22 since Jan 29". `yLabel` is optional — defaults to a sensible plain label per metric (e.g. "Fitness", "Load"). Override only when the default is wrong for the question. </instructions>

renderChart

<usecase> Patches metadata on a single block in the athlete's live trajectory — `name`, `phase`, and/or `notes`. Use when `getPlan` surfaces a block whose label or notes need refreshing (e.g. the athlete's goal shifted, or the coach's framing for a phase needs an edit). Per-week TSS edits and structural rewrites — moving block bounds, adding/removing weeks, changing a week's intent — go through `setPlan` instead. </usecase> <instructions> **blockId** — the `id` returned for the block in `getPlan`'s `data.plan.blocks[].id` (format `blk-<integer>`). **name**, **phase**, **notes** — supply only the fields you want to change. Pass an empty string for `notes` to clear it. `phase` must be one of base/build/peak/race/recovery. At least one field is required. </instructions>

updateBlock