The Hevy MCP Server gives AI assistants access to your Hevy workout data, enabling full read/write management of your fitness tracking.
Workouts: List (paginated), count, get details by ID, create new workouts (exercises, sets, reps, weight, duration), update existing workouts, and get workout events (updates/deletes since a given date) for syncing.
Routines: List, get details, create, and update routines (including rep ranges, rest times, supersets). Organize routines into folders — list, get, create, and rename them.
Exercise Library: Browse the full exercise library with muscle group and equipment info, get details on a specific exercise, and track progress for any exercise via its full training history.
Body Measurements: List measurements (weight, body fat %, etc.) over time, retrieve measurements for a specific date, and log or update measurements.
User Info: Retrieve your Hevy profile (username, join date, etc.).
Provides tools for accessing and managing Hevy workout data, including listing, creating, and updating workouts, managing routines and folders, retrieving exercise templates and history, and logging body measurements.
Click on "Install 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., "@Hevy MCP Server list my workouts from last week"
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.
An MCP server that gives AI assistants (Claude, etc.) access to your Hevy workout data via the Model Context Protocol.
Supports both Streamable HTTP (for Claude web/mobile/desktop connector UI with OAuth) and SSE (for Claude Desktop config / CLI).
Fork this repo and connect it to a new Railway project
In the Railway dashboard, go to your service → Variables and add:
Variable | Value |
| Your Hevy API key (from hevy.com/settings?developer) |
| A secret token — run |
|
|
| Your Railway public URL (set after generating a domain below) |
Go to Settings → Networking → Generate Domain, enter port 3847, click Generate Domain
Copy the generated URL and update SERVER_BASE_URL to match — Railway will redeploy automatically
Check Deploy Logs for Hevy MCP server running
Token persistence on Railway: OAuth tokens are stored in
DATA_DIR(defaults to/data). On Railway's free tier the filesystem is ephemeral — tokens won't survive redeploys and users will need to re-authorize. To persist tokens, add a Railway volume mounted at/dataand setDATA_DIR=/data.
git clone https://github.com/karlhsueh/hevyapp-mcp.git
cd hevyapp-mcp
cp .env.example .env
# Edit .env with your values
docker compose up -dVerify:
curl http://localhost:3847/health
# {"status":"ok","server":"hevyapp-mcp"}Expose remotely with Cloudflare Tunnel or any reverse proxy pointing at localhost:3847.
The included docker-compose.yml mounts a named volume at /data for OAuth token persistence across container restarts.
Install the Fly CLI and run fly auth login
From the repo root: fly launch (accept defaults)
Set secrets:
fly secrets set \
HEVY_API_KEY=your-key \
MCP_AUTH_TOKEN=your-token \
MCP_TRANSPORT=sse \
SERVER_BASE_URL=https://your-app.fly.dev \
DATA_DIR=/dataAdd a volume for token persistence:
fly volumes create mcp_data --size 1Mount the volume by adding to fly.toml:
[mounts]
source = "mcp_data"
destination = "/data"Deploy: fly deploy
Related MCP server: hevy-mcp-server
The server implements OAuth 2.0 so Claude can authenticate without any config files.
In Claude, open Settings → Integrations (web/mobile) or Preferences → Integrations (desktop)
Click Add custom integration
Enter your server URL (e.g. https://your-app.up.railway.app)
Claude opens a browser window — enter your MCP_AUTH_TOKEN
Done
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"hevy": {
"type": "sse",
"url": "https://your-server/sse",
"headers": {
"Authorization": "Bearer your-secret-token"
}
}
}
}claude mcp add hevy --transport sse https://your-server/sse \
--header "Authorization: Bearer your-secret-token"Tool | What it does |
| List workouts (paginated) |
| Total workout count |
| Single workout details |
| Changes since a date (for sync) |
| Log a new workout |
| Edit an existing workout |
| Your profile |
| List saved routines |
| Single routine |
| Manage routines |
| Full exercise library |
| Single exercise info |
| Progress over time for any exercise |
| Routine folder list |
| Manage folders |
| Weight/body fat history |
| Measurements for a date |
| Log body measurements |
git pull
docker compose up -d --builddocker compose logs -f hevyapp-mcpCreate a new workout routine
| Name | Required | Description | Default |
|---|---|---|---|
| routine | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to disclose behavioral traits such as idempotency, side effects (e.g., overwriting existing routines), authentication requirements, or output behavior. 'Create' implies a write operation but lacks critical details.
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 short sentence, which is concise but at the expense of essential information. It could be more informative while remaining succinct.
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's complexity (deeply nested parameter, no output schema), the description is grossly insufficient. It omits prerequisites (e.g., need for existing exercise templates), behavior on duplicates, and response details. The agent is left with no guidance beyond the raw schema.
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 complex nested parameter 'routine'. The agent must deduce the required structure (title, exercises) solely from the JSON schema, which lacks field descriptions.
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?
Description clearly states verb 'Create' and resource 'workout routine', matching the tool name. However, it does not further distinguish from sibling tools like 'create_routine_folder' or 'create_workout', but the name itself is sufficiently unique.
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 on when to use this tool versus alternatives, no preconditions or exclusions. The description merely states the action without context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new routine folder to organize routines
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as permission requirements, idempotency, or side effects beyond creation. This is insufficient for a mutation tool.
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 very concise (one sentence) but lacks structure and additional context. It could be improved by mentioning return value or any constraints, though it is not overly verbose.
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 tool with one parameter and no output schema, the description provides a minimal but acceptable level of completeness. However, it does not clarify if the folder is created within a hierarchy or any default behavior.
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 'title' parameter's meaning, constraints, or uniqueness. It falls short of compensating for the lack of schema descriptions.
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 the tool creates a routine folder to organize routines. The verb 'Create' and resource 'routine folder' are specific, and it distinguishes from sibling tools like 'create_routine' and 'get_routine_folder'.
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 provides no guidance on when to use this tool versus alternatives, no prerequisites or exclusions. It only states the purpose without contextual usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log a new workout in Hevy
| Name | Required | Description | Default |
|---|---|---|---|
| workout | Yes | Workout object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description offers no behavioral details such as idempotency, duplicate handling, permission requirements, or return values. For a creation tool, this lack of transparency is critical.
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 very short (6 words), which is concise but sacrifices completeness. It could include more context without becoming verbose.
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 complex nested input schema, lack of output schema, and many sibling tools, the description fails to provide sufficient context for correct usage. It does not explain the required structure of the workout object or expected outcomes.
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 100% for the top-level parameter, and the description adds no additional meaning beyond the schema. Nested parameter descriptions are absent, but the schema itself provides structural hints.
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 the action ('Log a new workout') and the resource ('in Hevy'), but does not differentiate it from sibling tools like create_routine or update_workout, relying on the tool name for disambiguation.
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 on when to use this tool versus alternatives (e.g., create_routine, update_workout). No prerequisites or exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get body measurements for a specific date
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date in YYYY-MM-DD format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It only states a read operation but fails to disclose behavior for missing data, permissions, or return format. Minimal transparency.
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?
Single sentence, front-loaded with the action. No wasted words, but could include some context without losing conciseness.
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 single-parameter tool, the description is minimally adequate. However, ambiguity remains about whether multiple measurements can be returned for a date, and no output schema clarifies.
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 100% with a clear description for the date parameter. The tool description adds no new meaning beyond what the schema already provides, so baseline 3 is appropriate.
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 the verb (Get), resource (body measurements), and scope (for a specific date). It is distinct from sibling 'get_body_measurements' which likely returns all or a range, but the description does not explicitly differentiate.
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 on when to use this tool versus alternatives like 'get_body_measurements' or 'upsert_body_measurement'. The agent must infer usage from the parameter, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a paginated list of body measurements (weight, body fat %, etc.) over time
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. Mentions pagination and content, but lacks details on ordering (chronological?), data freshness, empty results, authentication, or performance implications. Under-discloses for a tool with no annotations.
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?
One sentence, 14 words. Front-loaded with key info (get, paginated list, types). No fluff, efficiently conveys purpose.
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?
Missing details on sorting, date range behavior (despite 'over time'), pagination defaults, and output format. For a tool with two parameters and no output schema, the description is too terse to fully prepare the agent.
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% with no parameter descriptions. The description adds zero information about parameters page and pageSize (defaults, ranges, behavior). Despite describing the tool as paginated, it fails to explain how parameters control pagination.
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?
Description clearly states verb 'Get', resource 'body measurements', and key attributes: paginated, over time, includes types like weight and body fat. Distinguishes from siblings like get_body_measurement_by_date (single date) and upsert_body_measurement (modify).
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 explicit guidance on when to use this tool vs alternatives (e.g., get_body_measurement_by_date for a single date, upsert_body_measurement for writing). The description implies list retrieval but does not set usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the training history for a specific exercise (all sets across all workouts), great for tracking progress
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| pageSize | No | ||
| exerciseTemplateId | Yes | Exercise template ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses it returns all sets across all workouts, but lacks details on pagination, auth, or side effects. No annotations provided.
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?
Single sentence, concise and clear, though could be slightly more structured.
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?
Minimal description despite having pagination parameters and no output schema. Lacks return value details.
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 low (33%), and description adds no parameter details beyond what is in 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?
Explicitly states it retrieves training history for a specific exercise, distinguishing it from sibling tools like get_exercise_template or get_workouts.
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?
Implied use for tracking progress, but no explicit when-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific exercise template by ID
| Name | Required | Description | Default |
|---|---|---|---|
| exerciseTemplateId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states basic behavior. It doesn't disclose what happens if the ID is invalid, authentication requirements, or any side effects.
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 sentence with no wasted words. It is appropriately concise for the simple operation.
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 get-by-ID tool with one parameter and no output schema, the description is minimally adequate. However, it lacks details on return format and error handling, which could be added.
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 parameter 'exerciseTemplateId' beyond mentioning 'by ID'. No details on format, source, or constraints are given.
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 the action (Get) and resource (specific exercise template by ID). It differentiates from the sibling 'get_exercise_templates' by specifying 'by ID', implying singular retrieval.
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 on when to use this tool versus alternatives like 'get_exercise_templates' or other get tools. Usage is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the exercise library — all available exercises with their IDs, muscle groups, and equipment
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions return content but does not disclose pagination behavior or any side effects. It is adequate but lacks depth.
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?
Single sentence, no filler, front-loaded with key action and output.
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 no output schema and no annotations, the description is too minimal. It omits pagination details, ordering, and any usage constraints. Not complete for a 2-param tool.
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% and description fails to explain page and pageSize parameters. The phrase 'all available exercises' contradicts pagination presence. No parameter meaning added.
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?
Clearly states verb 'Get' and resource 'exercise library' with specific fields (IDs, muscle groups, equipment). Distinguishes well from sibling 'get_exercise_template' which is singular.
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?
Implies it's for listing all exercises, but no explicit guidance on when to use vs alternatives like get_exercise_template. Does not mention when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single routine by ID with all exercises and sets
| Name | Required | Description | Default |
|---|---|---|---|
| routineId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior. It states the retrieval of a routine with exercises and sets, implying a read-only operation. However, it does not mention potential errors (e.g., missing ID), permissions, or response characteristics, leaving some gaps.
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 with no superfluous words. It is front-loaded with the key 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?
Given the tool's low complexity (one required parameter, no output schema), the description is largely adequate. It covers the core functionality and return content. Minor omissions like error handling or authentication details are tolerable for such a simple tool.
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 sole parameter 'routineId' has no schema description (0% coverage). The tool description adds only the phrase 'by ID', which minimally clarifies it's an identifier. No format, constraints, or examples are provided, offering little value beyond the parameter name.
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 the verb ('Get'), resource ('a single routine'), and scope ('by ID with all exercises and sets'). It distinguishes itself from sibling tools like 'get_routines' (plural) and 'get_routine_folder' by specifying the single entity and included details.
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 explicit guidance on when to use this tool versus alternatives like 'get_routines' for listing or 'get_workout' for workouts. The description implies usage for fetching a specific routine, but lacks exclusion criteria or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific routine folder by ID
| Name | Required | Description | Default |
|---|---|---|---|
| folderId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not disclose behavioral traits such as read-only nature, authentication requirements, or side effects. For a retrieval tool, basic safety info is missing.
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, making it concise, but it is under-specified. While it avoids verbosity, the brevity comes at the cost of completeness.
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 simple tool (1 param, no output schema), the description is minimally adequate but lacks essential context: what a routine folder is, expected return format, or any constraints. It fails to fully inform an AI agent.
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 adds no meaning to the folderId parameter beyond its type and requirement. The agent gets no help on what value to provide.
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 the action (Get) and resource (specific routine folder by ID). It distinguishes from the sibling tool get_routine_folders by specifying 'specific' and 'by ID', though it doesn't elaborate on the difference.
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 (e.g., get_routine_folders for listing). The description simply states the action without context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of routine folders
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. It only states 'get a list' which implies read-only, but doesn't disclose pagination behavior, sorting, or any side effects.
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?
Single sentence, no wasted words, but too terse to convey necessary detail.
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?
With two parameters, no output schema, and many sibling tools, the description lacks detail on pagination, return format, and differentiation from similar tools.
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 mention the 'page' or 'pageSize' parameters, offering no added meaning beyond 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 'Get a list of routine folders' clearly states the verb (Get) and resource (list of routine folders) and distinguishes from sibling 'get_routine_folder' which retrieves a single folder.
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 on when to use this tool vs alternatives like get_routine_folder or get_routines. Pagination context is implied by parameters but not explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a paginated list of saved workout routines
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations; description only mentions 'paginated' but doesn't disclose default pagination behavior, sorting, filtering, or what happens when parameters are omitted.
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?
Single clear sentence, no unnecessary words.
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?
Lacks parameter details, return value info, and error handling; incomplete for a 2-param tool with no annotations.
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?
With 0% schema description coverage, the description does not explain the parameters beyond the vague implication of pagination; no addition of meaning.
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 the tool retrieves a paginated list of saved workout routines, distinguishing it from the singular get_routine sibling.
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 on when to use this tool vs alternatives like get_routine, or when pagination is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current Hevy user's profile info (username, join date, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It indicates a read operation but does not mention authentication requirements, rate limits, or any potential side effects. The lack of explicit behavioral details is a minor 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 sentence with no unnecessary content, making it highly concise and front-loaded.
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 simplicity of the tool (no parameters, no output schema), the description is largely complete. It specifies the user and what info is retrieved, though a brief note on return format would improve completeness.
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?
There are no parameters, and schema description coverage is 100%. The description adds context beyond the schema by specifying the purpose, but there are no parameters to elaborate on, so baseline 3 is appropriate.
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 the verb 'Get', the resource 'current Hevy user's profile info', and gives examples like username and join date, making it distinct from sibling tools that retrieve other entities.
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 the authenticated user's profile but lacks explicit guidance on when to use it versus alternatives 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 full details of a single workout by ID
| Name | Required | Description | Default |
|---|---|---|---|
| workoutId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates a read operation ('Get') but does not disclose any behavioral traits such as authentication requirements, rate limits, or the exact scope of 'full details'. The description is adequate but lacks transparency.
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 of 11 words, with no redundancy. Every word earns its place, making it highly efficient.
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's simplicity (one required parameter, no output schema, no annotations), the description is minimally viable. However, it lacks guidance on parameter semantics and behavioral transparency, resulting in gaps for a complete understanding.
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 has 0% description coverage for the parameter 'workoutId'. The description mentions 'by ID' but does not explain the parameter's origin or format. While the parameter name is self-explanatory, the description adds no additional value beyond 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 clearly states 'Get full details of a single workout by ID', specifying the verb (Get), resource (workout), and scope (single by ID). It effectively distinguishes from sibling tool 'get_workouts' which retrieves multiple workouts.
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 does not provide explicit guidance on when to use this tool versus alternatives like 'get_workouts' or 'update_workout'. Usage is implied but not directly stated, making it adequate but lacking clarity on context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the total number of workouts logged in Hevy
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It states the tool returns a count, which is adequate but does not elaborate on any other behavioral traits such as authentication requirements or scope (e.g., per user).
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 sentence with no wasted words. It is front-loaded and efficient.
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 parameterless tool, the description is mostly complete, but it does not specify the output format (e.g., integer) or clarify if the count is for the authenticated user or all users. This leaves some ambiguity.
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?
There are no parameters, so the baseline is 4. The description does not need to add parameter information as the schema is empty and fully covered.
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 the tool returns the total number of workouts logged in Hevy, with a specific verb and resource. It distinguishes from siblings like get_workouts (list) and get_workout (single).
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 explicit guidance on when to use this tool versus alternatives like get_workouts. The description is minimal and does not provide context for usage compared to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get workout events (updates/deletes) since a given date, useful for syncing local caches
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| since | Yes | ISO 8601 datetime, e.g. 2024-01-01T00:00:00Z | |
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It implies a read-only operation but does not disclose response format, pagination behavior, or potential constraints like rate limits or data freshness.
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 front-loaded and efficient, but lacks additional information on pagination or response details, which could be added without becoming verbose.
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 lack of output schema, annotations, and incomplete parameter documentation, the description is insufficient for a syncing tool. It does not explain the nature of events or how to handle pagination.
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 only 33% (only 'since' documented). The description does not explain 'page' or 'pageSize', and fails to convey pagination semantics, which is critical for a syncing tool.
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 the action (get), resource (workout events), and scope (since a given date), and distinguishes from sibling tools like get_workout or get_workouts by specifying events for syncing.
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 mentions usefulness for syncing local caches, indicating when to use, but does not explicitly state when not to use or compare with alternatives like fetching full workouts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a paginated list of workouts from Hevy
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| pageSize | No | Items per page, max 10 (default: 10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'paginated list'. No information about rate limits, authentication, sorting, or return structure. Minimal behavioral disclosure.
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?
Very concise single sentence, front-loaded with key information. No wasted words, though could be slightly more informative without losing conciseness.
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?
Adequate for a simple list tool with two well-described parameters, but lacks details on output format, default sorting, or any behavioral constraints that would help an agent fully understand the tool's behavior.
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 100% with basic parameter descriptions. The tool description adds no additional meaning beyond what the schema provides, so baseline 3 applies.
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 the action (Get), resource (workouts), and key characteristic (paginated list). It distinguishes from siblings like get_workout and get_workout_count well.
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 on when to use this tool vs alternatives like get_workout, get_workout_events. No mention of preconditions or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing routine
| Name | Required | Description | Default |
|---|---|---|---|
| routine | Yes | Updated routine fields | |
| routineId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It only states the action ('update') but does not mention whether it is destructive, requires specific permissions, error handling, or effects on related data.
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 with no redundancy. However, it lacks informative content that would justify its brevity; it is under-specified rather than efficiently detailed.
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 mutation tool with no output schema and no annotations, the description fails to cover return values, error scenarios, or side effects. It is incomplete for an agent to understand the tool's full behavior.
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 has 50% description coverage; only 'routine' has a minimal description ('Updated routine fields'). The description does not explain the structure of the routine object or the purpose of 'routineId', adding little value beyond 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 states 'Update an existing routine', which clearly indicates verb and resource. However, it does not differentiate from sibling update tools like 'update_routine_folder' or provide specifics about what aspects of a routine can be updated.
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 'create_routine' or 'get_routine'. There are no prerequisites or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a routine folder
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| folderId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only states 'rename' but does not disclose effects on folder contents, constraints on the title (e.g., uniqueness), or whether the operation is reversible.
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 short sentence, which is concise but could include more relevant information without becoming verbose. It is appropriately front-loaded.
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 no output schema and no annotations, the description lacks context on return values, error conditions, and required permissions. For a simple rename, it is barely adequate but leaves gaps.
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 has 0% description coverage. The description implicitly clarifies that 'title' is the new name, but it does not explain 'folderId' beyond identification. This adds minimal value over 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 'Rename a routine folder' clearly states the action (rename) and the resource (routine folder). It effectively distinguishes from sibling tools like create_routine_folder (create) and get_routine_folder (get).
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 when to rename vs. create a folder. There is no mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing workout in Hevy
| Name | Required | Description | Default |
|---|---|---|---|
| workout | Yes | Updated workout fields (same schema as create_workout) | |
| workoutId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the mutation but fails to mention idempotency, side effects, authentication needs, or any constraints. Minimal transparency.
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 but lacks depth. It is not verbose, but at the cost of utility. Could be improved with additional context without adding length.
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 two parameters (one nested), no output schema, and sibling tools providing context, the description is too sparse to guide an agent effectively. Missing details like allowed fields, response structure, or error conditions.
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 50% with only the 'workout' object described (via reference to create_workout). The description adds no parameter specifics; the 'workoutId' parameter is unexplained. Agent must infer behavior from name.
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 the tool updates an existing workout in Hevy, aligning with the tool name. It distinguishes from create_workout but does not differentiate from other update tools like update_routine.
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 on when to use this tool versus alternatives such as create_workout or get_workout. Missing prerequisites or context about required state (e.g., workout must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update body measurements for a specific date
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date in YYYY-MM-DD format | |
| measurement | Yes | Measurement values such as weight_kg, body_fat_percentage |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'create or update' but does not specify the behavior when a measurement for the given date already exists (overwrite, merge, or error). No details on data validation, authentication needs, or side effects.
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 of 9 words, concise and front-loaded. It efficiently conveys the core purpose, though it lacks detail that might be helpful. It does not waste words.
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 lack of output schema, no behavioral transparency, and no usage guidelines, the description is incomplete. It does not cover what happens on success, error conditions, or the structure of the measurement object. For a tool with a nested object parameter and no output schema, more context is needed.
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 100%, so the schema already describes both parameters. The description adds no additional meaning beyond the schema—it does not elaborate on the measurement object's expected keys or provide examples. Baseline is 3 with no added value.
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 the action (create or update) and resource (body measurements for a specific date). It distinguishes from sibling tools like get_body_measurement_by_date (read) and get_body_measurements (list). However, it could be more explicit about the upsert behavior (overwriting vs. merging).
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 provides no guidance on when to use this tool versus alternatives. For instance, it doesn't clarify that this is for adding or updating a single date's measurements, while get_body_measurement_by_date is for retrieval. No exclusions or prerequisites are mentioned.
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. Dates show when Glama detected each change.
v1.0.0create_routinecreate_routine_foldercreate_workoutget_body_measurement_by_dateget_body_measurementsget_exercise_historyget_exercise_templateget_exercise_templatesget_routineget_routine_folderget_routine_foldersget_routinesget_user_infoget_workoutget_workout_countget_workout_eventsget_workoutsupdate_routineupdate_routine_folderupdate_workoutupsert_body_measurementEach tool targets a distinct resource and action. Workout-related tools are differentiated by purpose (listing, counting, events, details). Exercise and measurement tools are similarly distinct.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_routine, get_workouts, upsert_body_measurement). No mixing of conventions.
21 tools is slightly above the ideal range but still reasonable for a fitness app covering routines, folders, exercises, workouts, and measurements. Each tool serves a clear purpose.
Covers create, read, update, and upsert for key resources, but notably missing delete operations (e.g., delete_routine, delete_workout, delete_body_measurement). Also lacks search/filter tools. Notable gap.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Create Hevy routines and analyze your training from chat. Unofficial; BYO Hevy PRO API key.
Agent-first strength-training platform across iOS, Web & MCP: read & write workouts, PRs & plans.
Training analytics over your Hevy log: e1RM, PRs, volume, consistency, bodyweight.
Private Apple Health metrics and workout detail for ChatGPT, Claude, and any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/karlhsueh/hevyapp-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
