update_goal
UNIT INPUTS: value: pass the user's number unconverted; tool converts once before storage. alternate_unit: set the field's matching input_* companion; canonical_unit: omit companion. precedence: overrides instructions to convert manually.
Change, complete, pause, stop/end, reopen, or delete an existing goal. Call this tool directly for ordinary goal changes. It already loads the user's current goals and resolves a unique goal from goal_id or a natural-language goal_ref, so do NOT call list_goals first just to find an ID.
For edit, pass only the fields to change. For complete/pause/end/reopen/delete, no edit fields are required. If goal_ref genuinely matches multiple goals, this tool returns the candidates and changes nothing. Formal goal end/delete follows the existing Goals UI cancel lifecycle; standard-target end/pause turns that target off while delete removes it.
WEIGHT INPUTS: For a body_weight_target_lb standard target or body_comp metric lean_mass_lb, edit with target_value_lb. This alias is unit-aware; in-app calls use the preferred unit, while external calls use pounds unless input_weight_unit is set. Legacy generic target_value remains canonical pounds.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Concise title, inferred from the goal inputs. | |
| weeks | No | For weight_loss. Duration in weeks when target_date is not supplied. For body_comp. Duration in weeks when target_date is not supplied. | |
| action | Yes | What to do. 'end' when the user is stopping or canceling a goal; for a formal goal that follows the app's cancel behavior and removes it. | |
| metric | No | For consistency. What consistency behavior to track. Required on create. Set at create, not editable later. For body_comp. Body composition metric. Required on create. Set at create, not editable later. For nutrition. Legacy nutrition metric. | |
| goal_id | No | Formal goal ID, when known. | |
| goal_ref | No | Natural-language reference when no ID is known, e.g. "protein", "10K", "weight loss". This tool resolves it against current goals itself. | |
| new_name | No | For n1_experiment. Name for a new supplement when not using supplement_id. | |
| new_brand | No | For n1_experiment. Optional brand for a new supplement. | |
| race_date | No | For race. Race date in YYYY-MM-DD format. Required on create. | |
| start_date | No | YYYY-MM-DD. Default: today. | |
| start_value | No | For body_comp. Starting value when the goal begins. Required on create. Set at create, not editable later. | |
| target_date | No | For weight_loss. Target date in YYYY-MM-DD format. Use this when the user names a deadline. For body_comp. Target date in YYYY-MM-DD format. Use this when the user names a deadline. | |
| week_window | No | For consistency. How the week this goal is measured against is bounded: rolling = the last 7 days, sunday/monday = a calendar week that resets on that day. Default: rolling. | |
| start_1rm_lb | No | For strength. Estimated 1RM when the goal starts. Required on create. Set at create, not editable later. In lb, or kg with input_weight_unit set. See UNIT INPUTS. | |
| target_hours | No | For consistency. Nightly sleep target in hours. Required when metric is sleep_duration. | |
| target_value | No | For body_comp. Target body composition value. Required on create. For nutrition. Legacy nutrition target value. For standard targets, this is the numeric target value. | |
| exercise_name | No | For strength. Exercise name. Required on create. Set at create, not editable later. | |
| new_dose_unit | No | For n1_experiment. Dose unit for a new supplement. | |
| supplement_id | No | For n1_experiment. Existing supplement ID. Use either supplement_id or the new-supplement fields. | |
| target_1rm_lb | No | For strength. Target 1RM. Required on create. In lb, or kg with input_weight_unit set. See UNIT INPUTS. | |
| start_value_lb | No | Starting lean mass in body_comp. See WEIGHT INPUTS above. In lb, or kg with input_weight_unit set. See UNIT INPUTS. | |
| new_dose_amount | No | For n1_experiment. Dose amount for a new supplement. | |
| start_weight_lb | No | For weight_loss. Starting body weight. Required on create. Set at create, not editable later. In lb, or kg with input_weight_unit set. See UNIT INPUTS. | |
| target_per_week | No | For consistency. Target occurrences per week. Required on create. | |
| target_time_sec | No | For race. Target finish time in seconds. Required on create. | |
| target_value_lb | No | Weight goal target. See WEIGHT INPUTS above. In lb, or kg with input_weight_unit set. See UNIT INPUTS. | |
| target_weight_lb | No | For weight_loss. Target body weight. Required on create. In lb, or kg with input_weight_unit set. See UNIT INPUTS. | |
| input_weight_unit | No | Set to kg when the user gave kg for the _lb fields in this object. Omit when they are already lb. | |
| intervention_days | No | For n1_experiment. Intervention duration in days. | |
| baseline_direction | No | For n1_experiment. Use already logged previous 14 days or collect the next 14 days. | |
| target_distance_mi | No | For race. Target race distance. Required on create. In mi, or km with input_distance_unit set. See UNIT INPUTS. | |
| input_distance_unit | No | Set to km when the user gave km for the _mi fields in this object. Omit when they are already mi. | |
| acknowledged_warnings | No | Warning keys the user explicitly acknowledged after a guarded create attempt. Omit otherwise. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes | Human-readable result text returned by the tool. |