Fitness AI Connector

Return Garmin attribution text. Call once per conversation when first presenting Garmin data. Retrieves the attribution_header and attribution_footer that should accompany Garmin-sourced data in the data-presentation turn. Do NOT call this before every subsequent tool invocation within the same conversation thread; the attribution from the first call carries through unless the data context materially changes (new data type fetched, new device introduced). Returns: dict with: - attribution_header: display this at the start of data presentation - attribution_footer: display this at the end of the same turn - compliance: GCDP v2 Brand Guidelines reference Note: Health API does not include device model information, so the attribution is generic ("Data from Garmin"). Activity data may include device names per entry.

acknowledge_garmin_source

List Garmin activities (runs, swims, rides, etc.) in a date range. Returns device, activity_type, date, start time (UTC/local), name, duration, distance, calories, heart rate, speed/pace, and elevation per activity. Use for: workout history, training consistency, finding activity_ids for get_activity_details. Multisport: parent activities (e.g. MULTI_SPORT) carry is_parent=true; child legs (swim/bike/run/transition) reference their parent via parent_id. Use child activity_ids with get_activity_details for per-leg analysis. Fields missing from a given activity are omitted, not null. Tool chaining: Call this first to obtain activity_ids, then get_activity_details (Basic+) for deep analysis. Tier: All tiers. Free: 2-day history. Paid plans: extended history. Coaching: Summarize patterns — volume, consistency, variety. Don't just list. Attribution scope: When this tool is called or its data is directly cited in a turn, include BOTH attribution_header and attribution_footer (returned in the response dict) in your output. Do not repeat either in later turns that build on this data without re-fetching. Per-activity device: Each activity includes a 'device' field (e.g., 'Forerunner 955', 'Tacx Training'). Per GCDP "Combined or Derived Data" per-entry attribution, include the device name with each activity entry when displaying, since users may have multiple devices. Example: '2026-03-20 Running (Forerunner 955) — 10.5km', or a 'Device' table column. Incident notice: If the response contains an `incident_notice` field with one or more entries, you MUST inform the user about the ongoing incident at the start of your reply, translated into the user's conversation language. Include severity, what's affected, expected resolution time if available, and source_url for reference.

get_activities

Get detailed Garmin activity metrics: avg/max heart rate, steps, pace, lap splits, HR drift, power and cadence stats, ascent/descent. Use for: pace breakdown, lap splits, "how was my run?", interval analysis. Gym, ball-sport, rowing and similar activities return an hr_only computed set: measured avg/max heart rate and duration only (no pace, distance, or zone estimates). Prerequisite: Call get_activities first to obtain a valid activity_id. Tier: Paid plans only. Free returns tier_limit error — suggest get_activities as a free alternative. Coaching: Give actionable feedback — HR drift, pace drops, lap-to-lap changes. Note: HR zone distribution is not provided because Garmin's Health API does not expose the user's max HR or zone settings, and computing zones without them would be inaccurate. Normalized power, IF, TSS, Training Effect, respiration, and power zones are also not available from Garmin's Health API (they exist only in Garmin Connect / FIT files). Attribution scope: When this tool is called or its data is directly cited in a turn, include BOTH attribution_header and attribution_footer (returned in the response dict) in your output. Do not repeat either in later turns that build on this data without re-fetching. Per-entry device: If the response contains a device name, include it in the display; do not fabricate device names when not provided. Incident notice: If the response contains an `incident_notice` field with one or more entries, you MUST inform the user about the ongoing incident at the start of your reply, translated into the user's conversation language. Include severity, what's affected, expected resolution time if available, and source_url for reference. Time series (opt-in): pass include_series to also get measured time-series points ([t_offset_s, value], seconds from activity start). Available fields vary per activity — unknown names are reported in series_meta.unavailable_fields, not errors. The actually applied granularity is reported in series_meta — narrow the range and re-call to zoom in. series_meta.coarsened=true means the server deviated from the request (lower-bound round-up or point guard); decimation that honors the requested interval does not set it.

get_activity_details

Get body composition measurements (weight, BMI, body fat %, muscle mass, bone mass, body water %) from Garmin for a date range. Data exists only on days a measurement was taken. Use for: weight tracking, body composition trends, "what's my weight?" queries. Fields are sparse — manual entries may carry only weight and BMI. Tier: All tiers. History window follows the plan's health summary window. If the requested range is older than the window, it is clipped and the response carries clipped_to_tier_window=true. data_status semantics: 'no_data' = no measurements in the period (the user only gets data on days they weigh in via Garmin Index scale or manual entry in Garmin Connect) — do not treat it as an error. Attribution scope: When this tool is called or its data is directly cited in a turn, include BOTH attribution_header and attribution_footer (returned in the response dict) in your output. Do not repeat either in later turns that build on this data without re-fetching. Incident notice: If the response contains an `incident_notice` field with one or more entries, you MUST inform the user about the ongoing incident at the start of your reply, translated into the user's conversation language. Include severity, what's affected, expected resolution time if available, and source_url for reference.

get_body_composition

