garmin-owl

Overview Schema Source Related Servers Discussions Admin

get_activities

Read-only

List Garmin activity summaries within an inclusive date range of up to 366 days, newest first. Filter by activity type or minimum duration, and page results for long ranges.

Instructions

List activity summaries whose start falls in an inclusive calendar date range of at most 366 days, newest first by default.

With both dates omitted, uses the last 14 days including today. With only end_date supplied, uses the 30 days ending on that date. Use for calendar ranges such as a month; use get_recent_activities for a rolling window with a type filter, get_activity for one activity's laps, zones, and notes, or get_training_week for Monday-Sunday totals.

For long ranges, filter with activity_types and min_duration_minutes, use compact=true, and page with offset. Returns {start_date, end_date, limit, count, matched, truncated, next_offset, activities}. matched counts every activity passing the filters; truncated is true when more matched than this page holds, and next_offset is the offset of the next page. A page also stops early (size_capped) rather than overflow the client. has_description marks activities with notes; get_activity returns the text. Metrics an activity did not measure (an indoor workout's distance or speed) are omitted, never zero. start_time is ISO 8601 with an explicit UTC offset and already local.

Requires saved local Garmin authentication (garmin-owl-auth). Reads Garmin and may update the local cache; never changes your Garmin account. Garmin failures are not retried automatically.

Input Schema

Name	Required	Description	Default
`limit`	No	Maximum number of activities returned, from 1 to 100; defaults to 20. This is a result cap, not a page number.
`order`	No	desc (default) is newest first; asc is oldest first.	desc
`offset`	No	Number of matching activities to skip, for paging: pass the previous response's next_offset. Defaults to 0.
`compact`	No	When true, return only id, name, start_time, type, duration, distance, calories, average/max HR, training load and effects, vo2_max, recovery HR (when cached) and has_description: about a third of the size. Defaults to false.
`end_date`	No	Inclusive end date, YYYY-MM-DD; omit or pass null for today in the server's local timezone.
`start_date`	No	Inclusive start date, YYYY-MM-DD; must not follow end_date. Range is at most 366 days. Defaults to 29 days before end_date; if both dates are omitted, uses the last 14 days instead.
`activity_types`	No	Optional Garmin activity type keys to keep, matched case-insensitively, e.g. ["indoor_cardio", "strength_training"] or ["running"]. Filtering happens before limit and offset. Omit for all types.
`min_duration_minutes`	No	Optional minimum moving duration in minutes, e.g. 20 to drop short walks. Activities without a reported duration are excluded.

Output Schema

Name	Required	Description
`count`	Yes	Number of activities returned.
`limit`	Yes
`order`	No
`offset`	No
`matched`	No	Activities in the range that passed every filter.
`end_date`	Yes
`truncated`	Yes	True when more activities matched than this response holds; pass next_offset as offset to get the rest.
`activities`	No
`start_date`	Yes
`next_offset`	No	offset for the next page, present only when more activities matched.
`size_capped`	No	True when the page stopped before limit to keep the response small.
`availability`	No
`activity_type`	No
`activity_types`	No
`min_duration_minutes`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed31 schema fields changedv0.3.1Oct 24, 2026

addedInput schema / properties / activity_types

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 20,
+      "minItems": 1,
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional Garmin activity type keys to keep, matched case-insensitively, e.g. [\"indoor_cardio\", \"strength_training\"] or [\"running\"]. Filtering happens before limit and offset. Omit for all types.",
+  "title": "Activity Types"
+}

addedInput schema / properties / compact

Added value: +{
+  "default": false,
+  "description": "When true, return only id, name, start_time, type, duration, distance, calories, average/max HR, training load and effects, vo2_max, recovery HR (when cached) and has_description: about a third of the size. Defaults to false.",
+  "title": "Compact",
+  "type": "boolean"
+}

changedInput schema / properties / end_date / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / end_date / description

Added value: +"Inclusive end date, YYYY-MM-DD; omit or pass null for today in the server's local timezone."

addedInput schema / properties / limit / description

Added value: +"Maximum number of activities returned, from 1 to 100; defaults to 20. This is a result cap, not a page number."

addedInput schema / properties / limit / maximum
```
Added value: +100
```
addedInput schema / properties / limit / minimum
```
Added value: +1
```

addedInput schema / properties / min_duration_minutes

Added value: +{
+  "anyOf": [
+    {
+      "exclusiveMinimum": 0,
+      "maximum": 1440,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional minimum moving duration in minutes, e.g. 20 to drop short walks. Activities without a reported duration are excluded.",
+  "title": "Min Duration Minutes"
+}

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Number of matching activities to skip, for paging: pass the previous response's next_offset. Defaults to 0.",
+  "maximum": 10000,
+  "minimum": 0,
+  "title": "Offset",
+  "type": "integer"
+}

addedInput schema / properties / order

Added value: +{
+  "default": "desc",
+  "description": "desc (default) is newest first; asc is oldest first.",
+  "enum": [
+    "desc",
+    "asc"
+  ],
+  "title": "Order",
+  "type": "string"
+}

changedInput schema / properties / start_date / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / start_date / description

Added value: +"Inclusive start date, YYYY-MM-DD; must not follow end_date. Range is at most 366 days. Defaults to 29 days before end_date; if both dates are omitted, uses the last 14 days instead."

addedOutput schema / $defs

Added value: +{
+  "ActivitySummary": {
+    "properties": {
+      "activity_id": {
+        "title": "Activity Id",
+        "type": "integer"
+      },
+      "activity_training_load": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Activity Training Load"
+      },
+      "activity_type": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Activity Type"
+      },
+      "aerobic_training_effect": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Aerobic Training Effect"
+      },
+      "anaerobic_training_effect": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Anaerobic Training Effect"
+      },
+      "average_cadence": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Average Cadence"
+      },
+      "average_hr_bpm": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Average Hr Bpm"
+      },
+      "average_moving_speed_mps": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Average Moving Speed Mps"
+      },
+      "average_power_w": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Average Power W"
+      },
+      "average_respiration": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Average Respiration"
+      },
+      "average_speed_mps": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Average Speed Mps"
+      },
+      "average_stride_length_m": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Average Stride Length M"
+      },
+      "calories_kcal": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Calories Kcal"
+      },
+      "description": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Description"
+      },
+      "distance_m": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Distance M"
+      },
+      "duration_seconds": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Duration Seconds"
+      },
+      "elapsed_seconds": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Elapsed Seconds"
+      },
+      "elevation_gain_m": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Elevation Gain M"
+      },
+      "elevation_loss_m": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Elevation Loss M"
+      },
+      "feel": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Feel"
+      },
+      "has_description": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Has Description"
+      },
+      "highest_respiration": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Highest Respiration"
+      },
+      "hr_zones_seconds": {
+        "anyOf": [
+          {
+            "additionalProperties": {
+              "type": "number"
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Hr Zones Seconds"
+      },
+      "intensity_factor": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Intensity Factor"
+      },
+      "lowest_respiration": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Lowest Respiration"
+      },
+      "max_cadence": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Max Cadence"
+      },
+      "max_hr_bpm": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Max Hr Bpm"
+      },
+      "max_power_w": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Max Power W"
+      },
+      "moderate_intensity_minutes": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Moderate Intensity Minutes"
+      },
+      "moving_duration_seconds": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Moving Duration Seconds"
+      },
+      "name": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Name"
+      },
+      "normalized_power_w": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Normalized Power W"
+      },
+      "perceived_effort": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Perceived Effort"
+      },
+      "recovery_hr_bpm": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Recovery Hr Bpm"
+      },
+      "start_time": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Activity start: ISO 8601 with an explicit UTC offset, e.g. 2026-10-09T23:18:16+02:00. The wall time is already local; never add the offset again. The offset is the one Garmin recorded for the device at that moment, or this computer's time zone when Garmin gives only UTC.",
+        "title": "Start Time"
+      },
+      "steps": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Steps"
+      },
+      "training_effect_label": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Training Effect Label"
+      },
+      "training_stress_score": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Training Stress Score"
+      },
+      "vigorous_intensity_minutes": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Vigorous Intensity Minutes"
+      },
+      "vo2_max": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Vo2 Max"
+      }
+    },
+    "required": [
+      "activity_id"
+    ],
+    "title": "ActivitySummary",
+    "type": "object"
+  },
+  "AvailabilityNotice": {
+    "properties": {
+      "field": {
+        "title": "Field",
+        "type": "string"
+      },
+      "message": {
+        "title": "Message",
+        "type": "string"
+      },
+      "status": {
+        "title": "Status",
+        "type": "string"
+      }
+    },
+    "required": [
+      "field",
+      "status",
+      "message"
+    ],
+    "title": "AvailabilityNotice",
+    "type": "object"
+  }
+}

