Vaultbeat MCP Server

Overview Schema Source Related Servers Discussions Admin

Sleep stage detail

get_sleep_detail

Read-onlyIdempotent

Fetch detailed per-night sleep stages with stage-level heart and respiratory rates for one or two specific nights, including partner-shared data when needed.

Instructions

Per-night sleep stages with per-stage HR/RR — depth on a few nights.

Which sleep tool to use: · THIS one for going deep on one or two specific nights (stage bands, per-stage vitals). It defaults to 2 nights because each is ~3k characters; see the SIZE note below. · get_sleep_nights for anything spanning time — "how did I sleep this week/month/year", patterns, worst nights. One compact row per night, a whole year in one read. Reach for it whenever the question is about a period rather than a night, and do not conclude from THIS tool's two rows that only two nights exist. · get_metric with the sleep series (bedtime_minutes, deep_sleep_minutes, awakenings, ...) for averages computed for you.

(This used to call itself "the primary tool for detailed sleep analysis", which read as "use this one for sleep" and handed back two days to anyone who asked how their week went.)

Returns stage_intervals (contiguous stage bands with start/end), stage_minutes, and stage_vitals (per-stage HR/RR min/mean/max). Reads YOUR nights by default; partner=true reads your partner's shared sleep.

limit = the newest N nights, 2 by default. To read a particular night, pass its date as since and until ("YYYY-MM-DD", the local day the night ENDS on — the local_date / date column of get_sleep_nights); a wider since / until reads every night in that window, and limit then applies only if you pass it.

⚠️ SIZE: each night is ~3k characters as returned (a week ~21k). Setting include_timeline=True adds the raw per-sample array (hr, rr, stage, time) — about 13k characters PER NIGHT, which will overflow a typical 25k-token client budget after 2-3 nights. Ask for it only when you need sample-level vitals (e.g. "when exactly did HR spike"); stage_vitals already answers per-stage questions. Raise limit for trends, but keep it low whenever include_timeline=True.

⚠️ is_in_bed_only: true means sleep was NEVER MEASURED that night (the Watch wasn't worn) — NOT that the person slept zero. duration_label reads "no sleep data" and in_bed_minutes holds the time actually recorded in bed. Report it as "no sleep data (in bed ~Xh)", never as "slept 0 hours".

Carries a coverage block: quote coverage.days_covered (distinct days, not the row count) and coverage.span_days beside any average or trend. coverage.window_satisfied: false alone does NOT mean a short history: it is also false when older days exist beyond your window. 🔴 Before saying how far back someone's data goes, read coverage.more_available: true means this server can decrypt days OLDER than first_day that your limit left behind — re-read with a larger limit, or quote coverage.oldest_available as the real start of their history. Never report a limit-shaped window as the extent of their data.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fresh`	No
`limit`	No
`since`	No
`until`	No
`partner`	No
`include_timeline`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.9.1Oct 3, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / limit / anyOf

Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / limit / default
```
Previous value: -2New value: +null
```
removedInput schema / properties / limit / type
```
Removed value: -"integer"
```

removedInput schema / properties / owner

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Owner"
-}

addedInput schema / properties / partner

Added value: +{
+  "default": false,
+  "title": "Partner",
+  "type": "boolean"
+}

addedInput schema / properties / since

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Since"
+}

addedInput schema / properties / until

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Until"
+}

First observedv0.8.1Sep 23, 2026

TDQS

A4.5/5.0

Behavior3/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes well beyond that with size/budget warnings (~3k chars per night, 13k with include_timeline), the `is_in_bed_only` non-measurement trap, and coverage-block reporting rules — genuinely useful behavioral context. However, the volume of caveats is disproportionate to the tool's actual behavior, and many are output-interpretation guidance rather than invocation behavior, so it earns solid but not top marks.

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 purpose, then clearly delimited routing/returns/SIZE/semantics sections. The parenthetical aside about the tool's former self-description is editorial waste, but most of the length is load-bearing given the size-budget traps and the coverage-reporting contract.

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 6-parameter, 0%-coverage, read-only analytics tool, the description covers invocation parameters, the output shape (stage_intervals/stage_minutes/stage_vitals) despite an output schema existing, size budgets, data-absence semantics, and the coverage block's correct interpretation. Nothing an agent needs to call or interpret it correctly is missing.

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 description coverage is 0%, so the description carries the full load and does so for limit (newest N, default 2), since/until (exact 'YYYY-MM-DD' format, local day the night ENDS on, and how limit interacts with a window), include_timeline, and partner. Only `fresh` is left unexplained, which is a minor gap against five well-documented parameters.

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?

Opens with a specific verb+resource ('Per-night sleep stages with per-stage HR/RR') and immediately scopes it ('depth on a few nights'). It explicitly names and distinguishes both alternatives, `get_sleep_nights` and `get_metric`, so an agent can route correctly without opening any 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?

Contains a dedicated routing block stating when to use this tool (one or two specific nights), when NOT to (anything spanning time, periods), and which sibling to use instead for each case. It even warns against a specific misinference ('do not conclude from THIS tool's two rows that only two nights exist').

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