Get menstrual cycle tracking snapshots from Garmin Connect. Returns cycle phase (with phase type), day in cycle, period start date, period length, cycle length distinguished as predicted or actual, fertile window (start and length), and days until the next phase. Each snapshot carries a `mode` field ("menstrual" or "pregnancy"). When the user is in a pregnant phase, snapshots are presented with pregnancy semantics (trimester phase, day of pregnancy, due date). Blood glucose and weight-goal logs are not exposed. Use for: cycle phase questions, "where am I in my cycle?", fertile window and next-phase estimates, period tracking summaries. Data availability: snapshots exist only when the user tracks their menstrual cycle in the Garmin Connect app and has MCT data sharing enabled in Garmin Connect settings. A 'no_data' status means no snapshots in the period — it is not an error. Tier: All tiers. History window follows the plan's health summary window. If the requested range is older than the window, it is clipped and the response carries clipped_to_tier_window=true. Attribution scope: When this tool is called or its data is directly cited in a turn, include BOTH attribution_header and attribution_footer (returned in the response dict) in your output. Do not repeat either in later turns that build on this data without re-fetching. Incident notice: If the response contains an `incident_notice` field with one or more entries, you MUST inform the user about the ongoing incident at the start of your reply, translated into the user's conversation language. Include severity, what's affected, expected resolution time if available, and source_url for reference.

get_cycle_data

Retrieve daily Garmin health snapshot: activity (steps, calories, heart rate), sleep (duration, stages, score), stress (body battery), HRV. Use for: daily wellness check, sleep quality, stress levels, recovery status, "how am I doing today?" queries. When present in the data, sleep includes Garmin sub-score qualifiers (sub_scores) and nap totals; daily includes max stress, stress-band durations (stress_duration_s), and goal values (goals). Tier: All tiers. Free: 2-day history. Paid plans: extended history. Coaching: Interpret, don't just report. Correlate sleep with stress, suggest rest when HRV is low. data_status semantics: 'no_data' = data hasn't arrived yet; inform user and mention 'latest_available_date'. 'partial' = report available data, note missing types. Dates are in user's local timezone (YYYY-MM-DD). Attribution scope: When this tool is called or its data is directly cited in a turn, include BOTH attribution_header and attribution_footer (returned in the response dict) in your output. Do not repeat either in later turns that build on this data without re-fetching or quoting specific numbers. Incident notice: If the response contains an `incident_notice` field with one or more entries, you MUST inform the user about the ongoing incident at the start of your reply, translated into the user's conversation language. Include severity, what's affected, expected resolution time if available, and source_url for reference. Advisories: If the response contains an `advisories` field, adjust your tool usage accordingly. Code `repeated_single_day_calls` means several single-day requests were detected within a short period — for multi-day questions, prefer one get_trends call (see `suggested_tool`) over repeated single-day calls. Time series (opt-in): pass include_series to also get measured time-series points ([offset_s, value]). Each series' time basis (t0_utc + tz_offset_s) and the actually applied granularity are reported in series_meta — narrow the range and re-call to zoom in. series_meta.coarsened=true means the server deviated from the request (lower-bound round-up or point guard); decimation that honors the requested interval does not set it.

get_health_summary

Get FAQ and troubleshooting guidance for common issues (connection, accounts, data availability, plans). Returns the full FAQ (question/answer pairs) from the public support site. Filter to the entries relevant to the user's situation and answer in the user's conversation language. The response also carries an account_diagnosis field reporting whether another sign-in with the same email address holds the user's Garmin connection or subscription (helpful when data or a paid plan seems missing). Available on all plans. If the FAQ cannot be fetched, the response degrades to a fallback carrying the FAQ page URL and a support contact instead of an error.

get_help

Analyze Garmin long-term trends: weekly averages, directional changes, pattern detection. Use for: progress over time, "am I improving?", weekly/monthly comparisons, training load assessment. Tier: Paid plans only. Free returns tier_limit error — suggest get_health_summary for individual date comparisons. Note: If status=not_implemented, acknowledge and use get_health_summary/get_activities for multiple dates instead. Coaching: Interpret trends proactively — flag fatigue, celebrate improvements. Sparse metrics: vo2max, weight, and body_battery return measured-days-only data_points (days without a measurement are omitted, never filled) with an arithmetic summary only — no weekly_averages, no trend direction. Interpret the point series yourself. Attribution scope: When this tool is called or its data is directly cited in a turn, include BOTH attribution_header and attribution_footer (returned in the response dict) in your output. Do not repeat either in later turns that build on this data without re-fetching or quoting specific numbers. Incident notice: If the response contains an `incident_notice` field with one or more entries, you MUST inform the user about the ongoing incident at the start of your reply, translated into the user's conversation language. Include severity, what's affected, expected resolution time if available, and source_url for reference. Long windows are summarized automatically: the finest granularity (daily / weekly / monthly) whose point count fits the max_points budget is chosen; weekly/monthly responses return `buckets` instead of daily data_points. Check `granularity` and `effective_window` in the response.

get_trends

Get Garmin connection status, subscription tier, VO2max (running, plus cycling when measured), fitness age. Call at conversation start for user context. Guide disconnected users to connect. No parameters required. Incident notice: If the response contains an `incident_notice` field with one or more entries, you MUST inform the user about the ongoing incident at the start of your reply, translated into the user's conversation language. Include severity, what's affected, expected resolution time if available, and source_url for reference.

get_user_profile

Manage account: 'portal' for billing and plan management, 'delete_account' for account deletion (30-day recovery). Present returned URLs as clickable links.

manage_subscription