Skip to main content
Glama
google-health-mcp

google-health-mcp

health_get_sleep_sessions

Retrieve each sleep session Google recorded separately, including intervals, stages, metadata, summaries, and device, so you can inspect naps or split nights instead of nightly totals.

Instructions

Get each sleep session as Google recorded it, rather than the nightly total.

A night can be several sessions (a wake-and-resume, a nap); health_get_sleep sums them per night, while this returns each one whole: its interval, type (CLASSIC or STAGES), Google's metadata (mainSleep, nap, processed, manuallyEdited, stagesStatus), its summary (minutesAsleep, minutesAwake, minutesInSleepPeriod, minutesToFallAsleep, minutesAfterWakeUp, and the per-stage minutes and counts), and the device that recorded it.

Args: start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "30d". Default: 30 days back from the end date or today, whichever is earlier. end_date: End date as "YYYY-MM-DD", "YYYY-MM" (its last day), or "Nd". Default: today. live: If true, re-fetch this window from the API before reading the cache. include_stages: If true, include every stage segment, short awakening and out-of-bed segment. Without it each session carries only how many there are, since a night runs to dozens.

Returns one entry per session with session_id, date (the local day it ended), start_time, end_time, provider, record (the session as Google sent it, less the segment arrays unless include_stages) and segment_counts (how many of each; absent where the stored record cannot be read).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "health_get_sleep_sessions"
  }
}

Input Schema

NameRequiredDescriptionDefault
liveNo
end_dateNo
start_dateNo
include_stagesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.12.0
    • changedOutput schema / (root)
      Previous value: -{
      -  "properties": {
      -    "result": {
      -      "title": "Result",
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "result"
      -  ],
      -  "title": "health_get_sleep_sessionsOutput",
      -  "type": "object"
      -}New value: +null
  2. Addedv1.7.0

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses the cache-vs-API behavior of `live`, the payload-size consequence of `include_stages` ('a night runs to dozens'), and the graceful degradation where segment_counts is 'absent where the stored record cannot be read'. Auth requirements and rate limits are not mentioned, which keeps it from a 5.

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?

Front-loaded with the distinguishing sentence before any detail, then Args and Returns in scannable blocks. The Returns paragraph enumerates many field names and is slightly dense, but each item conveys real payload structure rather than filler.

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?

No output schema exists, so describing the return shape (session_id, date as the local day it ended, record vs segment_counts) is necessary and is done thoroughly. Combined with full parameter semantics and sibling differentiation, an agent has everything needed to call this correctly.

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

Parameters5/5

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

Schema coverage is 0%, so the description must compensate, and it does: it documents accepted formats for start_date and end_date ('YYYY-MM-DD', 'YYYY-MM', '30d'/'Nd'), the non-obvious defaults (30 days back from the end date or today, whichever is earlier; end of month for 'YYYY-MM'), and the precise effect of both booleans.

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 each sleep session') and immediately scopes it against the nightly aggregate. The contrast with health_get_sleep ('sums them per night, while this returns each one whole') makes the distinction unmistakable 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 Guidelines4/5

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

Explicitly names the sibling alternative health_get_sleep and the condition that selects it (need per-session granularity: naps, wake-and-resume). It stops short of stating when *not* to use it, e.g. that callers wanting totals should avoid it, but the routing signal is clear.

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