Vaultbeat MCP Server

Overview Schema Source Related Servers Discussions Admin

Sleep stage detail

get_sleep_detail

Read-onlyIdempotent

Retrieve detailed per-night sleep stages with heart rate and respiratory rate for one or two specific nights, including stage intervals and vitals, to analyze sleep quality in depth.

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 ~1-2k characters; see the SIZE note below. · vaultbeat_sync_sleep for anything spanning time — "how did I sleep this week/month", trends, averages. Its default of 50 covers ~2-3 weeks. 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.

(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). Use owner prefix to filter by person — the first characters of a user id. vaultbeat_doctor lists them under capabilities.owner_prefixes; there is no other way to discover one, and omitting owner on a paired account blends both people into one result.

⚠️ SIZE: each night is ~1-2k characters as returned. 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, and read coverage.window_satisfied: false as a shorter history than asked, not as a missing kind. 🔴 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
`owner`	No
`include_timeline`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.8.1Sep 23, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already signal readOnly, idempotent, and non-destructive behaviorchery. The description adds substantial behavioral context beyond that: the ~1-2k character per-night size, the ~13k character per-night risk of include_timeline, the exact meaning of is_in_bed_only, the coverage block semantics, and the owner-blending pitfall. It also alerts agents to the limit-shaped window trap.

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?

The description is long, but it is well-structured with section headers, clear bullets, and prioritized warnings. The core purpose and tool-selection guidance are front-loaded, and every major section adds necessary operational safety or selection value. The brief historical note explains why the description was corrected, which is useful context for agents.

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 tool with output schema present, annotations, and four optional parameters, the description is nearly complete: it covers selection, ownership filtering, size constraints, special-value semantics, and coverage behavior. The only notable gap is the unspecified 'fresh' parameter, which prevents full completeness at the highest level.

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 description coverage is 0%, so the description carries the burden. It explains limit (defaults, size implications, raising for trends), owner (prefix, discovery via vaultbeat_doctor, blending risk), and include_timeline (raw samples, size, when to use). However, the 'fresh' parameter is never mentioned, leaving one parameter unexplained.

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 description opens with a precise verb-resource-scope statement: 'Per-night sleep stages with per-stage HR/RR — depth on a few nights.' It clearly distinguishes this tool from vaultbeat_sync_sleep and explicitly cautions against treating this tool as a broad sleep analysis tool.

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 gives explicit when-to-use guidance: use this tool for deep dives on one or two nights, and vaultbeat_sync_sleep for periods, trends, and averages. It also tells agents not to infer only two nights exist from this tool's default limit, which is a clear exclusion and alternative-related instruction.

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