Withings Health API용 MCP 서버로, OAuth, 로컬 SQLite, 추세 분석을 지원합니다.
다른 Withings MCP 서버와 차별화되는 점:
빠른 오프라인 조회 및 과거 추세 분석을 위한 로컬 SQLite 캐시
증분 동기화 - 마지막 동기화 이후의 새 데이터만 가져옵니다
광범위한 Withings 지원: 17가지 체성분 지표와 수면, 일일 활동, 운동, 심전도(ECG)/심방세동(AFib)
자동 OAuth 토큰 갱신 (액세스 토큰: 3시간, 리프레시 토큰: 1년)
mcp 외에 추가 의존성 없음 (HTTP는 표준 라이브러리 사용)
Python 3.13+
도구 | 설명 | 데이터 소스 |
| Withings API에서 로컬 캐시로 데이터 동기화 | 실시간 API -> SQLite |
| 체성분 (체중, 체지방률, 근육량, 골량, 혈압, SpO2) | 로컬 캐시 (오래된 경우 자동 동기화) |
| 수면 요약, 또는 | 캐시 (요약) / 실시간 (상세) |
| 일일 걸음 수, 거리, 칼로리, 활동 시간 | 로컬 캐시 (오래된 경우 자동 동기화) |
| 운동 세션 (유형, 시간, 심박수) | 로컬 캐시 (오래된 경우 자동 동기화) |
| 심전도(ECG) 기록 및 심방세동(AFib) 감지 | 실시간 API (항상) |
| 배터리 상태를 포함한 연결된 기기 | 실시간 API (항상) |
| 기간 평균, 주간/월간/분기별 추세, 비교 | 로컬 캐시 (오래된 경우 자동 동기화) |
캐시 기반 조회 도구는 데이터가 오래된 경우 자동으로 동기화하며, live=True를 전달하면 캐시를 우회하고 Withings API에서 직접 가져옵니다. withings_get_heart와 withings_get_devices는 항상 실시간으로 동작합니다. withings_get_sleep(detail=True)는 분 단위 수면 단계를 반환합니다 (실시간, 요청당 최대 7일).
Related MCP server: Withings MCP Server
Python 3.13+
uv (권장) 또는 pip
Withings 개발자 계정 및 등록된 애플리케이션
pip install withings-mcp또는 uvx withings-mcp로 설치 없이 실행할 수 있습니다. 클론에서 개발하는 경우:
git clone https://github.com/partymola/withings-mcp.git
cd withings-mcp
uv venv --python 3.13 .venv
uv pip install -e .새 애플리케이션 생성
콜백 URL을 http://localhost:8585로 설정
클라이언트 ID와 클라이언트 시크릿을 기록
.venv/bin/withings-mcp auth브라우저에서 Withings 인증이 열립니다. 승인 후 토큰은 config/에 로컬로 저장됩니다.
claude mcp add -s user withings -- /path/to/withings-mcp/.venv/bin/withings-mcpClaude Code에서 "Sync my Withings data"라고 말합니다.
withings_sync를 실행하여 로컬 캐시를 채웁니다. 이후 동기화는 새 데이터만 가져옵니다.
문제가 발생한 경우 - 예상한 위치에 데이터가 없거나, 동기화가 중단되는 경우 - withings-mcp doctor를 실행합니다. API 호출 없이 실제 사용 중인 경로와 자격 증명, 그리고 수정해야 할 사항을 보고합니다.
MCP 클라이언트 없이도 명령줄에서 동기화할 수 있습니다:
.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 version환경 변수 | 기본값 | 설명 |
|
| 자격 증명 및 토큰 저장 디렉터리 |
|
| SQLite 데이터베이스 경로 |
"내 Withings 데이터 동기화해 줘"
"지난 3개월간 체중 변화 보여 줘"
"올해 수면 패턴이 어떻게 변했어?"
"이번 달과 지난달 체성분 비교해 줘"
"3월에 어떤 운동을 했어?"
"연결된 Withings 기기 뭐가 있어?"
"분기별 수면 추세 보여 줘"
# 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 Windows읽기 전용: Withings 서버의 데이터를 수정하는 도구가 없습니다
로컬 저장: 건강 데이터는 로컬 SQLite 데이터베이스에만 저장됩니다
토큰 저장: OAuth 토큰은 config/에 저장됩니다 (gitignored; POSIX에서는 0600 권한으로 생성 - Windows는 권한을 무시하고 ACL로 관리)
오류 메시지: 건강 데이터 값을 포함하지 않습니다 - 상태 코드만 포함
Pre-commit 훅: CONTRIBUTING.md의 한 줄 명령으로 설치하는 선택적 훅(scripts/check-no-data.sh)이 데이터베이스 파일과 자격 증명이 커밋되는 것을 차단합니다
개발 환경 설정, 테스트 워크플로우, pre-commit 훅에 대한 자세한 내용은 CONTRIBUTING.md를 참조하세요. 변경 사항은 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. Names match exactly and are case-sensitive; one that is not on this list is refused, naming them. Options: weight_kg, height_m, lean_mass_kg, fat_pct, fat_mass_kg, muscle_mass_kg, hydration_kg, bone_mass_kg, heart_rate, systolic_bp, diastolic_bp, spo2_pct, temperature_c, body_temperature_c, pulse_wave_velocity, visceral_fat_index, basal_metabolic_rate.
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 the description fully discloses behavior: cache default, live override, sync requirement, sorted results, one entry per group, and metric validation by refusing invalid names.
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-organized with a clear purpose statement, parameter list, and return info. The metric list is necessary for usability, and 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?
Covers return format, exclusions, prerequisites, and alternatives, making it self-sufficient for an agent to decide and call the tool correctly.
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?
Despite 0% schema description coverage, the text provides thorough parameter details: date formats, defaults, exact metric options, and the live flag's effect, fully compensating for 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?
Clearly states it gets body composition measurements and explicitly distinguishes from sleep and activity tools by pointing to withings_get_sleep and withings_get_activity.
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 states when to use this tool (body composition) and when not to (sleep/activity), plus provides guidance on cache vs. live fetching and the need to run withings_sync first.
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, case-insensitive partial match. A value matching none of the categories below is refused, naming the ones your cache holds. Options: badminton, baseball, basketball, bmx, bodyboard, boxing, calisthenics, climbing, cycling, dancing, elliptical, fencing, football, golf, handball, hiking, hockey, horse_riding, ice_hockey, ice_skating, indoor_cycling, indoor_running, indoor_walk, kitesurfing, martial_arts, multi_sport, other, pilates, rowing, rugby, run, skating, skiing, snowboarding, soccer, squash, surfing, swimming, table_tennis, tennis, volleyball, walk, waterpolo, weightlifting, windsurfing, wrestling, yoga, zumba.
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 bears full responsibility for behavior. It clearly states it returns data 'sorted by date with type, duration, calories, distance, and heart rate data' and explains the default cache vs. live API behavior. It does not mention potential side effects (e.g., API rate limits), but as a read-only operation with no mutation, this is sufficient for transparency.
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 summary, an 'Args' section, and a return/exclusion note. It is front-loaded with the purpose. The category list is long but necessary for completeness. Minor redundancy (repeating 'from cache' in both the first line and the 'live' description) could be trimmed, but overall it is appropriately concise.
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 that an output schema exists (not shown here), the description need not enumerate return fields in detail, but it does mention the return content. It covers prerequisites, parameter semantics, and the scope limitation. It is complete enough for an agent to know when and how to invoke the tool without ambiguity.
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?
Although the input schema provides no descriptions (0% coverage), the description text thoroughly explains each parameter. It specifies date formats ('YYYY-MM-DD', 'YYYY-MM', or '90d'), defaults ('last 90 days', 'today'), the category filter case-insensitivity and the full list of options, and the 'live' flag's effect. This adds meaningful semantics beyond the bare 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: 'Get workout sessions (type, duration, HR, calories).' It also explicitly distinguishes itself from the sibling tool by noting 'Not for daily step/activity totals -- use withings_get_activity.' The verb 'Get' and the resource 'workout sessions' are specific and unambiguous.
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 when-not guidance ('Not for daily step/activity totals') and names the alternative tool. It also gives a prerequisite: 'Run withings_sync first to populate the cache.' Additionally, it explains the 'live' parameter for fetching from the API instead of cache, offering clear decision-making 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 the transparency burden. It states the computation/return behaviour and the auto-sync side effect, but it does not fully spell out whether the sync mutates local storage or whether network access may occur; the mention of auto-sync implies this but leaves some ambiguity.
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 organised but contains some redundancy: 'Computes averages, min/max, and changes over time' is repeated as 'Returns aggregated averages with change indicators'. Still, it is concise overall and easy to scan.
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?
The description covers purpose, parameters, return content per data type, and explicitly routes raw-data requests to sibling getter tools. It also clarifies the cache/sync context, making it self-contained for an agent deciding between this tool and its siblings.
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?
Although the input schema lacks descriptions, the prose explains every parameter: data_type options, period enum/default, start_date/end_date formats and defaults, and compare format including the rule that compare overrides the other date parameters. This is more than enough for an agent to fill the arguments correctly.
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: analysing trends in cached health data with aggregates (averages, min/max, changes). It explicitly distinguishes itself from raw-data getters by naming the alternative tools.
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 gives concrete guidance on when to use the tool (trends/aggregates) and when not to use it ('Not for raw data -- use withings_get_body/sleep/activity instead'). It also explains the auto-sync behaviour when the cache is stale, providing useful context for invocation.
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.
v0.8.0withings_trends2 fields changedInput schema / properties / data_type / enumAdded value: +[
+ "body",
+ "sleep",
+ "activity"
+]Input schema / properties / period / enumAdded value: +[
+ "weekly",
+ "monthly",
+ "quarterly"
+]v0.1.0withings_get_activitywithings_get_bodywithings_get_deviceswithings_get_heartwithings_get_sleepwithings_get_workoutswithings_syncwithings_trendsScored across 8 tools
Each tool targets a distinct data domain: activity, workouts, body composition, sleep, heart ECG, devices, and trend analysis. Cross-references are used effectively to prevent confusion between similar tools like activity vs workouts and body vs sleep.
Most tools follow a clear withings_get_<resource> pattern, making the set predictable. The exceptions are withings_sync and withings_trends, which break the get- verb pattern but are still understandable and not chaotic.
With 8 tools, the server is well-scoped for a health-data integration covering sync, raw data retrieval, and analysis. Each tool has a clear purpose and the count feels neither bloated nor thin.
The tool surface covers the major Withings health domains: activity, workouts, body composition, sleep, heart/ECG, devices, and trend analysis. The sync tool provides a reasonable update mechanism, and there are no obvious dead ends or missing lifecycle operations.
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.
Read sleep, readiness, activity, stress, heart rate and workouts from the Oura Ring.
Read WHOOP recovery, sleep, cycles, workouts and body measurements.