Vaultbeat MCP Server

Overview Schema Source Related Servers Discussions Admin

Basal energy (BMR)

get_basal_energy

Read-onlyIdempotent

Decrypt Apple Watch basal energy samples to return daily BMR estimates and averages, with coverage details for incomplete days.

Instructions

Decrypt recent basal-energy-burned samples (Apple Watch BMR estimate, kcal). Watch typically emits hourly samples; unlimited limit + daily aggregation returns per-day BMR (~1500-2000 kcal for active young adults) + average. Use owner prefix to filter by person.

READ hours_covered BEFORE QUOTING ANY SINGLE DAY. Basal arrives as one blob per hour, so a day the Watch spent off the wrist comes back as a real-looking row that is short in exact proportion — 883 kcal at 12 of 24 hours is half a day of data, NOT a collapsed metabolism. Rows with incomplete: true are already excluded from average_daily_basal_kcal (average_over_days is its denominator); if you quote such a day, say how many hours it covers.

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

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.3/5.0

Behavior5/5

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

Annotations already mark this read-only and idempotent; the description adds substantial behavioral detail beyond them: hourly sample cadence, partial-day rows looking real but being short proportionally, `incomplete: true` exclusion from averages, the coverage block semantics, and warnings about `more_available` and `oldest_available`. It also explicitly warns against quoting a `limit`-shaped window as the full history. No contradiction with annotations.

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 densely informative, and the key purpose is front-loaded before the caveats. Every warning addresses a plausible failure mode, so the length is mostly justified. It could be tightened slightly, but it does not waste words on 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?

Given the output schema exists and the annotations cover safety, the description covers nearly everything an agent needs: kcal units, hourly cadence, daily aggregation, incomplete-row exclusion, coverage fields, and the more_available/oldest_available re-reading behavior. The only notable omission is the `fresh` parameter, which is not described anywhere.

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 description coverage is 0%, so the description must compensate. It gives good semantics for `owner` (filter by person) and `limit` (increasing it retrieves older days), but never explains `fresh`, which is a real parameter. Without schema descriptions, that remaining gap prevents full parameter understanding.

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 names a specific verb and resource: 'Decrypt recent basal-energy-burned samples (Apple Watch BMR estimate, kcal).' It clearly scopes the metric to basal energy/BMR rather than total energy or activity, which distinguishes it from related siblings like get_total_energy_burned and get_activity. The title reinforces the purpose.

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?

The description gives operational guidance: how daily aggregation works, how to filter by person with `owner`, how to handle incomplete rows, and how to re-read with a larger `limit` when `coverage.more_available` is true. It does not explicitly state when to prefer this tool over alternatives, but it provides strong context for common use cases and caveats.

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