AIm

Add or update a goal

upsert_goal

Create or update a training goal with a target, deadline, and review date. Supports milestone, weekly volume, trend, maintenance, and frequency goal types.

Instructions

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 (check list_exercises; create via upsert_exercise first if genuinely new) — unknown ids are rejected, and a synonymous duplicate would split the exercise's history. Set review_date on every ratified goal (~4 weeks out, or the deadline if sooner) so check-ins have an anchor; calibrate milestone targets ~5-10% beyond the user's current number for an 8-12 week horizon.

Set featured=true on the ONE goal that should be the user's single featured goal in the app — this automatically un-features any other active goal. Never set featured on a frequency goal (the server rejects it); those live in the adherence widget only, never the featured-goal card.

When a milestone looks achieved, don't silently transition it — tell the user and ask whether to keep maintaining that level or set a new target, then call upsert_goal twice: mark the old goal status=achieved (also set featured=false, though the server defends this too) and create the new goal with supersedes_goal_id=<old goal's id> and featured=true. This is a decision the user makes with you in conversation, never something the app decides on its own.

Coach-proposed goals carry ratified=false until the user explicitly agrees. Never delete goals — supersede with status=revised/abandoned/achieved so history survives.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`goal`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.2.1Sep 14, 2026

TDQS

A5/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important side effects: setting featured=true automatically un-features any other active goal, the server rejects featured frequency goals, and unknown exercise IDs are rejected to avoid splitting exercise history. It also outlines the non-silent milestone transition workflow and the policy that goals are superseded rather than deleted. No contradiction with 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 long, but every section earns its place given the tool's complexity: create-vs-update distinction, goal_type shapes, validation rules, featured-goal side effects, lifecycle transitions, and coach-proposal handling. It is front-loaded with the most essential action and structured so an agent can quickly find the relevant constraint.

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 complex upsert tool with a nested target object, the description is complete: it covers field-level semantics, allowed values, server-enforced constraints, side effects, workflow sequencing, and domain heuristics like review_date cadence and milestone calibration. An output schema exists, so the lack of explicit return-value discussion is not a gap. An agent has enough context to invoke this tool correctly without additional probing.

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?

Despite 0% schema description coverage, the description thoroughly explains the nested goal.target semantics: each goal_type variant (milestone, weekly_volume, trend, maintenance, frequency, and omitted goal_type), which fields each requires, and what values mean (e.g., mev|mev_mav|mav bands, tolerance_pct, supersedes_goal_id, featured, ratified). It adds meaning far beyond the raw schema enum 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 opens with a specific verb+resource: 'Create or update a training goal (pass `id` to update).' It clearly differentiates the tool from siblings like get_goals and upsert_exercise, and further disambiguates the many goal shapes via target.goal_type. The purpose is unmistakable and immediately actionable.

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 gives explicit when-to-use and when-not-to-use guidance: it tells the agent to check list_exercises and use upsert_exercise for genuinely new exercises, never to set featured on frequency goals, never to delete goals, and to call upsert_goal twice when transitioning an achieved milestone. It also specifies when to set review_date, featured, ratified, and supersedes_goal_id, making correct invocation conditions concrete.

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