get_energy_balance
Estimates composition-derived TDEE by combining logged intake, Garmin calorie expenditure, and body-composition trends over a date range—useful for cross-checking Garmin's calorie model.
Instructions
Estimate a composition-derived TDEE from logged intake, Garmin's claimed expenditure, and body-composition change over a date range.
Combines three signals Garmin exposes separately -- mean logged intake
(nutrition log), mean claimed expenditure (Garmin's total_calories from
daily stats), and a body-composition trend (weight and body-fat % from
smart-scale readings) -- into composition_derived_tdee, an estimate
independent of Garmin's calorie model:
composition_derived_tdee = mean_intake + implied_deficit, where
implied_deficit comes from the fitted rate of fat and fat-free mass
change, using the standard energy-density approximations
7700 kcal/kg fat and 1800 kcal/kg fat-free mass. These are body
composition literature estimates, not Garmin-provided or measured
values -- treat the result as a rough estimate, not a lab measurement.
difference_kcal_per_day (Garmin's claim minus this estimate) has at
least two explanations -- Garmin overestimating expenditure, or
under-logged intake, which is common -- and this tool cannot
distinguish between them.
The body-composition trend is fit by least-squares regression across
every qualifying scale reading in range, not just the first and last --
an endpoint-to-endpoint difference is fully determined by two
individual measurements and inherits all of their noise (a 0.5%
body-fat wobble, well within normal scale repeatability, can swing a
two-point estimate by over a hundred kcal/day). weight_change_kg,
fat_mass_change_kg, and lean_mass_change_kg in body_composition are
all fitted values (the fitted line's value at the last reading's day
offset minus its value at the first), not raw differences between the
observed_first_*/observed_last_* fields, which are the actual
readings for reference/sanity-checking, not what the change figures
are computed from -- fitted_first_weight_kg/fitted_last_weight_kg are
also included so fitted_last_weight_kg - fitted_first_weight_kg can be
checked against weight_change_kg directly.
implied_deficit_kcal_per_day is the slope of a single regression: for
each reading, compute -(fat_kg * 7700 + lean_kg * 1800) where
lean_kg = weight_kg - fat_kg, then fit that value against day offset.
This is mathematically identical to combining separately-fit fat and
lean slopes, but its standard error -- implied_deficit_uncertainty_kcal_per_day,
returned whenever more than 2 readings are used -- is that single
fit's own residual standard error, which is well-defined and
reproducible from the raw readings alone (fat_kg and lean_kg are both
derived from the same weight/body-fat pair per reading, so treating
their separately-fit slopes' errors as independent and combining them
after the fact, instead of fitting the combined series directly,
would not be reproducible from outside without also knowing that
assumption). Treat a deficit within roughly one standard error of
zero as indistinguishable from no change.
Below a minimum span, or when most of the fit's statistical leverage
sits in one tight cluster of readings taken within about 48 hours of
each other, the fitted trend is not reliable even with 3+ readings --
a close, low-noise pair inside that cluster makes the fit look
precise while the slope is still mostly an extrapolation from that
cluster to wherever the other reading(s) fall. When this gate fails,
body_composition is still returned (it's just the fitted line, always
checkable against the observed readings) but derived is omitted and
gate_note explains which condition failed. Prefer windows of 3+ weeks
with several readings spread across them, not clustered at one end.
Short windows are also dominated by water/glycogen shifts (which
carry little caloric weight, unlike true lean tissue), which biases
the fat-free-mass term; see assumptions.note.
Exclusions applied automatically, matching get_nutrition_summary_between_dates
and get_stats_range:
- Intake: days with no logged food (item_count 0) are excluded from
the mean, not counted as zero. Days with a low but nonzero
item_count remain included (excluding them requires judgment this
tool doesn't make unilaterally) but are called out in
low_item_count_dates so low-confidence days are visible rather than
silently blended into the mean. A window with many such days (or
many item_count-0 days) biases composition_derived_tdee downward --
check days_excluded_unlogged and low_item_count_dates before
comparing two windows against each other.
- Expenditure: days with no device data, and the current (partial)
day, are excluded from the mean.
- Body composition: only scale readings with both weight and body-fat
percentage are used (skips weight-only manual entries).
Needs at least 2 qualifying body-composition readings to derive a
trend, and to pass the span/leverage gate above to derive a TDEE from
it. With 0 or 1 readings, returns the intake/expenditure means and
whatever body composition data exists, but omits the derived TDEE.
Maximum range: 61 days per call.
Args:
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"start_date": "<start_date>",
"end_date": "<end_date>"
},
"name": "get_energy_balance"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | ||
| start_date | Yes |