garmin-owl

Overview Schema Source Related Servers Discussions Admin

get_body_battery

Read-only

Retrieve Garmin Body Battery data for a single calendar date, including energy charged and drained plus start, end, highest, and lowest levels, with optional timeseries readings.

Instructions

Get one calendar day's Garmin Body Battery: energy charged and drained over the whole day plus start, end, highest, and lowest levels (0-100), with optional readings.

Use for Body Battery detail on one date; use get_sleep or get_recovery for the overnight change (body_battery_change), or get_recovery_trend for change over several days.

Field notes: charged/drained are whole-day totals, not the overnight recharge. Levels come from the day's readings; for today they are partial and end_level is the latest reading. A record Garmin returns for a different date is withheld and disclosed in availability.

Requires saved local Garmin authentication (garmin-owl-auth). Reads Garmin and may update the local cache; never changes your Garmin account. Garmin failures are not retried automatically.

Input Schema

Name	Required	Description	Default
`date`	No	Calendar date in YYYY-MM-DD format, e.g. 2026-10-09; any past date Garmin still stores. Omit or pass null for today in the server's local timezone.
`include_timeseries`	No	When true, also return timeseries: up to 48 {timestamp, value} readings sampled evenly across the day (first and last always kept), with ISO 8601 timestamps that include the UTC offset. Always reads Garmin fresh instead of the cached daily summary. Defaults to false.

Output Schema

Name	Required	Description	Default
`date`	Yes
`charged`	No
`drained`	No
`end_level`	No
`timeseries`	No
`start_level`	No
`availability`	No
`lowest_level`	No
`highest_level`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.3.1Oct 24, 2026

changedInput schema / properties / date / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / date / description

Added value: +"Calendar date in YYYY-MM-DD format, e.g. 2026-10-09; any past date Garmin still stores. Omit or pass null for today in the server's local timezone."

addedInput schema / properties / include_timeseries / description

Added value: +"When true, also return timeseries: up to 48 {timestamp, value} readings sampled evenly across the day (first and last always kept), with ISO 8601 timestamps that include the UTC offset. Always reads Garmin fresh instead of the cached daily summary. Defaults to false."

addedOutput schema / $defs

Added value: +{
+  "AvailabilityNotice": {
+    "properties": {
+      "field": {
+        "title": "Field",
+        "type": "string"
+      },
+      "message": {
+        "title": "Message",
+        "type": "string"
+      },
+      "status": {
+        "title": "Status",
+        "type": "string"
+      }
+    },
+    "required": [
+      "field",
+      "status",
+      "message"
+    ],
+    "title": "AvailabilityNotice",
+    "type": "object"
+  },
+  "TimePoint": {
+    "properties": {
+      "timestamp": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "integer"
+          }
+        ],
+        "description": "Reading time: ISO 8601 with an explicit UTC offset, e.g. 2026-10-09T23:18:16+02:00. The wall time is already local; never add the offset again. The offset is the one Garmin recorded for the device at that moment, or this computer's time zone when Garmin gives only UTC. A bare date or number is a Garmin value that could not be parsed as a time.",
+        "title": "Timestamp"
+      },
+      "value": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "integer"
+          }
+        ],
+        "title": "Value"
+      }
+    },
+    "required": [
+      "timestamp",
+      "value"
+    ],
+    "title": "TimePoint",
+    "type": "object"
+  }
+}

removedOutput schema / additionalProperties
```
Removed value: -true
```

addedOutput schema / properties

Added value: +{
+  "availability": {
+    "items": {
+      "$ref": "#/$defs/AvailabilityNotice"
+    },
+    "title": "Availability",
+    "type": "array"
+  },
+  "charged": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Charged"
+  },
+  "date": {
+    "title": "Date",
+    "type": "string"
+  },
+  "drained": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Drained"
+  },
+  "end_level": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "End Level"
+  },
+  "highest_level": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Highest Level"
+  },
+  "lowest_level": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Lowest Level"
+  },
+  "start_level": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Start Level"
+  },
+  "timeseries": {
+    "anyOf": [
+      {
+        "items": {
+          "$ref": "#/$defs/TimePoint"
+        },
+        "type": "array"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Timeseries"
+  }
+}

addedOutput schema / required
```
Added value: +[
+  "date"
+]
```

changedOutput schema / title

Previous value: -"get_body_batteryDictOutput"New value: +"BodyBatterySummary"

First observedv0.1.0Aug 31, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description goes well beyond them: it requires saved local Garmin auth (garmin-owl-auth), discloses that it may update the local cache without ever changing the Garmin account, notes that Garmin failures are not retried automatically, warns that today's levels are partial with end_level as the latest reading, and explains that a mismatched-date record is withheld and reported via availability. That is exactly the kind of staleness, auth, and failure context annotations cannot carry.

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

Conciseness5/5

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

Three short blocks with the return contents front-loaded, then the sibling routing, then field caveats and operational constraints. No sentence is filler — even the auth and retry lines carry decision-relevant information an agent cannot get elsewhere.

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?

An output schema exists, so return shape need not be spelled out, and annotations cover the safety profile; the description fills the remaining gaps — auth prerequisite, cache behavior, no auto-retry, partial-data caveat for today, and availability disclosure for withheld records. Nothing an agent needs to call this correctly or interpret the result is missing.

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 100%, so baseline is 3, but the description adds interpretive meaning the schema does not: it clarifies that today's readings are partial and that charged/drained are whole-day totals rather than overnight recharge, which directly affects how the omitted-date default should be read. The include_timeseries flag itself is only alluded to as 'optional readings', so the extra value is partial rather than comprehensive.

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?

States a specific verb and resource ('Get one calendar day's Garmin Body Battery') and enumerates exactly what is returned: charged/drained totals plus start, end, highest, and lowest levels on a 0-100 scale. It also explicitly names the sibling tools (get_sleep, get_recovery, get_recovery_trend) that cover the overnight or multi-day variants, so an agent can separate it from get_daily_summary or get_stress without opening a schema.

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

Usage Guidelines5/5

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

Gives a direct when-to-use ('Body Battery detail on one date') and names three alternatives with the specific condition that selects each — get_sleep/get_recovery for the overnight body_battery_change, get_recovery_trend for multi-day change. Exclusions and routing are both explicit.

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