Skip to main content
Glama

Propose a plan revision

propose_plan_revision
Idempotent

Propose a changeset of several workouts or weeks against one training plan, for example rebuilding a week or shifting a block. For a single workout whose load should change, propose_workout_adjustment fits. Nothing changes until approve_plan_revision applies it; group changes then reach every member.

scope='athlete' (plan_instance_id + athlete_id) — each operation is one of:

  • {op:'adjust', workout_id, changes:{...}} — changes allows: workout_name, status ('scheduled' or 'skipped' only), workout_type, workout_sub_type, day, target_distance_in_meters, target_duration_in_seconds, target_pace, target_pace_zone, target_complete_date, content_blocks. Applied like a calendar edit: a new target_complete_date moves the session and its week.

  • {op:'add', workout:{...}, target_complete_date} — workout requires workout_name and allows: workout_type, workout_sub_type, day, target_distance_in_meters, target_duration_in_seconds, target_pace, target_pace_zone, content_blocks. target_complete_date sits at the OPERATION level, not inside workout.

  • {op:'remove', workout_id}

scope='group' (plan_instance_id = group plan instance id; coach role and the group-training-plan feature required) also supports {op:'reschedule', workout_id, new_week, new_day}; group add requires workout_name, week (or week_number), day inside workout. Group adjust changes allows: workout_name, workout_description, workout_description_cards, workout_type, workout_sub_type, target_distance_in_meters, target_duration_in_seconds, content_blocks, session, is_group_workout, group_content, target_pace_zone, target_pace, day, attendance_enabled, attendance_rule, live_session_enabled, entry_kind, icon, clear_content_blocks (other keys are rejected).

Strength sessions: a strength workout with a structured session (sets, exercises, loads) derives its duration from that session and cannot carry content_blocks; to change its volume, edit the session in the workout editor (athlete adjust rejects a different target_duration_in_seconds). Changing workout_type away from strength drops the session.

Rules: target_complete_date is an epoch-SECONDS integer (milliseconds are accepted and auto-converted). An athlete workout does not accept week or status: week is derived from target_complete_date and status is system-managed. Completed workouts cannot be adjusted, moved or removed. An athlete with a coach may propose, but their coach approves. Re-proposing an already applied changeset is refused, and re-proposing a pending one returns the same revision. Example athlete add: {op:'add', workout:{workout_name:'Easy Run', workout_type:'run', target_distance_in_meters:6000, target_pace_zone:'Z1'}, target_complete_date:1781568000}. Workout reads return content_blocks as rows whose columns content_block_fields names (an interval's blocks column holds its nested steps as rows in the same columns), and a session shared by several rows as session_ref into session_definitions. As arguments, content_blocks is a list of block objects and session a session object.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "scope": "<scope>",
      "plan_instance_id": "<plan_instance_id>",
      "operations": "<operations>",
      "reason": "<reason>"
    },
    "name": "propose_plan_revision"
  }
}

Input Schema

NameRequiredDescriptionDefault
notesNoOptional notes for the reviewer.
scopeYesathlete: one athlete's plan; group: a group plan.
reasonYesWhy the plan changes; the reviewer reads it.
athlete_idNoThe athlete whose plan changes; athlete scope only.
operationsYesThe changes, applied in order on approval (1-50).
plan_instance_idYesathlete scope: plan_instance_id from get_training_plan or get_week_workouts; group scope: group_plan_instance_id from list_group_plans.

Output Schema

