Skip to main content
Glama
garmin-connect-mcp

garmin-connect-mcp

by Samiu1

Search Activities

garmin_search_activities
Read-onlyIdempotent

Find your recorded Garmin workouts by activity type, date range, distance, duration, elevation, or power, plus text search. Returns compact summaries with activity IDs for follow-up detail and file downloads.

Instructions

Search and filter the user's recorded Garmin activities (workouts), newest first by default.

Returns one page of compact activity summaries, each with an activity ID. Pass that ID to garmin_get_activity for full detail, or to garmin_download_activity_file for the original FIT/GPX file.

Examples:

  • "My runs last month" -> activity_type="running", start_date="2026-10-01", end_date="2026-10-31"

  • "Longest rides over 50km" -> activity_type="cycling", min_distance=50000, sort_by="distance", sort_order="desc"

  • "Find my race efforts" -> event_type="race"

Pagination: when has_more is true, call again with offset=next_offset. This covers the common filters; garmin_get_raw reaches the dive-depth, bounding-box, and field-requirement filters.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "garmin_search_activities"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum activities to return. Keep low; each activity is large.
offsetNoNumber of activities to skip, for pagination
searchNoText to match in activity names and descriptions
sort_byNoField to sort by, e.g. 'distance', 'duration', 'startLocal'. Defaults to start time.
end_dateNoLatest activity start date, inclusive, YYYY-MM-DD (local time)
favoriteNoRestrict to favorites (true) or non-favorites (false). Omit for no filter.
event_typeNoEvent classification: 'race', 'training', 'recreation', 'fitness', 'specialEvent', or 'uncategorized'
sort_orderNoSort directiondesc
start_dateNoEarliest activity start date, inclusive, YYYY-MM-DD (local time)
max_distanceNoMaximum distance in meters, inclusive
max_durationNoMaximum timer duration in seconds, inclusive
min_distanceNoMinimum distance in meters, inclusive
min_durationNoMinimum timer duration in seconds, inclusive
activity_typeNoParent activity type key, e.g. 'running', 'cycling', 'swimming'. Must be a parent type, not a subtype.
max_elevationNoMaximum total elevation gain in meters, inclusive
min_avg_powerNoMinimum average power in watts, inclusive
min_elevationNoMinimum total elevation gain in meters, inclusive
response_formatNo'markdown' for readable text, 'json' for the exact Garmin field names and valuesmarkdown
exclude_childrenNoExclude child activities such as individual legs of a multisport activity
activity_sub_typeNoActivity subtype key, e.g. 'trail_running'. Must belong to activity_type when both are given.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.1

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the read-only, idempotent, and open-world annotations, it discloses default ordering, one-page compact-summary results rather than full detail, and ID-based follow-up workflows. It also explains pagination through has_more/next_offset and scopes the tool to common filters, making both result behavior and coverage limits clear.

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

Conciseness5/5

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

The description front-loads purpose and result shape, then uses compact examples and short pagination and coverage notes. Its length is justified by a 20-parameter search tool and its sibling routing, with no repetitive parameter dump or unnecessary wording.

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 a complex, optional-parameter search tool with no output schema, it supplies the invocation-critical context: compact summaries, activity IDs, default order, pagination signals, and advanced-filter limits. Together with the fully documented schema and safety annotations, this is sufficient to select and invoke the tool correctly.

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 schema already supplies the baseline parameter documentation. The description adds practical composition guidance by mapping intents to combinations of activity type, dates, distance, sorting, and event type, and by explaining that offset should be populated from next_offset. Most individual values and units still come from the schema, so the added semantics are strong but not exhaustive.

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?

The opening line gives a specific verb and resource—searching and filtering the user's recorded Garmin activities (workouts)—and states the default newest-first ordering. It also distinguishes this summary search from garmin_get_activity, garmin_download_activity_file, and garmin_get_raw by their respective roles.

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?

It provides explicit next-step guidance for activity IDs, three natural-language-to-parameter examples, and an exact pagination rule using has_more and next_offset. The final sentence directs the agent to garmin_get_raw when dive-depth, bounding-box, or field-requirement filters are needed.

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