Skip to main content
Glama
Sign In
xichen-de

garmin-owl

by xichen-de
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

get_sleep

Read-only

Retrieve sleep score, need, stages, heart rate, stress, respiration, SpO2, and skin-temperature deviation for a date to review that night's sleep detail.

Instructions

Get sleep score/need, stages, HR/stress, respiration, SpO2, and skin-temperature deviation for a date.

Use for sleep detail; use get_recovery to combine sleep with HRV and readiness. Garmin files a night under the day you woke up, so the date 2026-10-10 is the night of 9-10 October.

sleep_start and sleep_end are 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.

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

NameRequiredDescriptionDefault
dateNoCalendar 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.

Output Schema

NameRequiredDescriptionDefault
dateYes
sleep_endNoSleep end: 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.
awake_countNo
nap_secondsNo
sleep_scoreNo
sleep_startNoSleep start: 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.
availabilityNo
awake_secondsNo
average_hr_bpmNo
average_stressNoGarmin's average stress during sleep, to one decimal. A different metric from the whole-day average_stress of get_stress and get_daily_summary.
rem_sleep_secondsNo
deep_sleep_secondsNo
lowest_respirationNo
sleep_need_minutesNo
average_respirationNo
body_battery_changeNo
highest_respirationNo
light_sleep_secondsNo
lowest_spo2_percentNo
sleep_need_feedbackNo
total_sleep_secondsNo
average_spo2_percentNo
sleep_score_feedbackNo
restless_moments_countNo
skin_temperature_basisNo
sleep_alignment_statusNo
sleep_need_baseline_minutesNo
skin_temperature_deviation_cNo
skin_temperature_calibration_daysNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.3.1
    • 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."
    • 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"
+  }
+}
    • removedOutput schema / additionalProperties
      Removed value: -true
    • addedOutput schema / properties
      Added value: +{
+  "availability": {
+    "items": {
+      "$ref": "#/$defs/AvailabilityNotice"
+    },
+    "title": "Availability",
+    "type": "array"
+  },
+  "average_hr_bpm": {
+    "anyOf": [
+      {
+        "type": "number"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Average Hr Bpm"
+  },
+  "average_respiration": {
+    "anyOf": [
+      {
+        "type": "number"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Average Respiration"
+  },
+  "average_spo2_percent": {
+    "anyOf": [
+      {
+        "type": "number"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Average Spo2 Percent"
+  },
+  "average_stress": {
+    "anyOf": [
+      {
+        "type": "number"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Garmin's average stress during sleep, to one decimal. A different metric from the whole-day average_stress of get_stress and get_daily_summary.",
+    "title": "Average Stress"
+  },
+  "awake_count": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Awake Count"
+  },
+  "awake_seconds": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Awake Seconds"
+  },
+  "body_battery_change": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Body Battery Change"
+  },
+  "date": {
+    "title": "Date",
+    "type": "string"
+  },
+  "deep_sleep_seconds": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Deep Sleep Seconds"
+  },
+  "highest_respiration": {
+    "anyOf": [
+      {
+        "type": "number"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Highest Respiration"
+  },
+  "light_sleep_seconds": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Light Sleep Seconds"
+  },
+  "lowest_respiration": {
+    "anyOf": [
+      {
+        "type": "number"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Lowest Respiration"
+  },
+  "lowest_spo2_percent": {
+    "anyOf": [
+      {
+        "type": "number"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Lowest Spo2 Percent"
+  },
+  "nap_seconds": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Nap Seconds"
+  },
+  "rem_sleep_seconds": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Rem Sleep Seconds"
+  },
+  "restless_moments_count": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Restless Moments Count"
+  },
+  "skin_temperature_basis": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Skin Temperature Basis"
+  },
+  "skin_temperature_calibration_days": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Skin Temperature Calibration Days"
+  },
+  "skin_temperature_deviation_c": {
+    "anyOf": [
+      {
+        "type": "number"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Skin Temperature Deviation C"
+  },
+  "sleep_alignment_status": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Sleep Alignment Status"
+  },
+  "sleep_end": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Sleep end: 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.",
+    "title": "Sleep End"
+  },
+  "sleep_need_baseline_minutes": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Sleep Need Baseline Minutes"
+  },
+  "sleep_need_feedback": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Sleep Need Feedback"
+  },
+  "sleep_need_minutes": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Sleep Need Minutes"
+  },
+  "sleep_score": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Sleep Score"
+  },
+  "sleep_score_feedback": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Sleep Score Feedback"
+  },
+  "sleep_start": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Sleep start: 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.",
+    "title": "Sleep Start"
+  },
+  "total_sleep_seconds": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "title": "Total Sleep Seconds"
+  }
+}
    • addedOutput schema / required
      Added value: +[
+  "date"
+]
    • changedOutput schema / title
      Previous value: -"get_sleepDictOutput"New value: +"SleepSummary"
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

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

Beyond the safety profile that readOnlyHint, destructiveHint, and openWorldHint already declare, the description discloses the authentication prerequisite (saved local Garmin auth, garmin-owl-auth), that the tool reads Garmin data and may write the local cache but never modifies the Garmin account, and that Garmin failures are not retried automatically. These are the operationally relevant facts an agent needs, and they are not available from the annotations alone.

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

Conciseness4/5

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

The description is front-loaded: purpose and the alternative tool come first, then the date semantics, then the authentication and side effects. The `sleep_start`/`sleep_end` paragraph does not earn its place because those parameters are absent from the schema, which costs a point, but everything else is tightly written with no filler.

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

Completeness4/5

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

For a one-parameter read that returns a structured payload, the description covers purpose, alternative routing, authentication, side effects, and failure handling, and the presence of an output schema means return values need not be explained. It falls short of complete because it omits what happens when no sleep record exists for a date, notably the empty/null behavior that the nullable default hints at.

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

Parameters3/5

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

Schema coverage is 100% and the single `date` parameter is fully documented, so the baseline here is 3. The description does add real value with the day-attribution rule for the date, but it also documents `sleep_start` and `sleep_end` ISO 8601 parameters that do not exist in the schema, along with offset guidance for them; this is a concrete source of invocation error that the schema coverage cannot cancel out.

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?

It names a specific verb and resource and enumerates the exact metrics returned: sleep score/need, stages, HR/stress, respiration, SpO2, and skin-temperature deviation. It also explicitly distinguishes itself from the neighboring get_recovery tool, so an agent can identify which tool to call without opening either 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?

The description states when to use this tool ('Use for sleep detail') and names the alternative and the condition that selects the alternative ('use get_recovery to combine sleep with HRV and readiness'). It also gives a usage rule for the `date` argument: Garmin files a night under the day the user woke up, so 2026-10-10 names the night of 9–10 October.

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