The withings-mcp server lets you sync, query, and analyze Withings health data using a local SQLite cache with automatic OAuth token management.
Sync data (withings_sync): Pull body, sleep, activity, and workout data from the Withings API into a local SQLite cache, with incremental updates fetching only new data since the last sync.
Body composition (withings_get_body): Retrieve weight, fat percentage, muscle mass, bone mass, hydration, heart rate, blood pressure, and SpO2 for a given date range.
Sleep data (withings_get_sleep): Get nightly summaries (duration, sleep score, HR, respiratory rate, snoring) or detailed minute-by-minute phase breakdowns (awake, light, deep, REM).
Daily activity (withings_get_activity): Access step counts, distance, calories burned, and active time by intensity level.
Workout sessions (withings_get_workouts): View individual sessions with type, duration, heart rate, calories, and distance; filterable by category (e.g., cycling, running).
ECG & heart health (withings_get_heart): Fetch ECG recordings and atrial fibrillation (AFib) detection results live from compatible devices (ScanWatch, BPM Core).
Connected devices (withings_get_devices): List all connected Withings devices with model info, battery level, firmware, and last session date (fetched live).
Trend analysis (withings_trends): Compute weekly, monthly, or quarterly averages, min/max, and change indicators for body, sleep, or activity data, with period-over-period comparisons.
All data is stored locally for fast offline access and privacy. ECG and device info are fetched live from the API.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@withings-mcp show my weight trends for the last 3 months"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for the Withings Health API with OAuth, local SQLite cache, and trend analysis.
What makes this different from other Withings MCP servers:
Local SQLite cache for fast offline queries and historical trend analysis
Incremental sync - only fetches new data since last sync
Broad Withings coverage: 17 body-composition metrics plus sleep, daily activity, workouts, and ECG/AFib
Automatic OAuth token refresh (access tokens: 3h, refresh tokens: 1 year)
Zero dependencies beyond mcp (HTTP via stdlib)
Python 3.13+ (tested on 3.13 and 3.14, on Linux, macOS and Windows, in CI)
Tool | Description | Data source |
| Sync data from Withings API to local cache | Live API -> SQLite |
| Body composition (weight, fat%, muscle, bone, BP, SpO2) | Local cache (auto-syncs if stale) |
| Sleep summaries, or detailed phase time-series with | Cache (summary) / live (detail) |
| Daily steps, distance, calories, active time | Local cache (auto-syncs if stale) |
| Workout sessions with type, duration, HR | Local cache (auto-syncs if stale) |
| ECG recordings and AFib detection | Live API (always) |
| Connected devices with battery status | Live API (always) |
| Period averages, weekly/monthly/quarterly trends, comparisons | Local cache (auto-syncs if stale) |
The cache-backed query tools auto-sync when their data is stale, and accept live=True to bypass the cache and fetch straight from the Withings API. withings_get_heart and withings_get_devices are always live. withings_get_sleep(detail=True) returns minute-by-minute sleep phases (live, up to 7 days per request).
Related MCP server: Withings MCP Server
Python 3.13+ (tested on 3.13 and 3.14, on Linux, macOS and Windows, in CI)
uv (recommended) or pip
A Withings developer account and registered application
pip install withings-mcpOr run it without installing with uvx withings-mcp. For development from a clone:
git clone https://github.com/partymola/withings-mcp.git
cd withings-mcp
uv venv --python 3.13 .venv
uv pip install -e .Create a new application
Set the callback URL to http://localhost:8585
Note your Client ID and Client Secret
.venv/bin/withings-mcp authThis opens your browser for Withings authorization. After approving, tokens are saved locally in config/.
claude mcp add -s user withings -- /path/to/withings-mcp/.venv/bin/withings-mcpIn Claude Code, say: "Sync my Withings data"
This runs withings_sync to populate the local cache. Subsequent syncs only fetch new data.
If anything does not work - no data where you expect it, a sync that stops happening - run withings-mcp doctor. It reports the paths and credentials actually in use and what needs fixing, without making an API call.
You can also sync from the command line without an MCP client:
.venv/bin/withings-mcp sync # all data types, last 30 days
.venv/bin/withings-mcp sync --types body,sleep # a subset
.venv/bin/withings-mcp sync --days 90 # deeper history on first syncwithings-mcp Start the MCP server (stdio transport)
withings-mcp auth Interactive OAuth setup (opens the browser)
withings-mcp sync Sync data to the local cache (--types, --days)
withings-mcp doctor Check the setup and report what needs fixing
withings-mcp --version Print the installed package versionEnvironment Variable | Default | Description |
|
| Directory for credentials and tokens |
|
| SQLite database path |
"Sync my Withings data"
"Show my weight for the last 3 months"
"How has my sleep changed this year?"
"Compare my body composition this month vs last month"
"What workouts did I do in March?"
"What Withings devices do I have connected?"
"Show my sleep trends quarterly"
# Install with dev dependencies
uv pip install -e . && uv pip install pytest
# Run tests (all use in-memory SQLite with fictional data)
.venv/bin/python -m pytest tests/ -v # .venv\Scripts\python on WindowsRead-only: No tools modify data on Withings servers
Local storage: Health data stays in your local SQLite database
Token storage: OAuth tokens stored in config/ (gitignored; created 0600 on POSIX - Windows ignores the mode and governs access by ACLs)
Error messages: Never contain health data values - only status codes
Pre-commit hook: An optional hook (scripts/check-no-data.sh) blocks database files and credentials from commits - install it with the one-liner in CONTRIBUTING.md
See CONTRIBUTING.md for development setup, the test workflow, and the pre-commit hook. Changes are tracked in CHANGELOG.md.
GPL-3.0-or-later
Get daily activity summaries (steps, distance, calories, active time).
Returns one entry per day from the local cache by default. Run withings_sync first to populate the cache.
Args: start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "30d". Default: last 30 days. end_date: End date as "YYYY-MM-DD". Default: today. live: If true, fetch from Withings API instead of cache.
Returns daily activity data sorted by date, with steps, distance in km, calories, and active minutes by intensity level. Not for workout sessions -- use withings_get_workouts instead.
| Name | Required | Description | Default |
|---|---|---|---|
| live | No | ||
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains behavior: default uses cache, optional live fetch from API, returns sorted daily data with specific fields. It lacks mention of rate limits or auth, but those are secondary for a read tool. Overall, it provides sufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: summary, default behavior, arguments with defaults, return format, exclusion. It is concise but not overly terse—each sentence adds value. Could be slightly tighter, but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 optional params, cache mechanism, and an output schema (so return values are documented there), the description covers prerequisites, usage, and alternatives. It lacks error handling notes, but for this simple tool, it is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining start_date format ('YYYY-MM-DD', 'YYYY-MM', or '30d') and default (last 30 days), end_date format and default (today), and live boolean meaning. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets daily activity summaries with specific metrics (steps, distance, calories, active time). It distinguishes from withings_get_workouts by explicitly stating 'Not for workout sessions -- use withings_get_workouts instead.' The verb 'get' and resource 'activity' are clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Run withings_sync first to populate the cache.' and 'Not for workout sessions -- use withings_get_workouts instead.' This provides clear when-to-use and when-not-to-use guidance with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get body composition measurements (weight, fat, muscle, etc.).
Returns measurements from the local cache by default. Use live=True to fetch directly from Withings API. Run withings_sync first to populate the cache.
Args: start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "30d" for relative days. Default: last 30 days. end_date: End date as "YYYY-MM-DD". Default: today. metrics: Comma-separated metric filter, e.g. "weight_kg,fat_pct". Default: all available metrics. Options: weight_kg, fat_pct, fat_mass_kg, muscle_mass_kg, hydration_kg, bone_mass_kg, heart_rate, systolic_bp, diastolic_bp, spo2_pct. live: If true, fetch from Withings API instead of cache.
Returns measurements sorted by date, one entry per measurement group. Not for sleep or activity data -- use withings_get_sleep or withings_get_activity instead.
| Name | Required | Description | Default |
|---|---|---|---|
| live | No | ||
| metrics | No | ||
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses behavior: returns from cache unless live=True, requires prior withings_sync, return sort order and grouping. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with separate sections for args and notes. First sentence gives purpose. Concise yet comprehensive, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a 4-parameter tool with output schema. Covers all parameter details, return format, and caching behavior. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters are explained with formats, defaults, and allowed values. Metrics parameter lists all options. Schema coverage was 0%, so description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets body composition measurements (weight, fat, muscle, etc.). Distinguishes from siblings by explicitly saying 'Not for sleep or activity data -- use withings_get_sleep or withings_get_activity instead.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when to use (body composition), when not (sleep/activity), and alternatives. Also explains caching behavior and prerequisite: 'Run withings_sync first to populate the cache.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get connected Withings devices with battery and firmware info.
Always fetched live from the Withings API.
Returns device type, model name, battery level (high/medium/low), and last session date for each connected device.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool fetches live data and returns device type, model, battery level, and last session date. This is sufficient for a non-destructive tool with no parameters, though additional details on authentication or rate limits could be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loaded with the purpose. Every sentence adds value, and there is no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and the presence of an output schema (not shown but indicated), the description is complete. It covers the purpose, behavior, and return fields adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (0 params, 100% schema coverage). The description adds value by detailing what the return includes (battery level, firmware info), which goes beyond the empty schema. Baseline for 0 params is 4, and the added context warrants a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets connected Withings devices with battery and firmware info. The verb 'Get' and resource 'connected Withings devices' are specific, and it distinguishes itself from sibling tools that focus on other data types like activity or sleep.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It notes that the data is 'Always fetched live from the Withings API,' implying when to use this tool (for live device status). However, it does not explicitly mention when not to use it or suggest alternatives, though the sibling names naturally guide usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get ECG recordings and atrial fibrillation detection results.
Always fetched live from the Withings API (not cached due to large signal data). Requires a Withings device with ECG capability (ScanWatch, BPM Core).
Args: start_date: Start date as "YYYY-MM-DD" or "30d". Default: last 30 days. end_date: End date as "YYYY-MM-DD". Default: today.
Returns ECG recording list with timestamps, AFib classification (negative/positive/inconclusive), and heart rate. Does not include raw signal waveforms. For resting heart rate trends, use withings_get_body or withings_get_sleep instead.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behaviors: always fetched live (not cached), requires specific devices, returns ECG list with timestamps and AFib classification, and explicitly excludes raw waveforms. Minor omission: no mention of pagination or rate limits, but given simplicity of tool, transparency is high.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive: first sentence states purpose, then caching behavior, device requirements, parameter details in a clear list, return summary, and alternative tool. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only 2 optional parameters and an output schema, the description covers all essential aspects: input semantics, output contents, behavioral constraints, and sibling differentiation. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description fully compensates: specifies date formats ('YYYY-MM-DD' or '30d' for start, 'YYYY-MM-DD' for end), defaults (last 30 days, today), and purpose (define date range for ECG recordings). Adds meaning beyond schema's basic string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool fetches 'ECG recordings and atrial fibrillation detection results', distinguishing it from sibling tools like withings_get_body (resting heart rate trends) and withings_get_sleep. The verb 'Get' and specific resource are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: requires a Withings device with ECG capability (ScanWatch, BPM Core), and advises to use withings_get_body or withings_get_sleep instead for resting heart rate trends. No ambiguity about when to use this vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get sleep data (summaries or detailed phases).
Summary mode (default): nightly totals with duration, sleep score, HR, respiratory rate, and snoring. From local cache unless live=True.
Detail mode (detail=True): minute-by-minute sleep phases (awake, light, deep, REM) with HR and respiratory rate. Always fetched live. Maximum 7 days per request (Withings API limit).
Args: start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "7d". Default: last 7 days (detail) or last 30 days (summary). end_date: End date as "YYYY-MM-DD". Default: today. detail: If true, return minute-by-minute sleep phases instead of nightly summaries. Always live, max 7 days. live: If true, fetch summaries from API instead of cache. Ignored when detail=True (always live).
Returns nightly sleep data sorted by date. Not for body composition -- use withings_get_body instead.
| Name | Required | Description | Default |
|---|---|---|---|
| live | No | ||
| detail | No | ||
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavioral traits: summary uses local cache unless live=True, detail always fetched live, live is ignored when detail=True, default date ranges differ by mode. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections for summary/detail, bullet points for parameters, and a separate line for return value. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description does not need to detail return values. It covers all necessary context: modes, parameter behaviors, caveats (max 7 days), and sibling differentiation, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description provides extensive parameter details: start_date format options ('YYYY-MM-DD', 'YYYY-MM', '7d'), default behavior for both modes, end_date default, and flags effect. Fully compensates for schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets sleep data in two modes (summary or detail), lists what each mode returns, and explicitly distinguishes from sibling tool withings_get_body for body composition. The verb 'Get' and resource 'sleep' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use summary vs detail, when to use live flag, and explicitly tells when not to use (for body composition, use withings_get_body). It also notes the maximum 7-day limit for detail mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get workout sessions (type, duration, HR, calories).
Returns individual workout sessions from the local cache by default. Run withings_sync first to populate the cache.
Args: start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "90d". Default: last 90 days. end_date: End date as "YYYY-MM-DD". Default: today. category: Filter by workout type, e.g. "cycling", "walk", "run". Case-insensitive partial match. live: If true, fetch from Withings API instead of cache.
Returns workout sessions sorted by date with type, duration, calories, distance, and heart rate data. Not for daily step/activity totals -- use withings_get_activity.
| Name | Required | Description | Default |
|---|---|---|---|
| live | No | ||
| category | No | ||
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It explains cache-by-default behavior, the live fetch option, sorting by date, and prerequisites (sync). However, it does not explicitly state that the tool is read-only or mention rate limits or authentication, leaving minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief summary line followed by detailed 'Args:' section. Every sentence adds value, and it is front-loaded with key information. No redundancy or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and low schema coverage, the description covers input parameters, return fields, behavior, and prerequisites. It also distinguishes from siblings. However, it lacks details on error handling, pagination, or exact data freshness, and does not reference the output schema that exists. Still, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must fully explain parameters. It does so for all four: provides format and default for start_date (e.g., '90d', 'YYYY-MM-DD'), end_date (default today), category (case-insensitive partial match with examples), and live (boolean flag). This adds significant meaning beyond the schema's bare titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves workout sessions with specific data (type, duration, HR, calories). It distinguishes from the sibling tool withings_get_activity by specifying it is not for daily step/activity totals, providing a clear and unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs users to run withings_sync first to populate the cache, explains default cache behavior versus live API usage via the 'live' parameter, and provides default date ranges. It also gives an explicit alternative (withings_get_activity) for daily totals, offering complete when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sync Withings health data to the local cache.
Fetches data from the Withings API and stores it in SQLite for fast offline queries. Run this before using other withings_get_* tools.
Syncs incrementally: only fetches data newer than the last sync. First sync fetches the specified number of days of history.
Args: data_types: What to sync. Options: "all", "body", "sleep", "activity", "workouts". Comma-separated for multiple, e.g. "body,sleep". Default: "all". days: Days of history for first sync (default: 30). Ignored on subsequent syncs (uses last sync timestamp).
Returns summary of records synced per data type. Not for querying data - use withings_get_body, withings_get_sleep, withings_get_activity, or withings_get_workouts instead.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| data_types | No | all |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses incremental sync behavior, first sync history fetching, storage in SQLite, and return summary. Missing minor details like API rate limits or authentication, but still comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear heading, paragraphs, bullet points, and explicit sections for args and returns. It is concise yet complete, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and an output schema, the description covers purpose, usage guidelines, parameter semantics, behavioral details, and returns. It fully equips the AI agent to select and invoke the tool correctly, even in the context of sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add full meaning. It explains data_types options with examples and default, and clarifies that 'days' applies only to the first sync. This adds significant value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Sync Withings health data to the local cache.' It uses a specific verb-resource pair and explicitly distinguishes from sibling query tools like withings_get_body and withings_get_sleep.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Run this before using other withings_get_* tools' and 'Not for querying data - use withings_get_body, withings_get_sleep, withings_get_activity, or withings_get_workouts instead.' It clearly tells the AI agent when and when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyse trends in cached health data.
Computes averages, min/max, and changes over time from the local cache. Auto-syncs if the cache is stale (no sync today).
Args: data_type: What to analyse. Options: "body", "sleep", "activity". period: Aggregation period. Options: "weekly", "monthly", "quarterly". Default: "monthly". start_date: Start date as "YYYY-MM-DD" or "12m" for relative. Default: last 12 months. end_date: End date as "YYYY-MM-DD". Default: today. compare: Compare two periods. Format: "last_30d vs previous_30d", "2026-03 vs 2026-02", "2026-Q1 vs 2025-Q4". When set, period/start_date/end_date are ignored.
Returns aggregated averages with change indicators. For body data: weight, fat%, muscle trends. For sleep: duration, score, HR trends. For activity: steps, distance, calorie trends. Not for raw data -- use withings_get_body/sleep/activity instead.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | monthly | |
| compare | No | ||
| end_date | No | ||
| data_type | No | body | |
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses auto-sync behavior on stale cache and explains that the 'compare' parameter overrides others. While it doesn't explicitly state read-only or non-destructive nature, it implies no side effects beyond cache refresh. A minor gap but still informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (summary, args, returns, exclusion). While a bit lengthy, it is front-loaded and every sentence adds value. Could be slightly more concise but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no annotations, no schema descriptions, and an output schema (which explains returns), the description provides complete context: explains return values per data type, cache sync behavior, and parameter interactions. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain all parameters. It covers all 5 parameters with options, formats, defaults, and interactions (e.g., compare overrides others). Examples are provided, making it very clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it analyzes trends in cached health data, specifying it computes averages, min/max, and changes over time. It distinguishes itself from sibling tools by stating 'Not for raw data -- use withings_get_body/sleep/activity instead,' fulfilling the specific verb+resource+scope requirement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use (trend analysis on cached data) and when not to use (raw data), naming alternatives. It also notes auto-syncs if cache is stale, providing clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0withings_get_activitywithings_get_bodywithings_get_deviceswithings_get_heartwithings_get_sleepwithings_get_workoutswithings_syncwithings_trendsEach tool targets a distinct domain (activity, body, devices, heart, sleep, workouts, sync, trends) with clear descriptions and explicit 'Not for' disclaimers, eliminating ambiguity.
All tools follow the 'withings_' prefix with a consistent pattern: 'get_' for data retrieval, plus 'sync' and 'trends' as distinct actions, making navigation predictable.
With 8 tools covering synchronization, data retrieval across key health categories, and trend analysis, the set is well-scoped and not excessive.
The tool surface covers all major Withings data types (activity, body, sleep, heart, workouts, devices) plus sync and analysis, with no obvious gaps for a read-only health data API.
Read wearables and lab health data — sleep, activity, workouts, timeseries, lab tests and orders.
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Private Apple Health metrics and workout detail for ChatGPT, Claude, and any MCP client.
Read your workouts, history, and stats; create and schedule new workouts. Writes are additive only.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/partymola/withings-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
