Skip to main content
Glama
littlenew117

mibly-apple-health-mcp

by littlenew117
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Apple Health detail query

health_detail

Query detailed Apple Health records for a single data type over a date range, up to the last 365 days. Retrieve sleep, steps, heart rate, HRV, workouts, weight, body fat, and menstrual flow data.

Instructions

Detailed time-range query for one health data type. Limited to the last 365 days.

Health data consumption and presentation (Local and Cloud):

  • Time/timezone: sleepStart, sleepEnd, start and end may be ISO 8601 UTC timestamps ending in Z. Preserve raw timestamps for storage and calculations. When presenting clock times, convert UTC to the user's local timezone when that timezone is known. Do not display UTC clock times as though they were local. Do not assume the Agent host timezone: a VPS or server may use a different timezone. If the user's timezone is unknown, explicitly label UTC times as UTC or ask for their timezone.

  • Sleep date: date is already the wake-up calendar date calculated by Mibly using the iPhone's local calendar. Treat date as authoritative for the sleep record. Do not recompute or change date from sleepStart/sleepEnd UTC timestamps.

  • Sleep minutes: durations and stage values may contain fractional minutes. Preserve raw fractional values for calculations. When presenting whole minutes, round to the nearest minute; do not truncate (for example, 59.6 minutes displays as 60 minutes).

  • Missing sleep stages: null means stage data is unavailable. Never interpret null as 0. Never invent or infer a missing sleep stage.

  • Body Fat: bodyFat.value is already a human percentage: 23.5 means 23.5%. Do not divide by 100 or multiply by 100 when presenting it.

  • Heart rate: a heartRate sample is an hourly summary, not a single reading. value is that hour's average bpm; heartRateSummary has min, avg, max, count and context. context is sedentary (still), active (moving) or unknown (Apple Health did not label it); the same hour can appear once per context. The newest hour may still be in progress and is replaced when updated. Older samples may be single readings without heartRateSummary.

  • Resting heart rate: restingHeartRate and walkingHeartRateAverage are separate daily values from Apple Health (one per day, bpm). Use restingHeartRate for the user's resting heart rate; never derive it from heartRate minimums or sedentary averages, and do not compare active hours with sedentary hours as if they were the same kind of reading. These are consumption/presentation rules only; preserve the raw Health data and existing calculations.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
endYesISO 8601 end of the range.
typeYesWhich health data type to query. Sleep summaries use wake-up dates and nullable stage minutes; bodyFat values are percentages, not fractions.
startYesISO 8601 start of the range.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.2.1

TDQS

B3.3/5.0
Behavior3/5

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

With no annotations, the description must carry the full behavioral burden. It discloses the 365-day limit and rich data-interpretation rules (UTC to local time, null semantics, fractional minutes), but says nothing about read-only status, error behavior, rate limits, or response shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is well front-loaded, but the definition then runs to several hundred words of consumption/presentation rules. Much of it is domain guidance rather than tool-selection or invocation information, making it excessive for the description field.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description thoroughly covers how to interpret returned health values, which is valuable given there is no output schema. It still omits return structure, pagination, and failure modes, leaving gaps for an agent invoking a query tool with no annotations.

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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: timezone handling for start/end ISO timestamps, sleep date authority, bodyFat percentage rules, and the distinction between hourly heartRate summaries and daily resting heart rate values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb (query), resource (health data type), and scope (time-range, last 365 days). It implicitly distinguishes itself from the sibling health_now by being historical/detailed rather than current, though it never names the sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

The 'last 365 days' limit is a useful constraint, and 'time-range query' implies historical use versus health_now's present-state use. However, there is no explicit when-to-use/when-not-to-use guidance or named alternative.

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

Deploy Server

Other Tools