addedOutput schema / properties / activities

Added value: +{
+  "items": {
+    "$ref": "#/$defs/ActivitySummary"
+  },
+  "title": "Activities",
+  "type": "array"
+}

addedOutput schema / properties / activity_type

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Activity Type"
+}

addedOutput schema / properties / activity_types

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Activity Types"
+}

addedOutput schema / properties / availability

Added value: +{
+  "items": {
+    "$ref": "#/$defs/AvailabilityNotice"
+  },
+  "title": "Availability",
+  "type": "array"
+}

addedOutput schema / properties / count

Added value: +{
+  "description": "Number of activities returned.",
+  "title": "Count",
+  "type": "integer"
+}

addedOutput schema / properties / end_date

Added value: +{
+  "title": "End Date",
+  "type": "string"
+}

addedOutput schema / properties / limit

Added value: +{
+  "title": "Limit",
+  "type": "integer"
+}

addedOutput schema / properties / matched

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Activities in the range that passed every filter.",
+  "title": "Matched"
+}

addedOutput schema / properties / min_duration_minutes

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Min Duration Minutes"
+}

addedOutput schema / properties / next_offset

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "offset for the next page, present only when more activities matched.",
+  "title": "Next Offset"
+}

addedOutput schema / properties / offset

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Offset"
+}

