Cal Plus

Weight over a period: first and last weigh-in, net change, a least-squares trend in kg per week, min/max/average, how many times they weighed in, the goal weight, the remaining distance to it, and a projection of how many weeks that would take at the current trend. Includes a downsampled series for shape, plus a count of progress photos taken. Use for "am I making progress", "has my weight stalled", "when will I hit my goal". The trend is a regression over all weigh-ins, so it is more reliable than comparing the first and last reading; prefer it when explaining direction. Weight is only present when the user logs it. A window with no weigh-ins comes back as no_data, which means unknown, not stable. The projection is null when the trend is flat or heading away from the goal, because a projection that never arrives is worse than none. Body weight is the only body metric Cal Plus stores — there is no body fat, lean mass or measurements. Defaults to the last 90 days.

get_progress_summary

Start here. Returns who this Cal Plus user is and what their account can answer: age, height, current and goal weight, the goal they chose (lose/gain/maintain), activity level, dietary preference, timezone, their current calorie/protein/carb/fat and micronutrient targets, water goal, logging streak and recent badges. Critically, it also returns a `capabilities` map saying which data categories this account actually has. Read it before asking for anything else. Cal Plus does NOT track heart rate, HRV, recovery or body composition at all — those come back as "unsupported" and no other tool will ever return them, so say so plainly rather than inferring them. Sleep is read from the user's health app only when they switch it on in Cal Plus: `capabilities.sleep` is "available" when nights exist (use get_sleep_summary) and "not_connected" otherwise, which means unknown — never poor sleep. Steps and active energy come back as "not_connected" when the user has never linked Apple Health or Health Connect, which means unknown, not zero. Takes no arguments and covers no date range — it describes the account as it is now. Cheap; call it once at the start of a conversation.

get_user_context

Puts two windows side by side for the chosen metrics and reports each one's daily average in both, the absolute change and the percentage change. Use for "how does this week compare with last week", "am I eating more than last month", "has my training dropped off". One call instead of two summaries and manual arithmetic. By default the comparison window is the equally long period immediately before the current one, so a partial week is compared against a partial week. Supply compare_start_date and compare_end_date to choose it explicitly. Comparison uses daily averages rather than totals so windows of different lengths stay fair. When either side has no data, `comparable` is false and the change is null — that means unknown, not unchanged. Defaults to the last 7 days versus the 7 before that.

compare_periods

Searches the names of meals the user logged and returns the matches with their date, time, meal type and nutrition, newest first. Use for "when did I last eat sushi", "how often do I have oats", "find my highest calorie pizza". Much cheaper than pulling a long history and scanning it. Matching is a case-insensitive substring on the meal name, so short general terms work better than long exact phrases. It does not search the component items inside a composite meal, only the meal name. Searches the last 180 days by default; widen with the date arguments up to 366 days. Paginated — check page.hasMore.

search_food_logs

Everything the user chose to track as a behaviour: habits like "no alcohol", "10k steps", "read 20 minutes", plus any custom nutrition trackers they created (caffeine, omega-3, whatever they defined). For each habit it returns the goal and cadence, how many periods were logged, a success / partial / miss / unlogged breakdown, the success rate over the requested range, the current and best streak, and a set of "how are things right now" signals fixed to the last 30 days: 30-day and 7-day consistency, whether that is rising or falling, a recency-weighted momentum score, and a weekday-versus-weekend split. Use it for "am I sticking to my habits", "how is my streak", "which habit am I slipping on", "do I do better on weekdays". The recent signals are always the last 30 days ending today so they match what the user sees in the Cal Plus app, whatever date range you ask for. Two rules to read correctly. **Abstinence habits succeed when nothing is logged** — not logging alcohol is the win — so a long unlogged run is a good streak, not a gap. And some habits are filled in automatically from other Cal Plus data (`autoSynced` with an `autoSyncSource` like steps or protein); those were not ticked by hand, so do not praise the user for consistency they did not perform. Habits are opt-in: an account with none returns no_data, which says nothing about the person. Set include_periods for the individual entries. Defaults to 30 days.

get_habits_summary