NameRequiredDescriptionDefault
idNo
kindNo
errorNo
notesNo
scopeNo
org_idNo
reasonNo
sourceNo
statusNo
messageNo
privacyNoPresent when the athlete's settings withhold data.
coach_idNo
warningsNo
next_stepNoWhat can be done next, for example after a failure.
applied_atNo
athlete_idNo
created_atNoEpoch milliseconds.
operationsNo
updated_atNo
apply_errorNo
next_cursorNoReads the next page; null on the last page.
reason_codeNo
reviewed_atNo
revision_idNo
total_weeksNo
user_contentNoFields in this result that people wrote.
applied_at_isoNoThe epoch field beside it as a UTC instant; the local day can differ.
coach_feedbackNo
created_at_isoNoThe epoch field beside it as a UTC instant; the local day can differ.
updated_at_isoNoThe epoch field beside it as a UTC instant; the local day can differ.
weeks_returnedNo
reviewed_at_isoNoThe epoch field beside it as a UTC instant; the local day can differ.
plan_instance_idNo
truncated_fieldsNoLists cut to fit one response: rows returned and total.
generated_contentNoFields in this result that NexRex's AI wrote.
operation_resultsNo
session_definitionsNoSessions that several rows of this result share by session_ref.
content_block_fieldsNoColumn names of every content_blocks row, nested blocks rows included.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedOutput schema / $defs / Activity / properties / content_blocks / anyOf
      Previous value: -[
      -  {
      -    "items": {
      -      "items": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "integer"
      -          },
      -          {
      -            "type": "number"
      -          },
      -          {
      -            "type": "boolean"
      -          },
      -          {
      -            "items": {
      -              "anyOf": [
      -                {
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "integer"
      -                },
      -                {
      -                  "type": "number"
      -                },
      -                {
      -                  "type": "boolean"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ]
      -            },
      -            "type": "array"
      -          },
      -          {
      -            "$ref": "#/$defs/LocalizedText"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "type": "array"
      -    },
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "items": {
      +      "items": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "integer"
      +          },
      +          {
      +            "type": "number"
      +          },
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "items": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "integer"
      +                },
      +                {
      +                  "type": "number"
      +                },
      +                {
      +                  "type": "boolean"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "type": "array"
      +          },
      +          {
      +            "$ref": "#/$defs/LocalizedText"
      +          },
      +          {
      +            "items": {
      +              "type": "array"
      +            },
      +            "type": "array"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "type": "array"
      +    },
      +    "type": "array"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / $defs / Activity / properties / content_blocks / description
      Previous value: -"Interval rows; each row's values follow content_block_fields."New value: +"Workout steps as rows whose values follow content_block_fields; an interval's blocks value is its nested steps as rows in the same columns."
    • changedOutput schema / properties / content_block_fields / description
      Previous value: -"Column names of every content_blocks row."New value: +"Column names of every content_blocks row, nested blocks rows included."
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description adds substantial context beyond that — nothing mutates until approval, group changes propagate to every member, completed workouts are immutable, re-proposing an applied changeset is refused while re-proposing a pending one returns the same revision (matching idempotentHint). It also discloses strength-session constraints and that changing workout_type away from strength drops the session.

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 purpose and the alternative before the operational detail, and uses scannable bullets rather than prose. It is long, and the closing paragraph on content_blocks row shape and session_ref describes read formats already covered by the output schema, which is mild duplication rather than wasted space.

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 6-parameter, 50-item, multi-op mutation tool, everything an agent needs is present: scope-dependent operation grammars, epoch-seconds format with millisecond auto-conversion, immutability rules, approval flow, and a worked example. The existence of an output schema means the brief return-shape note is sufficient without further detail.

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 coverage is 100%, but the description adds meaning the schema cannot: the per-op shapes for adjust/add/remove/reschedule, the exact allowed keys inside `changes` per scope, that target_complete_date sits at the operation level rather than inside `workout` for adds, that group add requires week/week_number inside workout, and which keys are rejected for group adjust.

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?

States a specific verb and resource — 'propose a changeset of several workouts or weeks against one training plan' — with concrete examples of that scope (rebuilding a week, shifting a block). It explicitly names the sibling it is not (propose_workout_adjustment for a single workout's load), so the agent can route 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.

Usage Guidelines5/5

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

Gives explicit when-to-use and when-not-to-use guidance: multiple-workout/week changes here versus propose_workout_adjustment for a single load change. It also states the approval path ('nothing changes until approve_plan_revision applies it'), the group-role prerequisite, and the coach-approval case ('an athlete with a coach may propose, but their coach approves').

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources