Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Sports Tracker MCP Server What's my current recovery and training load?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Unofficial Project: This project is an independent, open-source Model Context Protocol (MCP) server. It is not affiliated with, endorsed by, sponsored by, or associated with Sports Tracking Technologies Ltd, Amer Sports, Suunto, or any of their affiliates or subsidiaries. All registered trademarks, product names, and company logos are the property of their respective owners.
An unofficial Model Context Protocol (MCP) server for Sports Tracker, enabling AI assistants (such as Claude Desktop, Cursor, and Antigravity) to query workouts, activity history, training load, VO2Max progression, recovery metrics, and social feeds.
8 FastMCP Tools: Complete fitness tracking integration covering workouts, social feed, user statistics, training load, VO2Max trends, and activity breakdowns.
Structured Pydantic Models: Clean schemas with human-readable paces, formatted durations, and units.
Dual Unit Support: Effortlessly toggle between metric (km, km/h, min/km) and imperial (miles, mph, min/mi) across queries.
LRU Bounded TTL Caching: In-memory caching via cachetools.TTLCache (max 256 items, 60-second TTL) preventing redundant API requests and memory leaks.
Resilient Pagination: Multi-day summary tools dynamically paginate backwards through workout history without premature truncation.
Related MCP server: GC-MCP
Tool | Description | Parameters |
| Fetch recent workouts with formatted distance, duration, pace, and heart rate. |
|
| Retrieve feed items from followed athletes or community members. |
|
| In-depth metrics for a workout: ascent/descent, HR zones, gear, cadence, energy, and Suunto extensions. |
|
| Lifetime aggregate statistics and per-sport totals (distance, duration, calories, count). |
|
| Historical aerobic capacity (VO2Max) and fitness age progression extracted from workouts. |
|
| Aggregated volume, distance, time, and calories across all sports for the past N days. |
|
| Current recovery hours, training stress score (TSS), peak training effect (PTE), EPOC, and recovery status. | None |
| Breakdown of sport frequency, total duration, and last performed dates over the past N days. |
|
Once integrated, your AI assistant can answer natural language queries directly:
Weekly Training Volume: "How much running and cycling have I logged over the past 14 days? Break it down by distance, time, and pace."
Workout Deep Dive: "Give me a detailed breakdown of my latest workout, including heart rate zones, cadence, elevation gain, and Suunto metrics in imperial units."
Recovery & Readiness: "What is my current recovery time, TSS, and EPOC from my recent activities? Am I ready for a tempo run today?"
Fitness Trends: "Plot my aerobic capacity (VO2Max) and fitness age progression over my last 20 workouts."
Interactive Dashboards: "Analyze my training load and render an interactive React dashboard with weekly volume charts and HR zone distribution."
The server requires your Sports Tracker session key to authenticate requests.
Variable | Required | Default | Description |
| Yes | — | Your session token ( |
| No |
| Sports Tracker API base endpoint. |
Log in to Sports Tracker Web in your web browser.
Open your browser's Developer Tools (F12 or Cmd+Option+I) and switch to the Network tab.
Refresh the page or click on any workout.
Inspect any request to api.sports-tracker.com and copy the value of the STTAuthorization header (or find sessionkey in your browser cookies/local storage).
Create a .env file in the project root:
cp .env.example .envAnd populate:
STT_SESSION_KEY=your_session_key_herePython 3.14+
uv (recommended) or pip
Clone the repository and install dependencies:
git clone https://github.com/wilkar/sports-tracker-mcp.git
cd sports-tracker-mcp
uv syncYou can start the server directly using stdio transport:
# Using uv:
uv run sport-tracker
# Or directly with Python:
python main.pyInspect all tools interactively in your browser using FastMCP's inspector:
uv run fastmcp dev inspector src/sport_tracker_mcp/server.pyOr inspect tool schemas directly from the CLI:
uv run fastmcp list src/sport_tracker_mcp/server.pyAdd the server to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"sports-tracker": {
"command": "/path/to/sports-tracker-mcp/.venv/bin/sport-tracker",
"env": {
}
}
}
}In your workspace or global MCP settings (mcp_config.json):
{
"mcpServers": {
"sports-tracker": {
"command": "/path/to/sports-tracker-mcp/.venv/bin/sport-tracker",
"env": {
}
}
}
}sports-tracker-mcp/
├── src/
│ └── sport_tracker_mcp/
│ ├── client/ # Async HTTP client with LRU TTLCache & error handling
│ ├── formatting/ # Unit conversions (metric/imperial), pace, and duration utils
│ ├── models/ # Pydantic schemas for workouts, stats, load & recovery
│ ├── tools/ # 8 FastMCP tool implementations
│ ├── config.py # Environment variable resolution & .env loader
│ └── server.py # FastMCP server definition & CLI entrypoint
├── tests/ # Test suite (65 tests across client, models, tools, and formatting)
├── .env.example # Sample environment file
├── pyproject.toml # Project metadata, dependencies, and tool configs
├── TODO.md # Roadmap and endpoint specs for upcoming tools
└── README.mdThe following tools are planned for future releases to expand Sports Tracker capabilities:
get_routes: List saved and recorded GPS routes with distances, speeds, and activity types.
get_route_details: In-depth GPS track waypoints, elevation profiles, and polyline coordinates for a specific route.
export_workout_gpx: Download standardized GPX XML track files for activities.
get_user_following: Retrieve followers and followed athlete profiles from Sports Tracker.
See TODO.md for full endpoint specifications.
Run the test suite:
uv run pytestCheck types and formatting:
uv run mypy .
uv run isort --check .
uv run black --check .This project is licensed under the MIT License.
Get a breakdown of activity frequency, total time spent, and last performed dates over the past N days.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| now_ts | No |
| Name | Required | Description |
|---|---|---|
| days | Yes | Number of past days analyzed |
| activities | Yes | Breakdown per activity |
| total_sessions | Yes | Total activity sessions recorded |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the output dimensions but does not explain whether this is read-only, how 'past N days' is bounded, what activity types are included, or how now_ts affects the results.
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 a single, clear, front-loaded sentence with no filler. It delivers the core purpose efficiently, though it is brief enough that some semantic gaps exist in other dimensions.
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?
An output schema exists, so return structure is covered, but the description leaves key invocation context unclear: the role of now_ts, the exact meaning of 'past N days', and how this summary differs from sibling tools. For a tool with two unannotated parameters, this is insufficient.
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 compensate for both parameters. It only maps 'past N days' to the days parameter; now_ts is entirely unexplained. The description does not fully cover even the days parameter's semantics (e.g., inclusive/exclusive, calendar vs. rolling window).
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 uses a specific verb ('Get a breakdown') and names the exact outputs: activity frequency, total time spent, and last performed dates over the past N days. It is clearly about summarizing recent activities, though it does not explicitly differentiate from the sibling get_recent_workouts or get_training_summary.
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?
There is no guidance about when to use this tool versus siblings such as get_recent_workouts or get_training_summary. No context, prerequisites, or exclusion criteria are provided, so an agent must infer suitability from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent workouts with formatted distance, duration, pace, and HR.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| imperial | No |
| 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 of behavioral disclosure. It mentions 'formatted' output but doesn't disclose what formatting means (e.g., units, rounding), whether the data is read-only, or any rate limits or pagination behavior. For a read tool with no annotations, this is a notable gap.
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 a single concise sentence that front-loads the core purpose and lists the key output fields. It earns its place with no filler, though it could add a bit more detail without becoming bloated.
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 tool has an output schema, so return values are covered elsewhere. However, with no annotations and 0% schema description coverage, the description should clarify the meaning of 'formatted' and the two parameters. It's adequate for a simple read tool but leaves some ambiguity about units and defaults.
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 compensate. It mentions 'formatted' distance and pace, which hints at the 'imperial' parameter, and 'recent' hints at 'limit', but it doesn't explicitly explain either parameter's meaning or defaults. The description adds some context but not enough to fully compensate for the 0% schema coverage.
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 states a specific verb ('get') and resource ('recent workouts') and lists the formatted fields (distance, duration, pace, HR), which distinguishes it from siblings like get_workout_details or get_recent_activities_summary. It doesn't explicitly name a sibling, but the resource and field list make the purpose 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?
The description implies usage for retrieving recent workout data with formatting options, but it doesn't explicitly state when to use this tool versus alternatives like get_recent_activities_summary or get_workout_details. No exclusions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get social feed items from followed athletes or community.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| imperial | No |
| 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 full responsibility for behavioral disclosure. It conveys a read-only 'Get' action and the source of items, but it does not state ordering, pagination behavior, whether follower and community content are mixed, or any access requirements.
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 a single front-loaded sentence that immediately states the action, object, and scope. There is no filler or redundant phrasing.
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?
Although an output schema exists, the description still omits important invocation context: the meaning of the 'imperial' flag, whether 'limit' caps the number of returned items, and how follower/community items are combined. For a tool with no annotations and no schema parameter descriptions, this is incomplete.
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%, and the description does not explain either parameter. 'limit' is somewhat self-explanatory and has a default, but 'imperial' is opaque without additional context; the agent is left to guess whether it controls units, filtering, or something else.
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 uses a specific verb ('Get') with a concrete resource ('social feed items') and source scope ('followed athletes or community'). None of the sibling tools target a social feed, so an agent can clearly distinguish this from the training, workout, and stats 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?
The description implies the tool should be used when social feed content is requested, and the sibling list shows no clearly overlapping alternative. However, it never explicitly states when to favor this tool over siblings or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current training load, recovery hours, TSS, PTE, EPOC, and recovery status from the latest workout.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| peak_epoc | No | Peak EPOC in ml/kg |
| impact_tag | No | Suunto training impact tag, e.g. IMPACT_STRENGTH |
| latest_sport | Yes | Sport of latest workout |
| recovery_status | Yes | Human-friendly status, e.g. 'Fully Recovered' or 'Fatigued' |
| latest_workout_key | Yes | Latest workout identifier |
| latest_workout_date | Yes | Date/time of latest workout |
| peak_training_effect | No | Peak Training Effect (PTE 1.0 - 5.0) |
| training_stress_score | No | TSS of latest workout |
| cumulative_recovery_hours | Yes | Remaining body recovery needed in hours |
| latest_workout_recovery_hours | Yes | Recovery time generated by latest workout in hours |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It indicates a read-only operation ('Get') and specifies the data source ('latest workout'), but does not detail behavior such as what happens if no workout exists, data freshness, or computation method. It also does not state whether this is a safe read operation, though 'Get' implies read-only.
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?
A single sentence that is concise and front-loads the core purpose ('Get current training load, recovery hours...'). It does not waste words and is 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?
Given the tool has zero parameters and an output schema (though not shown), the description could be sufficient. However, for a data retrieval tool with no annotations and no explicit behavior on edge cases (e.g., no workout found), it lacks critical context. The output schema may cover return values, but the description does not mention it or guide on interpretation. It is adequate but not thorough.
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?
The input schema is empty with 100% schema description coverage (trivially), so the description adds no parameter details. Since there are no parameters, baseline is 4, but the description clarifies the scope ('latest workout'), which provides some contextual meaning beyond the schema. However, it does not elaborate on any implicit defaults (e.g., timezone, units).
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 retrieves training load and recovery metrics (TSS, PTE, EPOC, recovery status) from the latest workout. This distinguishes it from siblings like get_training_summary or get_recent_workouts, though it does not explicitly name alternatives.
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 implies it is used for the latest workout's load and recovery data, but does not explicitly state when to use it versus get_training_summary or get_recent_workouts. It gives some context ('latest workout') but lacks clear exclusions or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregated training volume, distance, time, and calories across sports for the past N days.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| now_ts | No | ||
| imperial | No |
| Name | Required | Description |
|---|---|---|
| days | Yes | Number of days aggregated |
| sports | Yes | Breakdown per sport |
| workouts_count | Yes | Total number of workouts in period |
| total_distance_km | Yes | Total distance in km |
| total_calories_kcal | Yes | Total calories burned in period |
| total_distance_formatted | Yes | Total distance formatted |
| total_duration_formatted | Yes | Total duration formatted as HH:MM:SS |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full weight. It conveys a read-only aggregation behavior and a time window, which is helpful. However, it doesn't disclose the role of now_ts as the reference timestamp or non-imperial vs imperial units, leaving some behavioral expectations implicit.
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?
A single, front-loaded sentence lists the key metrics (volume, distance, time, calories) and the time dimension with zero unnecessary words. The description spends its space efficiently.
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, return fields need not be spelled out, and the tool is relatively simple. Still, the missing meaning of now_ts and imperial, plus no sibling differentiation, means an agent may struggle to use all parameters 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?
Schema coverage is 0%, so the description must compensate for unrecorded parameters. It only clarifies 'days' via 'past N days' but leaves 'now_ts' and 'imperial' completely unexplained, despite their presence in 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 uses a specific verb 'Get' and a clear resource: aggregated training volume, distance, time, and calories across sports. It is sufficiently distinct from siblings like get_recent_workouts and get_workout_details because it emphasizes aggregation, though it doesn't name an alternative explicitly.
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?
No guidance is given on when to prefer this tool over similar siblings such as get_recent_activities_summary or get_training_load_and_recovery. The only context is 'for the past N days,' which implies a use case but never states exclusions or comparisons to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get lifetime totals and per-sport breakdown stats for the logged-in user or specified username.
| Name | Required | Description | Default |
|---|---|---|---|
| imperial | No | ||
| username | No |
| Name | Required | Description |
|---|---|---|
| sports | Yes | Breakdown per sport |
| total_days | Yes | Total registered active days |
| total_workouts | Yes | Lifetime total number of workouts |
| total_distance_km | Yes | Lifetime total distance in km |
| total_calories_kcal | Yes | Lifetime total calories in kcal |
| total_duration_hours | Yes | Lifetime total time in hours |
| total_distance_formatted | Yes | Lifetime total distance formatted |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It makes clear this is a read-only retrieval operation and explains the target-user behavior. However, it does not mention authentication requirements, data freshness, or how the imperial parameter alters results, leaving some behavioral context implicit.
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 a single, front-loaded sentence with no wasted words. It states the action, the returned data scope, and the target selection in a compact and scannable way.
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?
For a simple two-parameter read tool with an output schema, the description is mostly sufficient. It covers the primary purpose and username behavior, but omits the meaning of 'imperial' and any guidance about authentication or unit conventions, leaving a noticeable gap.
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 compensate. It partially explains 'username' by stating stats are for the logged-in user or a specified username, but it does not explain the 'imperial' boolean or its effect on the output. This leaves one parameter semantically underspecified.
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 uses a specific verb ('Get'), names the resource ('lifetime totals and per-sport breakdown stats'), and clarifies scope ('logged-in user or specified username'). This clearly distinguishes it from sibling tools that focus on recent workouts, training summaries, or VO2 max history.
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 conveys a clear context for use—retrieving aggregate lifetime stats—and implies that it is the appropriate tool for that purpose. It does not explicitly name alternatives or exclusions, but the precise scope effectively separates it from the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get VO2Max and fitness age history extracted from recent workouts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| records | Yes | Chronological VO2Max records |
| latest_vo2_max | No | Most recent VO2Max |
| average_vo2_max | No | Average VO2Max over recorded period |
| latest_fitness_age | No | Most recent estimated fitness age |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does add useful context by stating the history is 'extracted from recent workouts,' implying derived/aggregated data. However, it does not mention ordering, time range, limit behavior, or that this is a safe read-only operation.
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 a single, focused sentence with no wasted words. It front-loads the core action and resource, making it easy to parse quickly.
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 tool is simple and has an output schema, but the description lacks usage guidance and parameter semantics. An agent would not know when to choose this over sibling tools or what 'limit' controls, leaving important gaps for correct invocation.
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%, and the description does not explain the 'limit' parameter at all. The parameter name and default of 20 are somewhat self-explanatory, but the tool definition provides no explicit semantics for how the limit is applied.
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 identifies the resource (VO2Max and fitness age history) and the action (get), and notes the data source (recent workouts). It is specific enough to distinguish from siblings like get_recent_workouts, though it does not explicitly name alternatives or boundary conditions.
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?
No guidance is provided on when to use this tool versus alternatives such as get_training_summary or get_recent_workouts. The intended use is only implied by the name and description, with no exclusions or conditional routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed workout metrics including ascent, descent, HR zones, gear, and Suunto extensions.
| Name | Required | Description | Default |
|---|---|---|---|
| imperial | No | ||
| workout_key | Yes |
| Name | Required | Description |
|---|---|---|
| gear | No | Device or gear used (e.g. Suunto watch) |
| sport | Yes | Sport name, e.g. running, cycling, walking |
| avg_hr | No | Average heart rate in bpm |
| max_hr | No | Maximum heart rate in bpm |
| peak_epoc | No | Peak EPOC in ml/kg |
| start_time | Yes | ISO 8601 formatted start time |
| step_count | No | Total steps, if applicable |
| description | No | Workout description or notes |
| distance_km | Yes | Distance in kilometers |
| workout_key | Yes | Unique workout identifier |
| ascent_meters | No | Total ascent in meters |
| calories_kcal | No | Calories burned in kcal |
| descent_meters | No | Total descent in meters |
| duration_seconds | Yes | Active duration in seconds |
| heart_rate_zones | No | Formatted time spent in each HR zone |
| avg_pace_formatted | Yes | Pace in MM:SS min/km format |
| distance_formatted | Yes | Distance with unit, e.g. '5.20 km' |
| duration_formatted | Yes | Duration in HH:MM:SS format |
| avg_speed_formatted | Yes | Speed with unit, e.g. '10.5 km/h' |
| max_speed_formatted | Yes | Max speed formatted with unit |
| recovery_time_hours | No | Workout recovery time in hours |
| peak_training_effect | No | Peak training effect (PTE 1.0 - 5.0) |
| training_stress_score | No | Training stress score (TSS) |
| cumulative_recovery_hours | No | Total cumulative recovery time in hours |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention whether this is a read-only operation, whether it requires authentication, what the output format is, or any side effects. The description only lists metric categories, which is useful but insufficient for a tool with zero annotation coverage.
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 a single sentence that is concise and front-loads the main purpose. It lists specific metric categories efficiently. However, it could have used the available space to add usage guidance or parameter context.
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 tool has an output schema, which helps, but the description lacks essential context: no usage guidance, no parameter semantics, no behavioral notes. For a tool with 2 parameters and no annotations, the description is minimally adequate but leaves an agent guessing about when to use it and what the parameters mean.
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 compensate for the undocumented parameters. It does not explain what 'workout_key' is, how to obtain it, or what the 'imperial' flag does beyond its default value. The metric list implies some behavior but does not map to the parameters.
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 states a specific verb ('Get') and resource ('detailed workout metrics') and lists concrete metric categories (ascent, descent, HR zones, gear, Suunto extensions). It is clear what the tool does, though it does not explicitly differentiate it from sibling tools like get_recent_workouts or get_training_summary.
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?
No guidance is provided on when to use this tool versus alternatives. The sibling list includes several workout-related tools (get_recent_workouts, get_training_summary, get_recent_activities_summary), but the description does not state what makes this tool the right choice for detailed metrics.
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.1.0get_recent_activities_summaryget_recent_workoutsget_social_feedget_training_load_and_recoveryget_training_summaryget_user_statsget_vo2_max_historyget_workout_detailsScored across 8 tools
Most tools have clearly distinct purposes: social feed, workout lists, detailed workout metrics, user stats, VO2Max history, and recovery are easy to tell apart. The only mild ambiguity is between get_training_summary and get_recent_activities_summary, since both aggregate data over the past N days, though their metric focus differs.
All tools follow a consistent get_<noun_phrase> snake_case pattern, making the set predictable and easy to navigate. There are no mixed conventions or vague verbs.
Eight tools is well-scoped for a read-only sports tracking analytics server. Each tool represents a meaningful query surface without unnecessary redundancy or overwhelming breadth.
The read-only query surface is quite complete for analytics: recent workouts, detailed workout metrics, summaries, user stats, VO2Max history, recovery, and social feed are all covered. The main gap is the total absence of write operations like logging a workout or updating user data, though that may be acceptable if the server is intended only as a data retrieval layer.
Connect your wearables, rings and training apps, then ask your AI about your own health data.
Connect your health, fitness, nutrition, sleep, and wearable data to your AI assistant.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
AI running coach. Reads Strava, Suunto, Polar, Apple Health or Health Connect. Adapts to your feel.