Record-level detail: the actual meals eaten (with time of day, meal type, portion, per-item breakdown and full nutrition), the actual workouts (with exercises, sets, reps, weights and RPE; workouts imported from other apps come back with loggedVia "health_import", a source block and no sets), water intake, weigh-ins and — when the user shares it — each night's sleep. This is the tool for "what did I eat yesterday", "show me Tuesday's dinner", "what did I lift on Monday". Use it only when the individual records matter — for totals, averages or trends the summary tools are far cheaper and cover longer periods. Limited to 31 days per call and paginated; check `page.hasMore` and re-request with a larger offset to walk further back. Choose `include` to fetch only the categories you need. Item-level meal breakdowns are only returned when include_items is true, since they are the largest part of the response. Defaults to today.

get_daily_log

The flexible one. Returns a time series for any combination of supported metrics over one window, bucketed by day, week or month, with total, average, min and max. Supported metrics: calories, protein_g, carbs_g, fat_g, fiber_g, added_sugar_g, sodium_mg, meals_logged, steps, active_energy_kcal, weight_kg, water_ml, workout_sessions, workout_minutes, habits_completed, sleep_minutes, sleep_score, sleep_efficiency_pct. Use it to line different things up against each other — "compare my calories with my steps", "did my protein drop in the weeks my weight stalled", "chart my training volume against my weight". Ask for several metrics in one call rather than several calls; categories are fetched once and shared. Flow metrics (calories, steps, water) are summed within a bucket. Body weight is averaged, because a summed weight is meaningless. Each bucket reports daysWithData and daysInPeriod, so a week built from two logged days is visibly different from a full one. Empty buckets appear with a null value rather than being dropped — a gap is information. This is a structured request over prepared metrics, not a database query interface: metric names are a fixed list and nothing else is accepted. For headline figures prefer the summary tools; for the underlying records use get_daily_log. Defaults to the last 30 days by day.

get_metric_series

Aggregated eating data over a date range: total and average calories, protein, carbs, fat, fiber, added sugar, sodium and potassium; how those compare with the targets in force on each day; a per-day breakdown; the split across meal types; and the most frequently logged foods. Use this for any question about how someone has been eating — "how has my nutrition been this month", "am I hitting my protein", "what do I eat most". Do NOT use it to find out what someone ate on a particular day; get_daily_log returns the actual meals. Returns two different averages on purpose. `dailyAverages` divides by every day in the range; `averagesOnLoggedDays` divides only by days with at least one meal. The gap between them is under-logging, not under-eating. `completeness` reports how many days were actually logged and lists the missing ones — never treat a missing day as a zero calorie day. Defaults to the last 30 days. Accepts up to 366 days.

get_nutrition_summary

The standing facts this user has asked Cal Plus to remember: dietary restrictions, allergies, foods they dislike, workout style, supplement choices and similar. Each entry is a `kind` (free text, e.g. "dietary restriction", "dislike") and a `value` exactly as the user approved it in the app. Call this BEFORE suggesting foods, meals, recipes or training plans — it is what keeps advice consistent with what the in-app coach already knows. Treat every entry as a hard constraint unless it is clearly a soft taste ("prefers spicy food"). These rows are the user’s own words, curated by them in Settings → Preference memory. An empty result means nothing has been saved, not that the user has no restrictions — when it matters (allergies), ask rather than assume. Takes no arguments and covers no date range. Cheap; call once per conversation when food or training suggestions come up.

get_memory_preferences

Nightly sleep read from the health app on the user's phone (Apple Watch, Oura, Samsung Health, a sleep app, ...), only when the user has switched sleep sharing on in Cal Plus. Per night: time asleep against the user's sleep goal, time in bed and efficiency, time to fall asleep, awakenings, light / deep / REM when the source records stages, bedtime and wake-up, possible naps, and the Cal Plus Sleep Score (0–100: duration, efficiency, interruptions, stages, bedtime consistency). Over the window: averages, sleep debt against the goal, usual bedtime and wake-up and how much they vary, longest and shortest night. A night is credited to the morning it ended on, so "last night" is today's date. Pay attention to `availability`: "not_connected" means the user does not share sleep (unknown, never "slept badly"); "no_data" means they do but nothing was recorded in this window; `completeness.missingDays` lists nights with no record — a watch left on the charger is a missing night, not a sleepless one. Null stage or efficiency fields mean the source does not record them. Per-night detail is included for windows up to 31 days; longer windows return the summary only. Defaults to the last 7 nights.

get_sleep_summary