addedOutput schema / properties / order

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Order"
+}

removedOutput schema / properties / result

Removed value: -{
-  "items": {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  "title": "Result",
-  "type": "array"
-}

addedOutput schema / properties / size_capped

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "True when the page stopped before limit to keep the response small.",
+  "title": "Size Capped"
+}

addedOutput schema / properties / start_date

Added value: +{
+  "title": "Start Date",
+  "type": "string"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when more activities matched than this response holds; pass next_offset as offset to get the rest.",
+  "title": "Truncated",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "result"
-]New value: +[
+  "start_date",
+  "end_date",
+  "limit",
+  "count",
+  "truncated"
+]

changedOutput schema / title

Previous value: -"get_activitiesOutput"New value: +"ActivityList"

First observedv0.1.0Aug 31, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only cover read-only/non-destructive/open-world; the description adds auth requirement (saved local Garmin authentication), cache mutation ('may update the local cache; never changes your Garmin account'), no automatic retry on failure, and semantic details like size_capped pages and metrics omitted rather than zeroed. That is substantive context beyond structured data.

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

Conciseness4/5

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

Front-loaded with purpose, scope and sibling routing before the return-shape and auth details, and almost every sentence carries information. It is dense and long for a list tool, with return-format detail repeated against an existing output schema, which costs it a point.

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

Completeness5/5

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

For an 8-parameter, optional-all-defaults query tool it covers auth prerequisites, date-window defaults, filtering/paging strategy, response envelope fields (matched, truncated, next_offset), and failure behavior. Nothing an agent needs to call it correctly is missing.

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; the description adds operational meaning by describing the default-window behavior (both dates omitted → last 14 days; only end_date → 30 days ending on that date) and by advising which filters to combine for long ranges. Most per-parameter syntax still lives in the schema, keeping it short of a 5.

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

Purpose5/5

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

States a specific verb+resource ('List activity summaries'), its scope (inclusive calendar date range of at most 366 days) and default ordering (newest first). It also names the three sibling tools it is not, so the agent can route without opening any schema.

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

Usage Guidelines5/5

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

Explicitly routes: 'Use for calendar ranges such as a month; use get_recent_activities for a rolling window with a type filter, get_activity for one activity's laps, zones, and notes, or get_training_week for Monday-Sunday totals.' It also gives when-to-use guidance for long ranges (activity_types, min_duration_minutes, compact=true, offset paging).

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