Skip to main content
Glama
Sign In
garmin-mcp

garmin-mcp

by Sinfjell
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

get_activity_hr_zones

Retrieve time spent in each heart-rate zone (1-5) for a single Garmin activity, including zone limits, totals, and heart-rate data availability, to assess workout intensity.

Instructions

Get the time spent in each heart-rate zone (1-5) for one activity.

activity_id is the numeric id from list_recent_activities or list_activities_by_date. Returns a JSON object with "zones": one entry per zone with secs and minutes spent in it, plus the zone's floor_bpm and ceiling_bpm as configured when the activity was recorded (zone 5 has no ceiling). "total_secs" / "total_minutes" sum the zones.

"has_hr_data" is false when the activity was recorded without heart rate (Garmin returns no zones, or every zone at zero): treat the minutes as unknown then, never as zero. This is the per-activity breakdown behind get_activity_details' hasHrTimeInZones flag; for the zone limits themselves, without an activity, use get_running_threshold.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "activity_id": "<activity_id>"
    },
    "name": "get_activity_hr_zones"
  }
}

Input Schema

NameRequiredDescriptionDefault
activity_idYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full behavioral burden and does so: it discloses the return shape, the meaning of `has_hr_data=false`, and a critical data-interpretation warning ('treat the minutes as unknown then, never as zero'). That caveat is exactly the kind of non-obvious behavior an agent would otherwise get wrong.

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?

The core action and parameter source are front-loaded, and the subsequent sentences cover returns, edge cases, and siblings in a logical order. It runs a bit long across several paragraphs, but nearly every sentence adds distinct information.

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?

Even though an output schema exists, the description goes further by interpreting the zero-zone/no-HR case and clarifying the fallback source for zone limits. For a single-parameter read tool, an agent has everything needed to call and interpret it.

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 0% for the single parameter, but the description compensates by naming both source tools that produce `activity_id`. It doesn't note that the schema types the id as a string despite calling it 'numeric', a small residual ambiguity.

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 first sentence gives a specific verb and resource ('Get the time spent in each heart-rate zone (1-5) for one activity') and scopes it to a single activity, which cleanly separates it from the aggregate siblings like get_heart_rate and get_daily_stats.

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

Usage Guidelines4/5

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

It explicitly routes the agent elsewhere in two cases: get_activity_details for the `hasHrTimeInZones` flag context and get_running_threshold for zone limits without an activity. It doesn't state a when-not-to-use case, but the alternative routing is clear enough to be above baseline.

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

Deploy Server

Other Tools