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., "@btwb-mcp log my 1RM deadlift at 315 lbs today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An unofficial MCP server that lets an LLM search BTWB's movement library, log CrossFit/weightlifting/gymnastics results, and pull your full training history for Beyond the Whiteboard (BTWB) - straight from a chat, no copy-pasting between apps.
BTWB has no public API. This server calls the same internal JSON/form endpoints the BTWB web app itself uses, found by inspecting its network traffic. It authenticates with a copied browser session cookie rather than a real API key.
This is unofficial and unsupported by BTWB. It can break if they change their app, and your session cookie will periodically expire and need refreshing. Use it for personal automation only.
This project calls BTWB's internal, undocumented endpoints rather than a published API, using your own logged-in session cookie in place of an API key. It isn't affiliated with, endorsed by, or supported by BTWB, LLC. Using it may be subject to BTWB's own Terms of Service - review those and use this at your own discretion and risk. Provided as-is, with no warranty (see LICENSE).
Related MCP server: Gym Coach MCP Server
search_movement(term) - search BTWB's movement library, returns {id, name, modality, posting_trait} matches.
log_workout(movementId, movementName, reps, weight, weightUnit, performedDate, notes) - logs a single-movement result (e.g. a 1RM). Always posts with Privacy: Only Me - this is hardcoded in src/btwb-client.js and is not an exposed parameter, on purpose.
log_rounds_workout(workoutId, workoutSlug, memberId, sections, totalTimeSeconds, performedDate, rxd, notes, trackEventId) - logs a multi-movement "rounds" result (e.g. a For Time WOD with several movements per round). Only "For Time" / total-time scoring is supported. Always posts with Privacy: Only Me, same as log_workout.
get_movement_history(memberId, movementId, movementSlug, days) - pulls the full logged history for a movement over a date range: every individual set (date, reps, weight), not just PRs, plus a computed "Potential Max" trend line.
get_workout_session(sessionId) - fetches details of an already-logged result by its session ID.
delete_workout_session(sessionId) - permanently deletes an already-logged result by its session ID. No undo.
refresh_session_cookie() - manually re-authenticates and replaces the stored session cookie. Every other tool already does this automatically on an expired session (see "Automatic cookie refresh" below) - this is mainly for testing your setup or forcing an early refresh.
npm installLog into beyondthewhiteboard.com in your browser.
Open DevTools → Network tab, reload the page.
Click any request to beyondthewhiteboard.com.
Copy the full value of the Cookie request header.
This cookie is tied to your login session. If tools start failing with a CSRF/session error, it has expired - repeat these steps for a fresh one.
cp .env.example .env
# paste your cookie into .envOr export it directly:
export BTWB_SESSION_COOKIE="your_cookie_here"Add to your .mcp.json (project-level or global):
{
"mcpServers": {
"btwb": {
"command": "node",
"args": ["/absolute/path/to/btwb-mcp/src/index.js"],
"env": {
"BTWB_SESSION_COOKIE": "your_cookie_here"
}
}
}
}Or via the CLI:
claude mcp add btwb --env BTWB_SESSION_COOKIE="your_cookie_here" -- node /absolute/path/to/btwb-mcp/src/index.jsBy default, when your session cookie expires you refresh it by hand (repeat step 2). Optionally, you can let the server re-authenticate for you automatically whenever it detects an expired session - every tool call transparently retries once through a fresh login if needed, so you never have to touch DevTools again. This has been verified working end-to-end (login → fresh cookie → Keychain update → live authenticated request).
This requires storing your actual BTWB password (not just a session cookie) in Keychain. Weigh that before opting in - see the caveats below.
Store your BTWB password in Keychain (run this yourself in a terminal - never paste your password into a chat/AI session):
security add-generic-password -a "$USER" -s "btwb-password" -A -w-w with nothing after it makes security prompt for the password on a separate line with hidden input - it's never part of the command itself, so it's never echoed and never saved to shell history. (Prefer a GUI? Keychain Access.app → File → New Password Item → name btwb-password, account = your Mac username, works identically.)
Note: -a "$USER" is just the Keychain lookup key the code uses internally (your Mac account name) - it isn't your BTWB login and doesn't need to match your email.
Set BTWB_EMAIL to your BTWB login email (this one isn't sensitive on its own, unlike the password). Since GUI-launched MCP clients don't source your shell profile, the reliable place is your .mcp.json's env block, alongside the cookie:
{
"mcpServers": {
"btwb": {
"command": "node",
"args": ["/absolute/path/to/btwb-mcp/src/index.js"],
"env": {
"BTWB_EMAIL": "you@example.com"
}
}
}
}(.env or export BTWB_EMAIL=... also work for terminal-launched sessions.)
Restart the MCP server. refresh_session_cookie (or any other tool, automatically, whenever it detects an expired session) will now sign in with those credentials and overwrite the stored session cookie.
Caveats:
This stores a second, more sensitive secret (your actual login password) in Keychain, not just a session token.
It depends on BTWB's /signin → /session login form staying script-friendly. If BTWB ever adds a CAPTCHA or 2FA step, automatic refresh will start failing (with a clear error, not silently) and you'll fall back to the manual method.
Don't want this? Just skip this step - everything else works exactly as before, you'll just refresh the cookie by hand when it expires.
Every entry this server logs is posted with Privacy: Only Me, hardcoded in the client, not passed as a parameter. If you ever need a differently-scoped post, do it by hand in the BTWB app rather than changing this server's default.
Documented in commit history / session notes: found by watching Network tab traffic in a real logged-in browser session while performing each action (searching a movement, submitting the "Log Result" form, viewing a movement's PR page), then reading the resulting request URLs and the log form's actual field names directly out of the page DOM.
Search: GET /exercises/autocomplete_name.json?posting_trait=true&term={term}
Log (single movement): POST /workouts/logger (form-encoded, CSRF-protected, workout_session[definition] JSON)
Log (multi-movement/rounds): POST /workouts/{workoutId}-{slug}/workout_sessions (form-encoded, CSRF-protected, workout_session[uiobject] JSON - a different field name and shape than the single-movement flow)
History: GET /members/{memberId}/movements/{movementId}-{slug}/vmax?d={seconds}
Single session detail: GET /workout_sessions/{id} (HTML scrape - no JSON endpoint)
Delete: DELETE /workout_sessions/{id} (CSRF-protected, same endpoint as the app's own "Delete" UJS links)
Sign in (for automatic cookie refresh): GET /signin (pre-login session cookie + CSRF token) then POST /session (form-encoded: login, password, authenticity_token, remember_me)
Bug reports and PRs are welcome - see CONTRIBUTING.md for how this project is tested (there's no automated test suite) and what to include in a report.
Found a security issue (e.g. a way this could leak your session cookie)? See SECURITY.md for how to report it privately.
Permanently delete an already-logged BTWB result by its session ID. This cannot be undone - BTWB has no trash/undo for deleted sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | The workout_sessions ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it does so well: it explicitly warns the deletion is permanent and that BTWB has no trash/undo. This is exactly the irreversibility disclosure an agent needs before invoking a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, zero waste. The permanence warning is front-loaded as the consequence and the no-undo fact immediately follows.
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 single-parameter destructive tool with no output schema, the description covers the critical behavior (irreversibility), the target (logged session by ID), and the scope (session-level). Nothing an agent needs is missing.
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% (sessionId documented as 'The workout_sessions ID to delete'), so the baseline is 3. The description adds the constraint that the session must be an already-logged result, slightly exceeding the schema's generic wording.
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?
States a specific verb (permanently delete) and resource (an already-logged BTWB result), and identifies it by session ID. The 'permanently' qualifier distinguishes it sharply from siblings like get_workout_session or refresh_session_cookie.
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?
Clearly conveys this is for an already-logged result and implies the destructive context via 'permanently' and 'cannot be undone'. No explicit alternative named, but the destructive framing makes the when-to-use condition obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full logged history for a movement over a date range - every individual set (date, reps, weight), not just PRs - plus a computed 'Potential Max' trend line. Requires the BTWB member ID and the movement's numeric ID plus its URL slug (e.g. movementId 35, movementSlug 'deadlift' for beyondthewhiteboard.com/.../35-deadlift).
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | How many days of history to look back | |
| memberId | Yes | BTWB member/profile ID | |
| movementId | Yes | Movement ID | |
| movementSlug | Yes | URL slug for the movement, e.g. 'deadlift' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior: the return content (every individual set with date, reps, weight) plus a computed 'Potential Max' trend line. It also surfaces a non-obvious operational requirement that the movement must be identified by both numeric ID and URL slug, which goes beyond a plain read/write characterization.
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?
Front-loaded with the core purpose before the requirement and example details, and there is essentially no filler. It is slightly dense in the second sentence, but every clause earns its place by clarifying the identifier pair.
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?
No output schema exists, so the description correctly covers what comes back (sets plus the computed trend). It also documents the three required parameters and their composite nature; only minor omissions remain, such as behavior when history is empty or the effect of the days window rather than the default.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so a 3 is the baseline, but the description adds real value: it explains the composite requirement relationship between movementId and movementSlug and gives concrete example values (35, 'deadlift'). This is meaning the schema does not convey on its own.
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?
States a specific verb and resource (get the full logged history for a movement) and sharpens scope by contrasting it with what it is not: 'every individual set ... not just PRs'. The contrast lets an agent distinguish it from a summarization or PR-only tool without opening the schema.
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?
Usage is implied rather than stated: it tells you the prerequisites (member ID plus movement numeric ID and slug) but never names when to pick this over search_movement or another sibling. An agent can infer 'fetch history for a known movement', but there is no explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full details of one already-logged BTWB result by its session ID (the number in a beyondthewhiteboard.com/workout_sessions/{id} URL): workout name, performed date/time, the movements/sets, the result/score, and level/WOD-rank stats. There's no search-by-date endpoint yet - you need the session ID already (e.g. from a URL, or from log_workout's redirectedTo field).
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | The workout_sessions ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read-only lookup of an existing logged result, but does not disclose authentication requirements, whether the session must belong to the caller, error behavior for unknown IDs, or rate limits. It is adequate but leaves real behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the core action plus the ID requirement are front-loaded before the caveat about the missing search endpoint. Every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, no output schema, and no nested structures, the description is complete for the task: it names the required input, how to get it, and what the response contains. Nothing needed to invoke this correctly is missing.
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% and the single parameter is documented, so the baseline is 3. The description goes beyond the schema by explaining where the session ID originates (the numeric segment in a beyondthewhiteboard.com/workout_sessions/{id} URL) and where to obtain it programmatically (log_workout's redirectedTo field), adding genuinely useful 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?
States a specific verb ('Get') and resource ('full details of one already-logged BTWB result'), and enumerates the returned content: workout name, date/time, movements/sets, result/score, and rank stats. It is clearly distinguishable from siblings like log_workout or delete_workout_session, which mutate or create rather than read a single session.
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 the precondition ('you need the session ID already') and the reason ('There's no search-by-date endpoint yet'), and names concrete sources for that ID: a workout_sessions URL or log_workout's redirectedTo field. This tells the agent both when to use this tool and how to satisfy its input, which is unusually strong routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log a multi-movement 'rounds' result (e.g. a For Time WOD with several movements per round) to BTWB - as opposed to log_workout, which only handles a single movement. Only 'For Time' workouts scored by total time are supported (other scoring types like AMRAP/total-reps are untested). workoutId/workoutSlug come from the workout's URL (beyondthewhiteboard.com/workouts/{workoutId}-{workoutSlug}/...). Every entry logged through this tool is always posted with Privacy: Only Me - this is hardcoded and cannot be overridden.
| Name | Required | Description | Default |
|---|---|---|---|
| rxd | Yes | true = As Prescribed (Rx'd), false = Modified/scaled | |
| notes | No | Optional notes for the entry | |
| memberId | Yes | BTWB member/profile ID the result is logged under | |
| sections | Yes | Ordered list of round groups making up the workout, e.g. a single buy-in round followed by N rounds of several movements. | |
| workoutId | Yes | Numeric workout ID from the workout's URL | |
| workoutSlug | Yes | URL slug from the workout's URL, e.g. 'ft-rows-9x-toes-to-bars-power-cleans-and-wall-balls' | |
| trackEventId | No | Optional track_event ID to link this result to a scheduled/prescribed WOD (from get_workout_session or the workout's tracks page URL). | |
| performedDate | Yes | Date performed, format YYYY-MM-DD | |
| totalTimeSeconds | Yes | Total elapsed time in seconds (e.g. hit a 36:00 time cap -> 2160) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses a significant non-obvious behavior: 'Every entry logged through this tool is always posted with Privacy: Only Me - this is hardcoded and cannot be overridden.' That is exactly the kind of side effect an agent must know before writing. Gaps remain around auth requirements, error/failure behavior, and whether results are retrievable after logging.
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?
Front-loaded with the core action and the sibling contrast in the first sentence; the remaining sentences each carry a distinct constraint (supported scoring type, ID derivation, hardcoded privacy). Dense with parentheticals but no filler sentences.
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 9-parameter write tool with no annotations and no output schema, this covers purpose, routing, scoring-type limits, ID provenance, and the privacy side effect. Absent details are the response shape (no confirmation of a created entry ID) and failure/permission behavior, which are minor for this 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 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the composite workoutId/workoutSlug URL pattern, gives a concrete units example for totalTimeSeconds (36:00 cap -> 2160), and clarifies that 'sections' models an ordered buy-in-plus-rounds structure. It stops short of explaining edge cases like partial rounds or time-cap semantics.
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?
States a specific verb and resource ('Log a multi-movement rounds result ... to BTWB') and immediately differentiates from the sibling log_workout by scoping ('as opposed to log_workout, which only handles a single movement'). An agent can route between the two logging tools without opening either schema.
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 gives the selection condition against the alternative (multi-movement rounds vs single movement), plus a hard exclusion ('Only For Time workouts scored by total time are supported; AMRAP/total-reps are untested'). It also says where workoutId/workoutSlug come from, which is prerequisite info for calling it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log a single-movement result (e.g. a 1-rep max) to BTWB. Every entry logged through this tool is always posted with Privacy: Only Me - this is hardcoded and cannot be overridden.
| Name | Required | Description | Default |
|---|---|---|---|
| reps | Yes | Number of reps performed | |
| notes | No | Optional notes for the entry | |
| weight | Yes | Weight lifted | |
| movementId | Yes | Movement ID from search_movement | |
| weightUnit | No | lbs | |
| movementName | Yes | Movement name, should match the search_movement result | |
| performedDate | Yes | Date performed, format YYYY-MM-DD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden, and it discloses a genuinely non-obvious trait: entries are always posted with Privacy 'Only Me' and this is hardcoded/not overridable. That is exactly the kind of side effect an agent must know before writing data. It stops short of covering auth requirements, duplicate handling, or what the call returns.
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 filler: purpose first, then the critical hardcoded-privacy constraint. Nothing is redundant or buried.
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 7-parameter write tool with 5 required fields, no annotations, and no output schema, the definition covers purpose and the privacy side effect but omits permissions/auth requirements and any indication of return value or failure behavior. Adequate minimum, with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 86%, so the parameters are already well documented (reps, weight, dates, movementId source). The description adds no parameter-level detail beyond framing the typical case as a 1-rep max, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Log') and resource ('a single-movement result ... to BTWB'), with a concrete example (1-rep max). The 'single-movement' qualifier implicitly separates it from log_rounds_workout, but the sibling is never named, so differentiation is left to inference.
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?
Usage is implied by 'single-movement result' and the 1-rep max example, which points an agent away from the rounds-based logger. However, there is no explicit when-not-to-use, no alternative named, and no prerequisite stated (e.g. that movementId must be obtained via search_movement, which only appears in the schema).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manually re-authenticate to BTWB and replace the stored session cookie with a fresh one. Every other tool already does this automatically when it detects an expired session, so you normally don't need to call this directly - it's mainly useful to proactively refresh, or to test that BTWB_EMAIL and the Keychain-stored password are set up correctly. Requires BTWB_EMAIL and a password stored in Keychain (service: btwb-password) - see README "Automatic cookie refresh".
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does well: it discloses the side effect (the stored cookie is replaced), the required credentials (BTWB_EMAIL plus a Keychain password under service btwb-password), and the implicit auth/network dependency. It stops short of describing failure behavior or whether old sessions are invalidated, so it is strong 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the action and immediately followed by the 'you usually don't need this' caveat. The credential detail is necessary; the README pointer is slightly expendable but reasonable for a rare maintenance tool.
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 zero-parameter, no-output-schema tool with no annotations, the description covers purpose, prerequisites, side effects, and when to invoke. The only minor gap is that it never says what a successful or failed refresh looks like to the caller.
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 tool takes no parameters, so the schema carries no semantics to supplement and the baseline is 4. The description usefully points at the external inputs that actually matter (environment variable and Keychain service name), which is the closest analogue to parameter documentation here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: re-authenticate to BTWB and replace the stored session cookie. It also distinguishes itself from the rest of the toolset by noting every other tool refreshes automatically, so an agent can tell it is an out-of-band maintenance action rather than a normal data operation.
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?
It explicitly says you normally don't need to call this directly, then names the two legitimate cases (proactive refresh, verifying credential setup). That is an explicit when-to-use plus an effective default of don't-call, which is exactly what the field asks for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search BTWB's movement library by name (e.g. 'Deadlift', 'Squat Clean'). Returns matching movements with their numeric IDs, which log_workout and get_movement_history both require.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Movement name or partial name to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description carries the disclosure burden and does state the return content (matching movements with numeric IDs). It does not cover matching behavior (exact vs partial), result limits, or what happens on no match, which are minor for a read-only lookup.
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 tight sentences with the purpose and examples front-loaded and the downstream dependency stated last. No filler.
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 single-parameter search with no output schema, the description supplies what the agent needs (purpose, example inputs, returned IDs). Only edge-case behavior such as no-match returns or result caps is absent.
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 baseline is 3, but the description adds concrete example values ('Deadlift', 'Squat Clean') that clarify search granularity beyond the schema's generic 'Movement name or partial name'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Search) and resource (BTWB's movement library) plus the scoping dimension (by name), with concrete example terms. The mention that results feed log_workout and get_movement_history makes its role distinct from those write/history 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?
Gives clear context for when the tool is needed: it is the prerequisite lookup for log_workout and get_movement_history because they require numeric IDs. There is no explicit exclusion or named alternative, but no competing search tool exists among the siblings.
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.0.0delete_workout_sessionget_movement_historyget_workout_sessionlog_rounds_workoutlog_workoutrefresh_session_cookiesearch_movementScored across 7 tools
Each tool targets a distinct resource and action: search_movement (library lookup) vs get_movement_history (per-set history), log_workout (single movement) vs log_rounds_workout (multi-movement rounds), get_workout_session (read) vs delete_workout_session (remove), plus a standalone auth utility. Descriptions proactively clarify overlaps, e.g. log_rounds_workout explicitly contrasts itself with log_workout.
All seven tools use consistent snake_case verb_noun phrasing (search_movement, log_workout, get_workout_session, delete_workout_session, refresh_session_cookie). No style mixing or vague verb-only names.
Seven tools is well-scoped for a workout-logging and movement-data integration; each tool earns its place with a clear role and no redundant entries.
The surface covers search, log (two variants), read, and delete, but has no update/edit for an already-logged result, and get_workout_session requires a known session ID with no search-by-date or list-sessions tool. Discovery of existing sessions/workouts is thus a notable gap.
Create Hevy routines and analyze your training from chat. Unofficial; BYO Hevy PRO API key.
Manage fitness coaching clients, workouts, programs, chats and funnels from your assistant.
Chat forgets your workouts. AIm remembers them for Claude and ChatGPT: sets, weights, 1RM, volume.
Log workouts and meals by telling your AI. 873 exercises, muscle diagrams, food lookup.
