Vaultbeat MCP Server

Overview Schema Source Related Servers Discussions Admin

Sleep history

vaultbeat_sync_sleep

Read-onlyIdempotent

Fetch and decrypt encrypted sleep records, then return per-day primary session summaries; set summary_only to trigger a sync or verify connectivity without retrieving full session data.

Instructions

Fetch encrypted Vaultbeat sleep records, decrypt them locally, and return per-day primary session summaries matching the iOS app's display.

Returns daily_summary (one primary session per local date, selected by iOS priority: Watch > iPhone > inBedOnly) and sessions (all raw records). The limit controls how many raw blobs are fetched; 50 covers ~2-3 weeks. Use owner prefix to filter by person — take it from vaultbeat_status (owner_user_id_prefix is the paired user; server 0.7.1+), or vaultbeat_doctor for every owner present in the data. Without it, both partners' data is mixed and per-day selection may pick the wrong person's session.

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

Results are served from a short-lived local cache (default 10 min); pass fresh=True to force a cloud round trip.

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.

🔑 Pass summary_only=True when you only want the SIDE EFFECT. A default call returns every decrypted session — measured at 76,446 characters, which overflows a typical tool-result limit and gets spilled to a file the caller then has to read back. That is the right shape when you want the nights; it is pure waste when you called this to make the server do something (force a sync, check the link is alive, confirm a deploy took effect), which is a large share of real calls. summary_only=True returns the counts, the day range and the coverage block, and nothing else. For the nights themselves, get_sleep_detail is the tool that exists for it.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fresh`	No
`limit`	No
`owner`	No
`summary_only`	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.9/5.0

Behavior5/5

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

The description adds substantial behavioral context beyond the annotations: local decryption, a 10-minute cache with `fresh=True` forcing a cloud round trip, output-size overflow behavior, the `is_in_bed_only` interpretation trap, and the `coverage.more_available` caveat about limit-shaped windows. Despite mentioning 'side effect' and 'force a sync,' it does not contradict the readOnly/idempotent/non-destructive annotations because those actions are retrieval/cache refreshes, not data mutations.

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 long, but the tool is complex and full of easy-to-miss traps, so most sentences earn their place. It is front-loaded with the core purpose. A slight deduction is warranted because some phrasing, such as 'which is a large share of real calls' and the extended overflow narrative, could be trimmed without losing essential guidance.

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?

Given the tool's complexity, the lack of required parameters, and the presence of an output schema, this description is unusually complete. It covers return blocks, per-day selection priority, owner filtering, cache semantics, output-size failure mode, coverage interpretation, and the in-bed-only semantic trap. There is no important calling consideration left to the agent to discover.

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 burden, and it succeeds for all four parameters: `limit` is tied to raw blob count and rough time span, `owner` is sourced from specific sibling tools with a warning about mixing partners, `fresh` is tied to the cache, and `summary_only` is explained in terms of returned fields and output size. This is far more than the raw schema provides.

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 specific verb-plus-resource statement: 'Fetch encrypted Vaultbeat sleep records, decrypt them locally, and return per-day primary session summaries matching the iOS app's display.' It clearly distinguishes this tool from get_sleep_detail, which is explicitly named as the tool for raw night-level details. The name and title alone would not convey this, so the description adds real differentiation.

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?

Usage guidance is explicit and actionable. It says to use `owner` filtered from `vaultbeat_status` or `vaultbeat_doctor`, describes the consequence of omitting it, explains when to pass `fresh=True`, and tells the agent to prefer `summary_only=True` when only the side effect is wanted. It also routes night-level needs to get_sleep_detail, giving a clear alternative.

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