@diecoscai/hevy-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.5.0
Disambiguation5/5
Each tool has a distinct purpose: user info, workouts, routines, folders, exercise templates, and body measurements are clearly separated. Even similar tools like list vs search templates are distinguishable by their descriptions.
Naming Consistency5/5
All tools use the 'hevy_verb_noun' pattern in snake_case, with verbs like get, list, create, update, search. The naming is uniform and predictable.
Tool Count5/5
23 tools cover the Hevy API's main domains (user, workouts, routines, exercise templates, body measurements) without being excessive. Each tool has a clear role.
Completeness4/5
Most CRUD operations are present, but deletions are missing (API limitation) and folder updates are not supported. These are minor gaps given the API constraints.
Average 4.1/5 across 23 of 23 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 8 commits in the last 12 weeks
- Last stable release on May 22, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It only states the action without addressing side effects, read-only nature, error behavior (e.g., if routine not found), or authentication requirements. For a single-resource fetch, read-only is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. However, it is overly sparse; while concise, it sacrifices useful detail. It is front-loaded with the core action but lacks elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 insufficiently complete. It does not describe the return format, possible errors, or any additional behavior. For a simple GET endpoint, it is acceptable but minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema parameter descriptions are 0% covered. The description adds that the routine is identified by UUID, but the schema already specifies format=uuid. It does not explain the purpose of 'routineId' beyond the tool name, nor does it compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch one routine by UUID' specifically names the action (fetch), resource (one routine), and identifier (UUID). It clearly distinguishes from sibling tools like 'hevy_list_routines' which fetches all routines.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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., when to use 'hevy_list_routines' or 'hevy_get_routine_folder'). It does not specify prerequisites or context such as needing the UUID from a previous list call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It does not mention failure modes (e.g., folder not found), authentication requirements, or any side effects. It only states what the tool does, not its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence containing exactly the necessary information. No wasted words, and it is front-loaded with the action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no nested objects, no output schema), the description is adequate but minimal. It does not explain the return value or error cases, which would be helpful for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage, meaning no parameter descriptions. The description partially compensates by stating 'by its positive integer id', but it merely restates the schema constraints without adding new meaning. The required folderId parameter's purpose is clear, but no further semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Fetch) and the resource (routine folder) with the specific identifier type (positive integer id). It distinguishes from sibling tools like hevy_list_routine_folders by specifying 'one' and providing the lookup method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 hevy_list_routine_folders or hevy_get_routine. The agent is left to infer that this is for fetching a single folder by ID, but there is no mention of when this is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides some behavioral context: pagination constraints (pageSize 1-10) and return envelope structure. However, the note 'No DELETE endpoint' is tangential and not clearly relevant to the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise and front-loaded with the main action. The inclusion of 'No DELETE endpoint' is slightly out of place and adds a minor distraction, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with pagination, the description adequately covers the purpose, pagination limits, and return structure (envelope). Lacks error handling or empty list behavior, but acceptable for a read-only list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema (100% coverage). The description only repeats schema info (pageSize range) and adds no new semantic meaning for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List routine folders' with a specific verb and resource. While it doesn't explicitly distinguish from hevy_get_routine_folder, the name itself differentiates list vs get operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 hevy_get_routine_folder or hevy_create_routine_folder. No context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It adds the envelope structure and server-enforced pageSize limit, but does not explicitly state safety (e.g., read-only) 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short with three sentences, front-loaded with purpose. No wasted words, though the 'No DELETE endpoint' note is slightly out of place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 2 parameters and no output schema, the description provides the envelope structure and server behavior, making it fairly complete. Missing details like sorting or array size are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description repeats the pageSize limit from the schema and adds envelope info, but does not add meaningful new parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List routines' which is a specific verb and resource. The tool name and context distinguish it from siblings like 'hevy_get_routine' and 'hevy_list_workouts', though no explicit differentiation is given.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The only extra note about 'No DELETE endpoint' is tangential and does not help with usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It confirms the tool is a read operation returning full record details, but does not mention error behavior (e.g., what happens if UUID is invalid), idempotency, or any side effects. It is adequate for a simple fetch but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short, well-structured sentences. Every word adds value, with the core action and return information front-loaded. No redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with one parameter and no output schema, the description is largely complete. It addresses the return content (full record, exercises, sets) and assumes standard behavior. Minor gaps include lack of error handling details and idempotency, but overall it is sufficient for such a straightforward operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no new meaning beyond what the schema already provides (that 'workoutId' is a UUID). It fails to compensate for the lack of parameter documentation, merely restating the parameter's type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch'), resource ('one workout'), identifier ('by UUID'), and the scope of return data ('full record including exercises and sets'). It effectively distinguishes from sibling tools like hevy_list_workouts or hevy_get_workout_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (having a UUID and needing full workout details) but does not explicitly state when not to use or provide direct comparisons to alternatives. Usage context is implied rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits beyond the schema: dry-run mode by default, the environment variable HEVY_MCP_ALLOW_WRITES to enable actual writes, and that rep_range is only accepted on routine sets (not workout sets). This compensates for the lack of annotations. It does not mention error handling or response format on success, but the dry-run explanation is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of 6 sentences, front-loaded with the main action and endpoint. Every sentence adds unique information (required fields, references, set types, dry-run behavior). No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested object parameter) and missing annotations, the description covers essential usage but leaves gaps: it does not describe the success response format (routinely created object) or error conditions (e.g., duplicate titles, invalid folder_id). The dry-run behavior is well explained, but an agent may need more on what happens after a real write.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds significant meaning: it explains the required outer fields (title, exercises), the need for exercise_template_id, optional folder_id, set types (warmup|normal|failure|dropset), and the rep_range nuance. It does not detail all inner fields like notes or superset_id, but covers the key aspects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create a routine) and the HTTP method (POST /v1/routines). It lists required fields (title, exercises) and references sibling tools for lookups (hevy_list_exercise_templates, hevy_list_routine_folders), but does not explicitly differentiate from hevy_update_routine or hevy_create_workout beyond noting rep_range usage is routine-only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating routines and provides prerequisites (exercise_template_id, optional folder_id) with references to sibling tools for discovery. However, it does not explicitly state when to use this tool over alternatives like hevy_update_routine for modifications or hevy_create_workout for workouts, nor does it mention 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Mentions 404 return for missing date, but lacks detail on authentication or other behavioral aspects; annotations absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence, front-loaded with key information, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main purpose and result (record or 404), but doesn't describe record structure. Acceptable given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 0%, but description adds meaning by explaining the date parameter's role as identifier and format. Single parameter, so adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Fetch', resource 'body-measurements record', and identifier 'by date'. Distinct from sibling list/update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for a specific date, but no explicit comparison with sibling list tool or when-not scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It discloses that the new folder is inserted at index 0, shifting existing folders, and details the dry-run mechanism. This gives agents necessary understanding of 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient, starting with the core action and parameter, then explaining behavior and constraints in two sentences. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no output schema, and no annotations, the description covers the creation behavior, insertion index, and dry-run configuration. It lacks full response details for a successful write, but for a simple tool it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description confirms that 'title' is the only parameter and notes it's fixed after creation. However, it adds no additional semantic meaning beyond the schema constraints (e.g., uniqueness, format). With 0% schema coverage, the description compensates only modestly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a routine folder') with the HTTP endpoint. It explicitly specifies that the only parameter is 'title' and distinguishes from siblings by noting there are no update or delete tools for folders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context by explaining that the title is fixed after creation (no update/delete), implying caution. It also describes the dry-run behavior and how to enable writes via the environment variable, guiding when the tool actually performs writes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool returns the total number of workouts, but lacks details on caching, performance, or side effects. For a simple read operation, this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous content. It efficiently conveys the tool's purpose and output format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description is complete. It clearly states the return value and its meaning, fully meeting the needs for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description cannot add parameter-specific information. Coverage is 100% by default. The description adds value by explaining the return shape, which is sufficient given zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns the total number of workouts on the account, specifying the verb 'Return' and the resource '{ workout_count }'. It effectively distinguishes from sibling tools like hevy_list_workouts and hevy_get_workout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for getting a count but provides no explicit guidance on when to use this tool versus alternatives like hevy_list_workouts or hevy_get_workout. The context is clear, but no exclusions or alternative comparisons are made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: read-only (GET), pagination constraints (pageSize 1-10, server rejects >10), response envelope structure, and keying by date with no DELETE endpoint. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, and each sentence adds non-redundant value. It is concise but could be slightly more structured (e.g., bullet points) for easier scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional parameters, no output schema), the description covers the response format, pagination, keying, and lack of delete. It does not explain how to filter by date or handle missing data, but these are reasonable omissions for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and descriptions already cover parameters. The description adds minor extra context about pageSize range and rejection behavior, but does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists body measurements, specifies the HTTP method (GET), response envelope, pagination limits, and unique keying by date. It distinguishes itself from other tools by mentioning no DELETE endpoint and the keying scheme, providing high clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is a read-only list operation and mentions no DELETE endpoint, but does not explicitly state when to use this tool versus sibling tools like hevy_get_body_measurement or hevy_create_body_measurement. No alternatives or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: envelope structure, page size cap (unique among siblings), and ID format differences. Lacks mention of authentication or rate limits, but those are standard.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with no fluff. Could be slightly more structured (e.g., bullet points) but remains efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list endpoint with 2 params and no output schema, the description adequately covers response structure, id patterns, and unique cap. No major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. The description adds value by highlighting the pageSize cap as unique and noting 1-indexed pages, exceeding the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'list exercise templates (built-in + custom)' with a specific verb and resource, and distinguishes it from sibling tools like search and get by noting unique properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing all templates but does not explicitly contrast with search or get endpoints, nor does it provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It covers acceptable ID formats but does not disclose error behavior (e.g., on invalid/not found IDs) or any side effects. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary purpose, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter tool and no output schema, the description covers the key input constraint. Could mention it returns the template object, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds crucial context: acceptable formats (8-char uppercase hex and lowercase UUID). This adds significant meaning beyond the schema type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Fetch' and resource 'one exercise template by id', and distinguishes from sibling tools like list/search by specifying a single ID. Also clarifies acceptable ID formats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when a specific ID is known, but does not explicitly contrast with searching or listing. Mentions accepted formats, which helps avoid errors.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses POST mutation, dry-run by default (with enablement), duplicate detection (409), and suggests update tool. Missing details on authentication, rate limits, or idempotency, but is strong overall.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences long, front-loaded with purpose, then parameters, error handling, and dry-run behavior. No redundancy or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 18 parameters, no annotations, and no output schema, the description covers purpose, parameters, error handling, alternative tool, and dry-run. It could mention what the response contains (e.g., the created record) but is still fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 6% (only date described). The description lists all metric fields and clarifies they are optional and nullable, which adds value over the schema. However, no additional semantics or units beyond field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create one body-measurements record (POST /v1/body_measurements)', clearly specifying the verb and resource. It distinguishes from sibling hevy_update_body_measurement by referencing the alternative when a record already exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: required date format, optional/nullable fields, mention of 409 conflict with alternative tool, dry-run default with write-enablement condition. Tells the agent when to use this tool and when to switch to update.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It discloses that results include warmups/dropsets/failures, pagination details, date-range filtering, and default ordering (newest-first, all time). Does not mention rate limits or pagination error handling, but sufficiently covers behavior for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: first states purpose, second explains filter modes, third describes default behavior. No wasted words, information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and no output schema, description covers purpose, filtering, ordering, and row content. Lacks details on return format (e.g., pagination metadata) but is still fairly complete for a list tool. Minor gap in error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 80% of parameters. Description adds value by explaining that filters are combinable, that without start_date/end_date results span all time, and defaults for page/pageSize. Could clarify that exerciseTemplateId is required, but overall adds meaningful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists logged sets for a specific exercise template, specifying verb (List), resource (exercise history), and what is included (warmups/dropsets/failures). This distinguishes it from sibling tools like hevy_list_workouts (workout-level) and hevy_get_workout (single workout).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains when to use: to get history for a given exercise template. Mentions two filter modes and default time span. Does not explicitly list when not to use or alternatives, but the purpose is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses critical behavioral traits: the full-replace destructive nature, the rejection of folder_id (400 error), and the dry-run safety mechanism. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences efficiently cover purpose, key constraints, and safety behavior. Critical information is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers dry-run behavior, auth env var, and the folder_id limitation. No output schema exists, but description does not specify the success response format (probably returns updated routine). Slight gap, but non-critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description adds value by explaining that exercise_template_id is needed and that folder_id is not accepted. However, it does not explain the structure of the routine object or other nested fields (e.g., sets, rep_range). Partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states that the tool performs a full replace (PUT) of a routine, explicitly noting that omitted fields are dropped. Distinguishes from sibling create/get tools by specifying update semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context: mentions dry-run default, env variable for writes, and that folder_id is not accepted. Guides to use hevy_list_exercise_templates for exercise_template_id. Lacks explicit when-not-to-use comparison with similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses critical behaviors: full replace semantics, dry-run default (with env var to enable writes), and the absence of a DELETE endpoint. This provides excellent transparency beyond what the schema offers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 sentences) and front-loads the key replace behavior. It covers essential points without verbosity, though it could be slightly more structured by separating parameter guidance from behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested objects, no output schema, no annotations), the description covers all critical aspects: HTTP method, replace semantics, dry-run behavior, template ID source, and notes on API limitations. It is sufficiently complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has some descriptions (e.g., ISO-8601 for times, exercise_template_id format), but description coverage is low (0% per context). The description adds value by noting that exercise_template_id can be found via other tools, but does not explain other nested parameters like sets properties. The replace behavior is explained but not parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Full replace of a workout (PUT /v1/workouts/{id})' and explains that any field not re-sent is dropped. It distinguishes from potentially confusing partial updates, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the replace behavior and references sibling tools for finding exercise_template_id, guiding parameter preparation. However, it does not explicitly compare to other workout tools (e.g., hevy_create_workout) or state when this tool should be avoided, though the replace semantics imply it's for full updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes read operation, lists returned fields, and mentions authentication. No side effects or errors, but adequate for a simple read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-loaded with action and return value. Every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no output schema, but many sibling tools, the description fully conveys purpose, prerequisites, and output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline 4 applies. Description does not need to add parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns the authenticated user's name, id, and profile URL. Distinguishes from siblings like workout and routine tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions prerequisite (Hevy Pro api-key) and endpoint. No explicit when/why usage, but the distinct resource (user info) makes context clear among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It fully discloses the destructive null-overwrite behavior, the dry-run safety mechanism, and the configuration requirement (HEVY_MCP_ALLOW_WRITES). This gives the agent a complete understanding of the tool's side effects and safety constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet comprehensive. It starts with the core action, follows with the critical null-overwrite warning, provides a practical pattern for partial updates, and finishes with the dry-run behavior. Every sentence is purposeful and front-loaded for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested object, destructive operation, dry-run), the description covers most key aspects. It omits details about the return format beyond the dry-run example and does not mention error handling or authentication prerequisites. However, for a tool with sibling tools that provide additional context, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description must compensate. While it clarifies that body_measurement is an object whose missing fields become null, it does not list or explain individual fields beyond their presence in the schema. The description adds context about the replace semantics but lacks detailed parameter descriptions, so it only partially compensates for the absent schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'full replace' of body measurements for a date, using PUT. It explicitly distinguishes from a partial update and explains that unspecified fields are overwritten to NULL, leaving no ambiguity about the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: for a partial update, it instructs to first call hevy_get_body_measurement, modify, then send all fields. It also warns about the destructive null-overwrite behavior and mentions the dry-run default and the required environment variable to enable writes, giving clear when-to-use and when-not-to-use advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: case-insensitive substring matching, pagination limited to 30 pages of 100, truncation flag, total_matches as lower bound when truncated, and a one-hour catalog cache. This goes beyond basic disclosures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences plus a brief response format explanation. Every sentence adds value—no fluff, front-loaded with core purpose, and efficiently covers behavior and usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (search with pagination and truncation) and the absence of an output schema, the description thoroughly explains response fields (query, total_matches, exercise_templates, truncated) and the truncation behavior. It fully equips the agent to understand outcomes and limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have schema descriptions, but the description adds significant value: it clarifies query is 'case-insensitive substring matched against the template title' and provides default value for limit (25) and explains that total_matches reports the full count even if truncated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Find exercise templates by name' and specifies it paginates the full catalog, returning case-insensitive substring matches. It distinguishes from siblings by explicitly saying to use it to resolve an exercise_template_id from a human name before composing a workout or routine, differentiating it from listing all templates or getting by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool: 'Use this to resolve an exercise_template_id from a human name... before composing a workout or routine.' It implies not to use it if you already have the ID, but does not provide explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden. It discloses the dry-run default, the requirement for a server env variable to actually create, and the expected response shape, ensuring the agent understands the tool's non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured, front-loading the action and then detailing enums and special behavior. It could be slightly more concise, but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested object, multiple enums, and dry-run behavior, the description is thorough. It covers all essential aspects for correct invocation without relying on an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 0%, the description enumerates all enums (exercise_type, muscle_group, equipment_category) and explains the exercise object structure, including the optional other_muscles array, providing complete parameter semantics beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create a custom exercise template' and lists required fields (title, exercise_type, muscle_group, equipment_category), distinguishing it from sibling tools like hevy_list_exercise_templates and hevy_search_exercise_templates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains the dry-run default behavior and the environment variable (HEVY_MCP_ALLOW_WRITES=1) needed to execute actual writes, providing clear when-to-use and how-to-enable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the dry-run behavior and the env var requirement for actual writes, which is critical behavioral info. It also mentions that rep_range is rejected. No annotations exist, so the description fully carries the transparency burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of moderate length that packs substantial information. It is front-loaded with key facts, but could be slightly more structured (e.g., bullet points) for easier scanning. Still, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the nested parameter and no output schema, the description covers all critical aspects: required fields, exercise template resolution, set configuration, superset rules, rejection of rep_range, and dry-run mode. It references sibling tools where needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It extensively explains the 'workout' object structure, required subfields, set types, RPE enum, superset_id constraints, and template ID formats, adding significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a workout (POST /v1/workouts)' and lists required fields, distinguishing it from update or other operations. It provides specific verb and resource, with additional context on exercise templates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells how to use the tool: required fields, resolving exercise_template_id via sibling tools, and notes that rep_range is rejected and dry-run is default. It gives clear context and alternatives for template lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: event structure (updated/deleted), pagination limits (pageSize 1-10 with HTTP 400 for >10), and the importance of since for detecting deletions. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, every sentence adds value. No redundancy or fluff. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and no annotations, the description is self-contained. It explains the return format, usage pattern, and error condition. No missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 3 parameters. The description adds functional context (e.g., how to use since for sync, pageSize limit enforcement) beyond the schema, though schema already covers basic meaning. Baseline 3 with upgrade due to added usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'Delta sync feed' for workouts, returning events newer than a timestamp. It distinguishes from sibling tools like hevy_list_workouts by emphasizing deletion detection, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit instructions are given for incremental sync: first call with since=1970-01-01T00:00:00Z, subsequent calls with the newest seen timestamp. It also notes that this is the only way to detect deletions, guiding the agent to use this tool for that purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behavioral traits: pagination order ('newest-first'), error behavior ('Hevy returns 400 for >10'), empty state ('Empty account returns workouts: []'), and a limitation ('No DELETE endpoint exists on the Hevy API'). It also describes the response envelope structure. This fully compensates for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise three-sentence paragraph that front-loads the main purpose. Every sentence serves a distinct role: stating the action, providing usage guidance, and detailing behavioral/structural notes. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 well-described parameters and no output schema, the description covers all essential aspects: pagination, error handling, empty state, and relationship to sibling tools. It is complete enough for an agent to use the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to explain parameters in depth, but it adds value by mentioning the error response for pageSize >10, which reinforces the schema's description. It does not add additional parameter semantics beyond that, but the baseline is 3 and the added context justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List workouts newest-first, paginated,' immediately establishing the specific verb (list), resource (workouts), ordering, and pagination. It further distinguishes itself by explicitly stating its use case: 'Use this to discover workout ids; fetch a single full record with hevy_get_workout, or just the count with hevy_get_workout_count,' differentiating it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (to discover workout ids) and when to use alternatives (hevy_get_workout, hevy_get_workout_count). It also provides a crucial constraint: 'pageSize is 1-10 (Hevy returns 400 for >10),' guiding the agent on parameter limits. No misleading advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![hevy-mcp MCP server](https://glama.ai/mcp/servers/diecoscai/hevy-mcp/badges/card.svg)](https://glama.ai/mcp/servers/diecoscai/hevy-mcp)

Score Badge

Copy to your README.md:

[![hevy-mcp MCP server](https://glama.ai/mcp/servers/diecoscai/hevy-mcp/badges/score.svg)](https://glama.ai/mcp/servers/diecoscai/hevy-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/diecoscai/hevy-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server