Provides tools to access and manage workout data, routines, exercise templates, folders, body measurements, user info, and webhooks via the Hevy API (requires Hevy PRO subscription).
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., "@hevy-mcp show me my most recent workout"
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.
A Model Context Protocol (MCP) server implementation that interfaces with the Hevy fitness tracking app and its API. This server enables AI assistants like Claude Desktop and Cursor to access and manage workout data, routines, and exercise templates through the Hevy API (requires PRO subscription).
Related MCP server: Hevy MCP
Workout Management: Fetch, create, and update workouts.
Routine Management: Access and manage workout routines.
Exercise Templates: Browse available exercise templates with in-memory caching.
Folder Organization: Manage routine folders.
Webhook Subscriptions: Create, view, and delete webhook subscriptions for workout events.
Pick the workflow that fits your setup:
Scenario | Command | Requirements |
One-off stdio run |
| Node.js ≥ 26, Hevy API key |
Local development |
|
|
Node.js: v26 or higher (strongly recommended to use the exact version pinned in .nvmrc).
npm: v10 or higher.
Hevy API key: Required for all operations (available with Hevy PRO).
You can launch the server directly without cloning:
HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp# Clone the repository
git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp
# Install dependencies
npm install
# Create .env and add your keys
cp .env.sample .env
# Edit .env and add your HEVY_API_KEYTo use this server with Claude Desktop, add the following to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"hevy-mcp": {
"command": "npx",
"args": ["-y", "hevy-mcp"],
"env": {
"HEVY_API_KEY": "sk_live_your_key_here"
}
}
}
}Add this server under "mcpServers" in ~/.cursor/mcp.json:
{
"mcpServers": {
"hevy-mcp": {
"command": "npx",
"args": ["-y", "hevy-mcp"],
"env": {
"HEVY_API_KEY": "your-api-key-here"
}
}
}
}For a generic setup flow across MCP clients, use add-mcp:
npx add-mcp hevy-mcp --env "HEVY_API_KEY=secret"This bootstraps the hevy-mcp entry in your client config without manual JSON edits.
🚀 High Performance: Built with the Oxc toolchain (oxlint/oxfmt) for near-instant linting and formatting.
🛡️ Type Safety: Fully type-safe implementation using Zod and Kubb-generated API clients.
📉 Observability: Built-in Sentry monitoring for error tracking, lifecycle and tool tracing, and stdio parse diagnostics.
⚡ Optimized: Includes in-memory caching for exercise templates to reduce API latency.
Supply your Hevy API key via:
Environment Variable: HEVY_API_KEY (in .env or system environment).
CLI Argument: --hevy-api-key=your_key (after -- in npm scripts).
# Example .env
HEVY_API_KEY=your_hevy_api_key_herehevy-mcp includes Sentry monitoring to observe errors and usage in production. It initializes @sentry/node with tracing enabled and PII collection disabled by default. Recent observability changes also add:
lifecycle spans around server build, run, and stdio connect
per-tool execution spans plus captured handler exceptions
stdio parse diagnostics, including leading UTF-8 BOM stripping and invalid JSON context
a deterministic pseudonymous Sentry user ID derived from HEVY_API_KEY, so the raw key is never sent to Sentry
As of version 1.18.0, hevy-mcp only supports stdio transport. HTTP/SSE transport has been completely removed to simplify the codebase and focus on the native MCP experience.
Docker-based workflows are retired. The provided Dockerfile now exits with a message pointing to the stdio-native experience. Legacy GHCR images are no longer updated.
Category | Tools |
Workouts |
|
Routines |
|
Templates |
|
Folders |
|
Body Measurements |
|
User |
|
Webhooks |
|
Build: npm run build
Lint/Format: npm run check (uses oxlint/oxfmt)
Unit Tests: npx vitest run --exclude tests/integration/**
Full Test Suite: npm test (requires HEVY_API_KEY)
For a detailed senior engineer guide, please refer to AGENTS.md.
The API client is automatically generated from the OpenAPI spec using Kubb:
npm run build:clientLicense: MIT
Credits: Model Context Protocol, Hevy Fitness.
Contributions are welcome! Please open an issue or PR for any major changes.
Create a body measurement entry for a given date. All measurement fields are optional; null values are treated as omitted, since the Hevy API does not support clearing individual fields. Returns 409 if an entry already exists for that date — use update-body-measurement instead.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | The date of the body measurement (YYYY-MM-DD). Must be unique — returns 409 if an entry already exists for this date. | |
| hips | No | Hips circumference in centimeters | |
| waist | No | Waist circumference in centimeters | |
| neckCm | No | Neck circumference in centimeters | |
| abdomen | No | Abdomen circumference in centimeters | |
| chestCm | No | Chest circumference in centimeters | |
| leftCalf | No | Left calf circumference in centimeters | |
| weightKg | No | Body weight in kilograms | |
| leftThigh | No | Left thigh circumference in centimeters | |
| rightCalf | No | Right calf circumference in centimeters | |
| fatPercent | No | Body fat percentage | |
| leanMassKg | No | Lean body mass in kilograms | |
| rightThigh | No | Right thigh circumference in centimeters | |
| shoulderCm | No | Shoulder circumference in centimeters | |
| leftBicepCm | No | Left bicep circumference in centimeters | |
| rightBicepCm | No | Right bicep circumference in centimeters | |
| leftForearmCm | No | Left forearm circumference in centimeters | |
| rightForearmCm | No | Right forearm circumference in centimeters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that null values are omitted (not cleared) and 409 error for duplicates, adding context beyond annotations which already indicate non-read-only and non-idempotent.
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?
Two sentences, no filler; front-loaded with purpose, followed by key behavioral notes.
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?
Covers creation semantics, duplicate handling, and null behavior; missing return value mention but acceptable given no output 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 coverage is 100%, so baseline 3; description adds value by explaining that null values are treated as omitted, which is not 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 clearly states the verb 'Create' and the resource 'a body measurement entry for a given date', and distinguishes from update-body-measurement.
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?
Explicitly states when not to use (409 if entry exists) and provides alternative 'use update-body-measurement instead', plus guidance on null values.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a custom exercise template with title, type, equipment, and muscle groups.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| muscleGroup | Yes | ||
| exerciseType | Yes | ||
| otherMuscles | No | ||
| equipmentCategory | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits such as whether authentication is required, whether creation is idempotent, or what happens to the response. Annotations provide no hints (readOnlyHint=false, no other hints), so the description bears the full burden but fails to add context.
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 contains no unnecessary words. Every part earns its place.
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 5 parameters (4 required) and no output schema, the description is too minimal. It lacks information about what a template is, the return format, error conditions, or how this fits into the broader exercise template workflow.
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 schema description coverage at 0%, the description only names parameters (title, type, equipment, muscle groups) without adding semantics beyond the schema property names. It does not explain the meaning of each parameter, constraints beyond schema, or defaults like otherMuscles.
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 custom exercise template and lists the key fields (title, type, equipment, muscle groups). This verb+resource combination distinguishes it from sibling tools that create other entities like workouts or routines.
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 searching for existing templates or updating templates. There is no mention of prerequisites 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.
Create a new workout routine in your Hevy account. Requires a title and at least one exercise with sets. Optionally assign to a folder. Returns the full routine details including the new routine ID.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| title | Yes | ||
| folderId | No | ||
| exercises | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set readOnlyHint=false and destructiveHint=false, so description must clarify behavior. Description explains it creates a new routine and returns full details with new routine ID, which is sufficient. No contradictions; no extra safety warnings needed.
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?
Two concise sentences, no fluff. The first sentence states purpose and requirements; the second confirms return value. Efficiently structured for quick understanding.
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 schema (exercises with many sub-properties) and no output schema, the description is high-level but incomplete. It misses details about notes, supersetId, restSeconds, and set sub-properties (distance, duration, etc.). The description covers only the essentials, leaving gaps for 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%, so description must compensate. It mentions required title, exercises with sets, and optional folderId. However, it does not elaborate on other parameters like notes or nested set properties (reps, weight, type, etc.), which are in the schema but undocumented in the description. Only partial value 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?
The description clearly states it creates a workout routine, specifies resource type (Hevy account), and differentiates from sibling tools like create-workout and create-routine-folder. The verb 'Create' and resource 'workout routine' are explicit.
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 usage context: requires title and at least one exercise with sets, and optional folder. It implies when to use this tool (when creating a routine) but does not explicitly exclude scenarios or mention alternatives. Sibling tools are distinct, so no confusion.
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 in your Hevy account. Requires a name for the folder. Returns the full folder details including the new folder ID.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate mutation (readOnlyHint=false) but description adds context by stating it returns full folder details including the new ID. However, no discussion of side effects, permissions, or limits beyond what annotations imply.
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?
Two concise sentences, no unnecessary words. Front-loaded with the purpose, then key requirement, then return value.
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 create tool with one parameter, the description covers purpose, input requirement, and output. The lack of an output schema is compensated by mentioning return of full folder details. Minor gap: no mention of potential errors or constraints.
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 describes name as a required string with minLength 1, but description merely restates that a name is needed without adding semantic details like naming conventions or uniqueness constraints. With 0% schema description coverage, the description should compensate but does not.
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 new routine folder in Hevy, with a specific verb and resource. It distinguishes from sibling tools like create-routine and create-workout by focusing on folder creation.
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 creating a routine directly or when folders are needed. The description only mentions the required name parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new webhook subscription for this account. The webhook will receive POST requests when workouts are created. Your endpoint must respond with 200 OK within 5 seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The webhook URL that will receive POST requests when workouts are created | |
| authToken | No | Optional auth token that will be sent as Authorization header in webhook requests |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (which indicate no readOnly, destructive, etc.), the description adds that the webhook receives POST requests on workout creation and imposes a 5-second response requirement. It does not cover failure scenarios or rate limits, but adds useful context.
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?
Two sentences efficiently convey purpose and a key behavioral requirement. No redundant or unnecessary text.
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 creation tool with 2 parameters and no output schema, the description covers the main purpose and a critical constraint (timeout). It is missing potential error handling details or response format, but is adequate.
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 description adds minimal value. It mentions the webhook receives POST requests for workouts, which relates to the 'url' parameter, but does not elaborate beyond the schema. The 'authToken' parameter is not described in the description.
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 'Create a new webhook subscription for this account', specifying the verb 'create' and the resource 'webhook subscription'. It also explains the webhook's purpose (receiving POST requests when workouts are created), distinguishing it from sibling tools like delete-webhook-subscription.
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 clear context for when to use the tool (to create a webhook subscription) and includes a critical requirement (endpoint must respond with 200 OK within 5 seconds). However, it does not explicitly mention when not to use it or provide alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new workout in your Hevy account. Requires title, start/end times, and at least one exercise with sets. Returns the complete workout details upon successful creation including the newly assigned workout ID.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| endTime | Yes | ||
| exercises | No | ||
| isPrivate | No | ||
| startTime | Yes | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate write operation (readOnlyHint=false), non-destructive, non-idempotent. Description confirms creation and return of details, adding that a workout ID is assigned. However, no discussion of auth requirements, rate limits, or side effects like overwriting or conflicts.
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?
Two sentences, each serving a clear purpose: first states action and requirements, second states return value. No extraneous text. Efficient and well-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?
Description covers creation intent and returns but omits error conditions, prerequisites (e.g., exercise template existence), or validation constraints. Moderate complexity with 6 parameters and nested exercises array warrants more guidance for safe 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?
With 0% schema_description_coverage, description should compensate. It mentions required fields (title, startTime, endTime, exercises) but ignores all optional parameters like isPrivate, description, and lacks details on exercising input format (though schema provides structure). Incomplete coverage of 6 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?
Description clearly states 'Create a new workout' with specific verb and resource. Includes requirements (title, start/end times, exercises) and return value (workout ID). Clearly distinguishes from sibling tools like get-workout, update-workout, or create-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?
Description implies usage when creating a new workout but provides no explicit guidance on when to use vs alternatives. No mention of prerequisites (e.g., need for exercise templates) or when not to use (e.g., if editing an existing workout).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete the current webhook subscription for this account. This will stop all webhook notifications.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructive and idempotent. Description adds that it will stop all webhook notifications, providing behavioral context beyond 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?
Two efficient sentences with no wasted 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?
Adequately covers the essential information for a simple tool with no parameters. Could mention idempotency or confirmation, but annotations provide destructive and idempotent hints.
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?
No parameters in the input schema, so the description does not need to explain them. Schema coverage is 100%, and the description adds no param info, which 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?
Clearly states the action (delete) and the resource (webhook subscription), along with the consequence (stop notifications). Differentiates from create and get siblings.
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 or when not. The description only states what it does, not in which situations it is appropriate. However, given the tool's name and zero parameters, the usage context is somewhat implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single body measurement by date. Returns all measurement fields for the specified date.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | The date of the body measurement (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds that it returns all measurement fields, but does not disclose additional behaviors such as error handling or authentication 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 concise with two short sentences. The first sentence fronts the core purpose, and the second adds clarification about return values. 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?
Given the low complexity (single parameter, no output schema), the description covers what the tool does and returns. It lacks mention of error conditions but is otherwise sufficient for a simple read-only 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 100% with a detailed schema description. The description adds limited extra meaning beyond stating the date parameter is used for selection.
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 gets a single body measurement by date and returns all fields. The use of 'single' differentiates it from the sibling tool 'get-body-measurements' (plural).
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 by date but does not explicitly state when to use this tool versus alternatives like get-body-measurements or update-body-measurement. No when-to-use or when-not-to-use guidance is provided.
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 for the authenticated user. Returns measurements including weight, body fat, and various circumference measurements.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds that results are paginated and include weight, body fat, circumferences. Does not disclose pagination specifics (ordering, empty results) or other behaviors, but annotations cover safety.
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?
Two sentences, no redundancy, directly states purpose and return content. Efficiently 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?
Adequate for a simple list tool with annotations. However, lacks detail on response format (since no output schema) and pagination behavior, which could be improved.
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 'page' and 'pageSize' parameters. It only mentions pagination generically, leaving the agent without semantic guidance beyond the schema's default/min/max.
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 a paginated list of body measurements for the authenticated user, listing example fields. This distinguishes it from siblings like get-body-measurement (singular) and create-body-measurement.
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 use when a list of measurements is needed. No explicit when-not or alternatives, but context is clear. Could mention using get-body-measurement for a single entry.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get past sets for a specific exercise template, optionally filtered by start and end dates.
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | No | ISO 8601 end date for filtering history | |
| startDate | No | ISO 8601 start date for filtering history | |
| exerciseTemplateId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, describing it as a read operation. The description adds the concepts of 'past sets' and date filtering, which are consistent. However, it does not disclose other behavioral traits like pagination, ordering, or limits, which would be helpful.
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 front-loaded with the core action. Could be slightly expanded to include response format without losing efficiency.
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?
Without an output schema, the description does not specify what 'past sets' includes (e.g., reps, weight, date). Given 3 parameters and no output schema, some additional context about the response structure 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?
Input schema covers 67% of parameters with descriptions (startDate and endDate have ISO 8601 format notes). The overall tool description mentions optional date filtering, aligning with schema. However, the required exerciseTemplateId parameter lacks description in both schema and tool description, leaving ambiguity.
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 'Get past sets for a specific exercise template', specifying the verb, resource, and optional filtering. This distinguishes it from sibling tools like get-exercise-template or get-workout, which serve different purposes.
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-workout or get-exercise-templates. The description implies usage context (getting history for a specific exercise template), but does not state when not to use it or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get complete details of a specific exercise template by its ID, including name, category, equipment, muscle groups, and notes.
| Name | Required | Description | Default |
|---|---|---|---|
| exerciseTemplateId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, indicating a safe read operation. The description adds that it returns 'complete details' and lists fields, but does not disclose additional behavioral traits such as error handling, authentication needs, or rate limits. With annotations already covering safety, the description adds moderate value.
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 18 words, front-loaded with the action and resource, and lists the fields concisely. Every word contributes value; no waste.
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, the description covers the purpose and return fields. It does not mention error cases or what happens if the ID is invalid, but given no output schema, it provides sufficient context for a straightforward read operation.
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. However, it only mentions 'by its ID' without explaining the format, source, or constraints of 'exerciseTemplateId'. The schema says minLength 1, but the description adds minimal meaning, leaving the parameter 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 clearly states the tool retrieves complete details of a specific exercise template by ID, listing the fields included (name, category, equipment, muscle groups, notes). It distinguishes from siblings like 'get-exercise-templates' (plural) and 'search-exercise-templates' by focusing on a single template 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?
The description implies use when needing details of one template, but does not explicitly state when to use this tool versus siblings like 'get-exercise-templates' for listing or 'search-exercise-templates' for searching. No when-not or alternative guidance is provided.
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 exercise templates (default and custom) with details like name, category, equipment, and muscle groups. Useful for browsing or searching available exercises.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is clear. The description adds useful context about the returned fields and pagination, which helps the agent understand what to expect beyond the schema. No contradictions.
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?
Two concise sentences, front-loaded with the main action. No fluff or unnecessary detail. Efficient and scannable.
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 explicit output schema description; only lists a few example fields. Does not mention pagination metadata, total counts, or error behaviors. Given no output schema, more detail on the return structure 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?
Schema has 0% description coverage for parameters. The description only mentions 'paginated list,' which hints at pagination parameters but does not explain 'page' or 'pageSize' semantics. With no parameter descriptions in the schema, the description should compensate more explicitly.
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 it gets a paginated list of exercise templates with specific details. However, does not explicitly differentiate from the sibling 'search-exercise-templates' tool, which could cause confusion for the agent.
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?
Says 'useful for browsing or searching available exercises,' implying context but not clearly stating when to use this vs. the 'search-exercise-templates' sibling. No explicit when-not-to-use 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 a routine by its ID using the direct endpoint. Returns all details for the specified routine.
| Name | Required | Description | Default |
|---|---|---|---|
| routineId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds that it 'returns all details', which is useful beyond the readOnlyHint annotation. However, it does not describe any other behavioral traits such as potential missing fields or error handling.
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 two sentences long, front-loaded with the core action, and contains no extraneous information. Every sentence adds value.
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 read operation with one parameter and no output schema, the description is adequate but lacks details about the return format or what 'all details' entails, which 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?
The description does not elaborate on the sole parameter 'routineId'. With 0% schema description coverage, the description fails to compensate by adding meaning beyond the schema, even though the parameter name is self-explanatory.
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 ('routine'), and the identifier ('by its ID'). It distinguishes from the sibling tool 'get-routines' by specifying direct retrieval of a single 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?
The description implies usage when you have a routine ID and need full details, but it does not explicitly state when to use this tool over alternatives like get-routines. 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.
Get complete details of a specific routine folder by its ID, including name, creation date, and associated routines.
| Name | Required | Description | Default |
|---|---|---|---|
| folderId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, saving description from needing safety disclosure. The description adds return content (name, dates, routines) but no further behavioral traits like pagination or error conditions.
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, no redundancy, front-loaded with action and resource. Every word contributes.
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 simplicity (1 param, no output schema, read-only), the description covers main purpose. Missing explicit response structure detail, but adequate for a basic GET operation.
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%; description merely says 'by its ID' without detailing the folderId parameter's type, required status, or format. The schema defines it as a string with minLength=1, but the description adds minimal 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 uses specific verb 'get' and resource 'routine folder', listing returned fields: 'name, creation date, and associated routines'. It clearly distinguishes from sibling tools like 'get-routine-folders' (list) and 'get-routine' (single 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 or when not to use this tool vs alternatives like get-routine-folders. The mention 'by its ID' implies a prerequisite but no explicit context.
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 your routine folders, including both default and custom folders. Useful for organizing and browsing your workout routines.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the description does not need to restate safety. It adds pagination context, but lacks details on behavior when parameters are out of bounds or the response format.
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 concise with two sentences and front-loads the primary action, but omits parameter documentation which would improve structure.
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 list endpoint with two optional parameters and no output schema, the description is somewhat complete but lacks parameter semantics, reducing overall 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?
Schema coverage is 0% and the description does not explain the page and pageSize parameters, failing to add meaning beyond the schema. With two parameters undocumented, the description should compensate.
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 a paginated list of routine folders, including both default and custom folders, distinguishing it from the 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?
The description mentions it is useful for organizing and browsing workout routines, but does not provide explicit guidance on when to use this tool versus alternatives like get-routine-folder for a specific folder.
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 your workout routines, including custom and default routines. Useful for browsing or searching your available routines.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds pagination behavior but no other behavioral 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?
Two efficient sentences with no fluff. Front-loaded with key information.
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 few parameters and no output schema. Could mention pagination details more explicitly.
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 description does not explain page or pageSize parameters. Misses opportunity to add 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?
Clearly states action (get), resource (paginated list of workout routines), and scope (custom and default). Distinguishes from siblings like get-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?
Implies usage for browsing or searching routines. No explicit when-not or alternatives, but context is clear enough given sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the authenticated user's account info, including user ID, display name, and public profile URL. Useful for verifying which account the API key belongs to.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint: true, so the description's mention of 'account info' and specific fields adds context beyond the annotation. It does not contradict annotations and provides useful details about returned 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 two sentences, front-loaded with the core action, and concise. Every word adds value.
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?
Without an output schema, the description fully explains what the tool returns (user ID, display name, public profile URL). It is complete for a simple, zero-parameter retrieval 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?
There are no parameters, and schema coverage is 100%. The description correctly indicates no input is needed, so parameter semantics are perfectly clear.
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 the authenticated user's account info, listing specific fields (user ID, display name, public profile URL). It uniquely identifies its purpose among siblings, which focus on body measurements, routines, and 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 explicitly mentions it is useful for verifying which account the API key belongs to, providing a clear use case. While it doesn't explicitly state when not to use it, the sibling tools' purposes are distinct, making confusion unlikely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current webhook subscription for this account. Returns the webhook URL and auth token if a subscription exists.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. The description adds that it returns URL and auth token if a subscription exists, but does not mention behavior when no subscription exists or any other edge cases. Adds minor context beyond 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?
Two sentences, front-loaded with the action, no unnecessary words. Highly concise and clear.
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 read tool with no parameters and no output schema, the description explains the return values sufficiently. Lacks mention of error handling or authentication, but given annotations and simplicity, it is mostly complete.
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?
No parameters exist (0 params, 100% schema coverage). The description does not need to add parameter info, but it clarifies what the response contains, which is valuable. Baseline for zero-parameter tools is 4.
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 the current webhook subscription for the account and specifies the returned data (webhook URL and auth token). Among siblings (create, delete), this 'get' tool is distinctly identified.
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 siblings like create-webhook-subscription or delete-webhook-subscription. The usage is implied by the name and description but not stated directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get complete details of a specific workout by ID. Returns all workout information including title, description, start/end times, and detailed exercise data.
| Name | Required | Description | Default |
|---|---|---|---|
| workoutId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the return contents (title, description, times, exercise data) beyond the readOnlyHint annotation. Does not discuss authentication or error handling, but adds context about what is returned.
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?
Two sentences with no wasted words. Front-loaded with the core purpose, then specifies return data.
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 read-only tool with one required parameter and no output schema, the description sufficiently covers what it does and what it returns. Lacks details on error handling but is adequate.
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 has 0% description coverage for the single parameter workoutId. The description mentions 'by ID' which hints at the parameter's purpose, but does not explicitly describe the parameter or its constraints. This partially compensates 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?
Clearly states the verb 'Get' and the resource 'workout', specifies that it returns complete details by ID. This distinguishes it from sibling tools like get-workouts (list) and get-workout-count.
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?
Does not explicitly state when to use this tool instead of alternatives like get-workouts or get-workout-events. Implies usage when full details of one workout are needed, but lacks explicit guidance.
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 on the account. Useful for pagination or statistics.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds that output is a count, but no further behavioral disclosure (e.g., caching, rate limits). Adds value beyond 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?
Two sentences, zero waste. Front-loaded with purpose, immediately followed by use case.
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?
Completely adequate for a parameterless, read-only tool with clear purpose and usage context. No missing information.
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?
No parameters, baseline 4. Description does not need to add parameter info, but it appropriately omits anything irrelevant.
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?
Clear verb+resource: 'Get the total number of workouts on the account.' Distinguishes from sibling 'get-workouts' by emphasizing count vs list, with explicit use case (pagination/statistics).
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?
Provides context for usage ('Useful for pagination or statistics') which implies when to use count vs list, but lacks explicit when-not-to-use or alternative naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a paged list of workout events (updates or deletes) since a given date. Events are ordered from newest to oldest. The intention is to allow clients to keep their local cache of workouts up to date without having to fetch the entire list of workouts.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| since | No | 1970-01-01T00:00:00Z | |
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only. Description adds ordering (newest to oldest) and pagination details, which are not in annotations. No contradictions.
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?
Three sentences, front-loaded with core action. No filler. Every sentence adds value.
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?
Covers key behavioral aspects (paging, ordering, caching use case) but lacks description of event structure or error handling. Acceptable given no output 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%, so description must compensate. It mentions 'since a given date' and 'paged list' connecting to since, page, pageSize. However, it doesn't detail data types, defaults, or max/min constraints.
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 'retrieve', resource 'workout events', and scope 'paged list since a given date'. Distinguishes from fetch-all tools like 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?
Provides context for syncing caches, implying incremental updates. Does not explicitly exclude alternatives or list when-not-to-use, but the intention is clear.
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. Returns workout details including title, description, start/end times, and exercises performed. Results are ordered from newest to oldest.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds behavioral context about pagination and ordering (newest to oldest), which is beneficial beyond the 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?
Two sentences with no redundant information. The purpose is front-loaded, and every sentence adds value: first sentence states action and outcome, second sentence adds detail on returned fields and ordering.
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, the description explains return fields (title, description, times, exercises). However, it could be more complete by detailing pagination behavior (e.g., total count, next page). Adequate for a simple list tool but not fully comprehensive.
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%, meaning parameters 'page' and 'pageSize' have no descriptions. The description mentions 'paginated' but does not explain the meaning, defaults, or constraints of these parameters, thus failing to compensate for the missing 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 verb 'Get' and the resource 'paginated list of workouts', and distinguishes from sibling tools like 'get-workout' (single) and 'get-workout-count' by specifying it returns a list with ordering.
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 multiple workouts but does not explicitly state when to use versus alternatives like single-get or count endpoints. No exclusions or when-not guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search exercise templates by name with optional muscle group filter. Fetches all templates from the Hevy API on first call and caches them in memory for subsequent searches. Use refresh:true to force a re-fetch.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Case-insensitive substring to match against exercise template titles | |
| refresh | No | Set to true to bust the in-memory cache and re-fetch all templates from the API | |
| primaryMuscleGroup | No | Optional filter to restrict results to a specific primary muscle group |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds caching behavior (fetches all on first call, caches in memory, refresh busts cache) beyond the readOnlyHint and openWorldHint annotations. No contradictions. Could mention potential staleness of cache.
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?
Two sentences effectively cover purpose and caching behavior. Every word earns its place; no fluff.
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 description covers purpose, caching, and parameter usage but does not mention the return format or pagination. With no output schema, the agent may lack information about what the response contains.
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 descriptions, but the narrative adds context: 'case-insensitive substring' for query, 'bust the in-memory cache' for refresh, and 'optional filter to restrict results' for primaryMuscleGroup. This adds 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 the verb 'search', resource 'exercise templates', and scope 'by name with optional muscle group filter'. It distinguishes from sibling tools like get-exercise-templates (which likely returns all without search) and get-exercise-template (single by ID).
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 when to use the refresh parameter ('Use refresh:true to force a re-fetch') and explains caching behavior. However, it does not explicitly contrast with alternative tools like get-exercise-templates for retrieving all templates or get-exercise-template for a known ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing body measurement entry for a given date. Only the fields you provide are sent and updated; null values are treated as omitted, since the Hevy API does not support clearing individual fields. Requires at least one measurement field. Returns 404 if no entry exists for the date.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | The date of the body measurement to update (YYYY-MM-DD). Must already exist — returns 404 otherwise. | |
| hips | No | Hips circumference in centimeters | |
| waist | No | Waist circumference in centimeters | |
| neckCm | No | Neck circumference in centimeters | |
| abdomen | No | Abdomen circumference in centimeters | |
| chestCm | No | Chest circumference in centimeters | |
| leftCalf | No | Left calf circumference in centimeters | |
| weightKg | No | Body weight in kilograms | |
| leftThigh | No | Left thigh circumference in centimeters | |
| rightCalf | No | Right calf circumference in centimeters | |
| fatPercent | No | Body fat percentage | |
| leanMassKg | No | Lean body mass in kilograms | |
| rightThigh | No | Right thigh circumference in centimeters | |
| shoulderCm | No | Shoulder circumference in centimeters | |
| leftBicepCm | No | Left bicep circumference in centimeters | |
| rightBicepCm | No | Right bicep circumference in centimeters | |
| leftForearmCm | No | Left forearm circumference in centimeters | |
| rightForearmCm | No | Right forearm circumference in centimeters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: the API doesn't support clearing fields, so null values are omitted. This explains the idempotent behavior (sending same fields multiple times yields same result) and potential destructive nature (updating fields). The 404 response is also disclosed.
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 concise, with three sentences that cover purpose, behavior, and caveats. No unnecessary words or repetition. Well-structured and easy to parse.
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 18 parameters and no output schema, the description covers the essential behavioral aspects: partial update semantics, null handling, required date, and 404 error. Missing success response format, but this is acceptable without an output schema. Adequate for agent decision-making.
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 every parameter is described. The description adds valuable overall behavior: only provided fields are sent and updated, and at least one measurement field must be provided (not enforced in schema beyond date). This clarifies how to construct requests correctly.
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 updates an existing body measurement entry for a given date, specifying the resource and action. It implicitly distinguishes from sibling tools like create-body-measurement by emphasizing 'existing' but does not explicitly contrast.
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?
Provides clear guidance: null values are treated as omitted (cannot clear fields), requires at least one measurement field, and returns 404 if date doesn't exist. This tells the agent how to use the tool correctly and what to expect.
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 by ID. You can modify the title, notes, and exercise configurations. Returns the updated routine with all changes applied.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| title | Yes | ||
| exercises | No | ||
| routineId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true; the description adds the return value but no additional behavioral context (e.g., partial vs full update, authorization needs, rate limits).
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?
Two sentences with no filler; first sentence states purpose, second sentence clarifies return value. Efficient 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 complex nested 'exercises' parameter and no output schema, the description provides only the most basic field names. It does not guide the agent on constructing the exercise array, leaving gaps for a tool with high parameter complexity.
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 coverage, the description only names 'title, notes, and exercise configurations' but fails to explain the complex nested structure of the 'exercises' parameter or mention the required 'routineId' parameter explicitly.
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 the action ('Update an existing routine by ID'), the resource ('routine'), and the modifiable fields, distinguishing it from sibling tools like create-routine and get-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?
Implies use for modifying existing routines, but lacks explicit when-not-to-use or alternatives among siblings. However, the tool name and description make the context clear.
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 by ID. You can modify the title, description, start/end times, privacy setting, and exercise data. Returns the updated workout with all changes applied.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| endTime | Yes | ||
| exercises | No | ||
| isPrivate | No | ||
| startTime | Yes | ||
| workoutId | Yes | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and idempotentHint=true. The description mentions returns but does not elaborate on side effects, required permissions, or partial update behavior. It neither contradicts nor significantly extends the 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?
Two concise sentences, front-loaded with action, no filler. Every sentence adds value.
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, the description includes return value info. It adequately covers parameters and behavior for a straightforward update tool. Lacks error handling or prerequisite details, but sufficient for typical use.
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 adds meaning by enumerating modifiable fields (title, description, start/end times, privacy, exercises). It helps the agent understand what each parameter group does, though it does not detail subfields like exercise 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 clearly states the action ("Update an existing workout"), the resource (workout), and lists the modifiable fields. It distinguishes from siblings like create-workout (create vs update) and get-workout (read vs write).
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 use when modifying an existing workout but does not explicitly state when to use alternatives (e.g., update-routine) or any prerequisites. No guidance on when not to use this tool.
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.
v1.25.12create-body-measurementcreate-exercise-templatecreate-routinecreate-routine-foldercreate-webhook-subscriptioncreate-workoutdelete-webhook-subscriptionget-body-measurementget-body-measurementsget-exercise-historyget-exercise-templateget-exercise-templatesget-routineget-routine-folderget-routine-foldersget-routinesget-user-infoget-webhook-subscriptionget-workoutget-workout-countget-workout-eventsget-workoutssearch-exercise-templatesupdate-body-measurementupdate-routineupdate-workoutScored across 26 tools
Each tool targets a distinct resource and action, with clear names that prevent confusion. For example, get-exercise-template vs get-exercise-templates vs search-exercise-templates are unambiguous.
All tools follow a consistent verb_noun pattern using snake_case, such as create-body-measurement, get-workouts, delete-webhook-subscription. No mixing of styles.
With 26 tools covering multiple resources (body measurements, exercises, routines, folders, webhooks, workouts, user info), the count is slightly high but still well-scoped for a fitness tracking server.
Several resources lack delete operations (e.g., body measurements, routines, workouts) and some lack updates (exercise templates, routine folders). While the core workflows are covered, these gaps are notable and could cause agent inconvenience.
Create Hevy routines and analyze your training from chat. Unofficial; BYO Hevy PRO API key.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
