Skip to main content
Glama

AIm Workout Journal

by com.aim-journal
OverviewDiscussionsAdmin

Add or update a goal

upsert_goal
Destructive

Create or update a training goal (pass id to update). target.goal_type selects the shape: milestone (point target — exercise_id+value, or bodyweight+baseline_value), weekly_volume (muscle+band: mev|mev_mav|mav — "train X at least at MEV every week"), trend (exercise_id+metric, no value — "just keep it climbing", no fixed finish line), maintenance (baseline_value+tolerance_pct, exercise_id and/or muscle optional, unset means total session volume — "don't lose ground"), or omit goal_type for a plain process goal (metric=sessions_per_week).

Any exercise_id must be an id from the user's catalog (list_exercises; new ones via upsert_exercise): unknown ids are rejected, and a synonymous duplicate would split the exercise's history. review_date is the goal's scheduled check-in date.

featured=true makes this the ONE goal on the app's featured-goal card and automatically un-features any other active goal. The server rejects featured on a frequency goal; those live in the adherence widget only. A sessions_per_week goal and the profile's training_days_per_week are one number: writing either sets both.

Goal succession is two records: the earlier goal with status=achieved (never featured, which the server enforces) and the next goal with supersedes_goal_id=<earlier goal's id>. The user also sets and closes goals in the app (source=user); a goal they set is theirs, and nothing changes a goal automatically. Activity goals (activity_days_per_week) are set in the app only and read in get_coaching_context.activities.

Coach-proposed goals carry ratified=false until the user agrees. Goals are not deleted: status=revised/abandoned/achieved supersedes them, so history survives.

Input Schema

NameRequiredDescriptionDefault
goalYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / goal / properties / target / anyOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "band": {
-        "anyOf": [
-          {
-            "description": "weekly_volume's threshold: mev = at least MEV; mev_mav = within the MEV-MAV band;\nmav = at or above MAV.",
-            "enum": [
-              "mev",
-              "mev_mav",
-              "mav"
-            ],
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "baseline_value": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "deadline": {
-        "anyOf": [
-          {
-            "format": "date",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "exercise_id": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "goal_type": {
-        "anyOf": [
-          {
-            "description": "How a goal is quantified/visualized (target.goal_type) — a different axis from GoalKind\n(which methodology section it maps to). Legacy goals with no goal_type infer one from\ntarget.metric via infer_goal_type() below, so this is purely additive.",
-            "enum": [
-              "milestone",
-              "weekly_volume",
-              "trend",
-              "maintenance",
-              "frequency"
-            ],
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "metric": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "muscle": {
-        "anyOf": [
-          {
-            "enum": [
-              "chest",
-              "upper_chest",
-              "lower_chest",
-              "lats",
-              "upper_back",
-              "traps",
-              "lower_traps",
-              "rhomboids",
-              "rear_delts",
-              "side_delts",
-              "front_delts",
-              "biceps",
-              "triceps",
-              "forearms",
-              "abs",
-              "obliques",
-              "lower_back",
-              "glutes",
-              "quads",
-              "hamstrings",
-              "adductors",
-              "abductors",
-              "calves",
-              "neck",
-              "rotator_cuff",
-              "full_body",
-              "other"
-            ],
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "tolerance_pct": {
-        "anyOf": [
-          {
-            "maximum": 100,
-            "minimum": 0,
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "unit": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "value": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "activity_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "band": {
+        "anyOf": [
+          {
+            "description": "weekly_volume's threshold: mev = at least MEV; mev_mav = within the MEV-MAV band;\nmav = at or above MAV.",
+            "enum": [
+              "mev",
+              "mev_mav",
+              "mav"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "baseline_value": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "deadline": {
+        "anyOf": [
+          {
+            "format": "date",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "direction": {
+        "anyOf": [
+          {
+            "enum": [
+              "at_least",
+              "at_most"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "exercise_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "goal_type": {
+        "anyOf": [
+          {
+            "description": "How a goal is quantified/visualized (target.goal_type) — a different axis from GoalKind\n(which methodology section it maps to). Legacy goals with no goal_type infer one from\ntarget.metric via infer_goal_type() below, so this is purely additive.",
+            "enum": [
+              "milestone",
+              "weekly_volume",
+              "trend",
+              "maintenance",
+              "frequency"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "metric": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "muscle": {
+        "anyOf": [
+          {
+            "enum": [
+              "chest",
+              "upper_chest",
+              "lower_chest",
+              "lats",
+              "upper_back",
+              "traps",
+              "lower_traps",
+              "rhomboids",
+              "rear_delts",
+              "side_delts",
+              "front_delts",
+              "biceps",
+              "triceps",
+              "forearms",
+              "abs",
+              "obliques",
+              "lower_back",
+              "glutes",
+              "quads",
+              "hamstrings",
+              "adductors",
+              "abductors",
+              "calves",
+              "neck",
+              "rotator_cuff",
+              "full_body",
+              "other"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "tolerance_pct": {
+        "anyOf": [
+          {
+            "maximum": 100,
+            "minimum": 0,
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "unit": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "value": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
  2. First observed

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Well beyond the annotations, it discloses consequential side effects: featured=true 'automatically un-features any other active goal', a sessions_per_week goal and training_days_per_week 'are one number: writing either sets both', and unknown exercise ids are rejected. It also clarifies that despite destructiveHint=true nothing is hard-deleted ('Goals are not deleted: status=revised/abandoned/achieved supersedes them'). The one missing piece is whether an update with an existing `id` is a full replace or a merge of the nested goal object — important for a non-idempotent upsert and left unstated.

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?

Front-loads the create-vs-update branch and the goal_type taxonomy before the edge rules, which is the right ordering. It is long (~200 words) and the parenthetical example quotes are chatty, but nearly every sentence carries a rule that cannot be inferred from annotations or schema; the trailing paragraphs on user-set goals, app-only activity goals, and ratified are the only parts that could be trimmed.

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?

An output schema exists, so return values need no explanation, and the description covers the hard parts of a 20-field nested object: goal_type shapes, succession via supersedes_goal_id plus status=achieved, the featured exclusivity rule, and the profile coupling. Gaps remain on the required `kind` field, allowed status transitions, and update-merge semantics, which matter for a mutation tool with destructiveHint=true.

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 description coverage is reported at 0%, so the description carries the burden, and it does map most of the consequential nested fields: which target keys each goal_type requires (exercise_id/value/baseline_value/tolerance_pct/muscle/band/metric), review_date, featured, ratified, supersedes_goal_id, source=user. It leaves unexplained the required `kind` enum (outcome/process/performance) and fields such as status, unit, direction, deadline, notes, and custom_fields, so it does not fully compensate for the coverage gap.

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?

Opens with a specific verb+resource ('Create or update a training goal') and immediately disambiguates the two modes ('pass `id` to update'), which is the key branch an agent needs. The rest of the first sentence narrows 'goal' to five concrete shapes via goal_type, so an agent can tell this apart from get_goals or update_coach_profile 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.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit selection rules per goal_type ('milestone (point target — exercise_id+value, or bodyweight+baseline_value)', weekly_volume, trend, maintenance, plain process metric=sessions_per_week) plus the default when goal_type is omitted. It also states real exclusions and routes elsewhere: activity goals are 'set in the app only and read in get_coaching_context.activities', exercise ids must come from list_exercises/upsert_exercise, and featured is rejected on frequency goals.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All AIm Workout Journal toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources