Skip to main content
Glama

get_energy_balance

Read-only

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

NameRequiredDescriptionDefault
end_dateYes
start_dateYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only establish that this is a safe read (readOnlyHint=true, destructiveHint=false); the description adds a great deal beyond that: which days are auto-excluded from each mean, what is returned versus omitted when the gate fails, when implied_deficit_uncertainty_kcal_per_day appears, and repeated warnings that difference_kcal_per_day is confounded. It also flags the estimate's provenance as literature constants rather than measured values.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the headline formula are front-loaded, and the exclusion list is cleanly bulleted. However, roughly 700 words is far more than needed, and several passages (the extended justification of why the combined regression's standard error is reproducible, the exhaustive fitted-versus-observed field reconciliation) read as authorial defense rather than agent guidance and could be cut by a third without losing decision-relevant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a derived metric, statistical gating, and no output schema, the definition covers the formula, the reliability conditions, the failure modes, the returned-versus-omitted fields, and the confounds a consumer must not over-interpret. An agent has everything it needs to call it and to read the result responsibly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the schema titles are bare ('Start Date', 'End Date'), so the description carries the load: it specifies YYYY-MM-DD formatting and imposes a 61-day maximum range, both of which constrain valid input. It does not discuss inclusivity of endpoints or behavior on reversed dates, but the essential semantics are covered.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and output ('Estimate a composition-derived TDEE') and enumerates the three input signals it fuses. It explicitly distinguishes itself from Garmin's own calorie model and names the sibling tools (get_nutrition_summary_between_dates, get_stats_range) whose exclusion rules it mirrors, so an agent can place it precisely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use conditions ('Prefer windows of 3+ weeks with several readings spread across them, not clustered at one end'), when-not conditions (the span/leverage gate, 0-1 readings, short windows dominated by water/glycogen), and a hard 61-day cap. It stops short of explicitly routing the agent to a sibling for raw intake/expenditure, which is the main remaining gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools