@trainheroic-unofficial/athlete-mcp 3.2.0 → 3.3.0

package/dist/server.mjs

@@ -24,12 +24,14 @@ const numLikeOrNull = z.union([
 	z.string(),
 	z.null()
 ]);
-z.looseObject({
+/** `/user/simple` — the identity + tenant key (numeric `id`) for any logged-in account. */
+const userSimpleSchema = z.looseObject({
 	id: intLike$1,
 	roles: z.array(z.string()).optional(),
 	org_id: intLikeOrNull$1.optional()
 });
-z.looseObject({
+/** `/v5/athleteProfile/summary` — lifetime training totals. Needs `use_metric` in the query. */
+const athleteProfileSummarySchema = z.looseObject({
 	reps_sum: z.number().optional(),
 	volume_sum: z.number().optional(),
 	sessions_count: z.number().optional(),
@@ -37,7 +39,8 @@ z.looseObject({
 	last_logged_date: z.string().optional(),
 	duration_hours: z.number().optional()
 });
-z.looseObject({
+/** `/v5/users/{id}` — the detailed athlete profile (only the fields we surface). */
+const athleteUserSchema = z.looseObject({
 	id: intLike$1,
 	email: z.string().optional(),
 	name_first: z.string().optional(),
@@ -47,7 +50,8 @@ z.looseObject({
 	date_of_birth: z.string().optional(),
 	use_metric: z.boolean().optional()
 });
-z.looseObject({ id: intLike$1 });
+/** `/1.0/athlete/prefs` — notification + display preference flags. */
+const athletePrefsSchema = z.looseObject({ id: intLike$1 });
 /** One item of `/2.0/athlete/workingMax` — the athlete's working max for an exercise. */
 const athleteWorkingMaxSchema = z.looseObject({
 	exercise_id: intLike$1,
@@ -57,7 +61,7 @@ const athleteWorkingMaxSchema = z.looseObject({
 	type_suffix: z.string().optional(),
 	working_max_id: intLikeOrNull$1.optional()
 });
-z.array(athleteWorkingMaxSchema);
+const athleteWorkingMaxListSchema = z.array(athleteWorkingMaxSchema);
 /** One item of `/v5/users/exercises/history` — an exercise the athlete has logged. */
 const exerciseHistoryListItemSchema = z.looseObject({
 	id: intLike$1,
@@ -107,7 +111,8 @@ const liftPRSchema = z.looseObject({
 	isMetric: z.boolean().optional(),
 	description: z.string().optional()
 });
-z.looseObject({
+/** `/v5/exercises/{id}/history` — the per-exercise PRs + session history. */
+const exerciseHistoryDetailSchema = z.looseObject({
 	liftPRs: z.array(liftPRSchema).optional(),
 	singleParamPRs: z.array(z.unknown()).optional(),
 	history: z.array(historyEntrySchema).optional()
@@ -123,8 +128,9 @@ const personalRecordSchema = z.looseObject({
 	units: z.string().optional(),
 	isMetric: z.boolean().optional()
 });
-z.array(personalRecordSchema);
-z.looseObject({
+const personalRecordListSchema = z.array(personalRecordSchema);
+/** `/v5/exercises/{id}/stats` — last performance + PR for an exercise. Needs `date` in the query. */
+const exerciseStatsSchema = z.looseObject({
 	isLift: z.boolean().optional(),
 	lastPerformance: z.unknown().optional(),
 	personalRecord: z.unknown().optional()
@@ -144,7 +150,7 @@ const programWorkoutSchema = z.looseObject({
 	team_title: z.string().optional(),
 	summarizedSavedWorkout: z.unknown().optional()
 });
-z.array(programWorkoutSchema);
+const programWorkoutListSchema = z.array(programWorkoutSchema);
 /** A `YYYY-MM-DD` date argument. The single definition reused across athlete tool inputs. */
 const dateString = z.string().regex(/^\d{4}-\d{2}-\d{2}$/u, "expected YYYY-MM-DD");
 z.object({
@@ -251,6 +257,163 @@ const athleteSessionRemoveArgsSchema = z.object({
 	programWorkoutId: idArgSchema,
 	date: dateString
 });
+const presentedNullNumber = z.number().nullable();
+const presentedNullString = z.string().nullable();
+/** Flattened exercise within a presented workout: prescriptions, logged results, units. */
+const athleteWorkoutExerciseSchema = z.object({
+	exerciseId: presentedNullNumber,
+	title: z.string(),
+	instruction: presentedNullString,
+	units: z.array(presentedNullString),
+	prescribed: z.array(z.string()),
+	performed: z.array(z.string())
+});
+const athleteWorkoutBlockSchema = z.object({
+	order: z.number(),
+	title: presentedNullString,
+	instruction: presentedNullString,
+	isTest: z.boolean(),
+	exercises: z.array(athleteWorkoutExerciseSchema)
+});
+const athleteWorkoutViewSchema = z.object({
+	id: presentedNullNumber,
+	date: z.string(),
+	title: z.string(),
+	program: presentedNullString,
+	team: presentedNullString,
+	instruction: presentedNullString,
+	logged: z.boolean(),
+	personal: z.boolean(),
+	blocks: z.array(athleteWorkoutBlockSchema)
+});
+const athleteWorkoutSummarySchema = z.object({
+	id: presentedNullNumber,
+	date: z.string(),
+	title: z.string(),
+	program: presentedNullString,
+	team: presentedNullString,
+	logged: z.boolean(),
+	personal: z.boolean(),
+	exerciseCount: z.number().int().nonnegative(),
+	performedCount: z.number().int().nonnegative()
+});
+/** Presented views first so a summary/detail row cannot be swallowed by the loose raw list. */
+const athleteWorkoutsOutputSchema = z.union([
+	z.array(athleteWorkoutSummarySchema),
+	z.array(athleteWorkoutViewSchema),
+	programWorkoutListSchema
+]);
+const athleteProfileOutputSchema = z.looseObject({
+	summary: athleteProfileSummarySchema,
+	user: athleteUserSchema
+});
+const athleteExerciseCatalogOutputSchema = z.array(z.object({
+	id: z.union([z.number(), z.string()]),
+	title: z.string(),
+	isCircuit: z.boolean(),
+	units: z.array(presentedNullString)
+}));
+const coachAthleteExerciseSchema = z.object({
+	exerciseId: presentedNullNumber,
+	title: z.string(),
+	summary: presentedNullString,
+	completed: z.boolean()
+});
+const coachAthleteSessionSchema = z.object({
+	workoutId: presentedNullNumber,
+	savedWorkoutId: presentedNullNumber,
+	title: z.string(),
+	logged: z.boolean(),
+	completed: z.boolean(),
+	rpe: presentedNullNumber,
+	durationMin: presentedNullNumber,
+	notes: presentedNullString,
+	exercises: z.array(coachAthleteExerciseSchema)
+});
+z.object({
+	athleteId: presentedNullNumber,
+	athleteName: presentedNullString,
+	year: z.number().int(),
+	month: z.number().int(),
+	sessions: z.array(coachAthleteSessionSchema)
+});
+const rosterActivityRowSchema = z.object({
+	athleteId: z.number(),
+	sessionsCount: presentedNullNumber,
+	firstLoggedDate: presentedNullString,
+	lastLoggedDate: presentedNullString,
+	totalReps: presentedNullNumber,
+	totalVolume: presentedNullNumber
+});
+const teamVolumeAthleteSchema = z.object({
+	athleteId: z.number(),
+	name: presentedNullString,
+	sessions: z.number(),
+	reps: z.number(),
+	volume: z.number(),
+	firstLoggedDate: presentedNullString,
+	lastLoggedDate: presentedNullString
+});
+z.object({
+	window: z.object({
+		start: z.string(),
+		end: z.string()
+	}),
+	athletes: z.array(teamVolumeAthleteSchema),
+	totals: z.object({
+		athletes: z.number(),
+		sessions: z.number(),
+		reps: z.number(),
+		volume: z.number()
+	})
+});
+z.array(rosterActivityRowSchema);
+const presentedExerciseSessionSchema = z.object({
+	date: z.string(),
+	abr: presentedNullString,
+	estimated1RM: presentedNullNumber,
+	sets: z.array(z.object({
+		setNumber: z.number(),
+		value: presentedNullString
+	}))
+});
+const presentedExerciseHistorySchema = z.object({
+	liftPRs: z.array(z.object({
+		description: presentedNullString,
+		reps: presentedNullNumber,
+		weight: presentedNullNumber,
+		units: presentedNullString,
+		date: presentedNullString
+	})),
+	sessions: z.array(presentedExerciseSessionSchema)
+});
+/** Presented history first so the loose raw detail schema cannot swallow it. */
+const exerciseHistoryOutputSchema = z.union([presentedExerciseHistorySchema, exerciseHistoryDetailSchema]);
+//#endregion
+//#region ../dto/src/exercise.ts
+/**
+* A row presented for display. The raw param-type codes are dropped and the fixed
+* measurement units are surfaced positionally in `units`, ordered by entry slot
+* (param 1, then param 2). Positional, not semantic: param 2 is not always the load
+* — some exercises reverse the slots — so the units are not labelled by role.
+*/
+const exerciseViewSchema = z.object({
+	id: z.number(),
+	title: z.string(),
+	can_edit: z.number(),
+	user_id: z.number().nullable(),
+	use_count: z.number(),
+	units: z.array(z.string().nullable())
+});
+z.looseObject({
+	id: idSchema,
+	title: z.string(),
+	units: z.array(z.string().nullable())
+});
+z.object({
+	match: exerciseViewSchema.nullable(),
+	candidates: z.array(exerciseViewSchema)
+});
 z.looseObject({
 	title: z.string().min(1),
 	param_1_type: z.number().optional(),
@@ -305,6 +468,198 @@ z.object({
 	pub_timezone: z.string().optional()
 }).refine((v) => v.pub_enabled !== void 0 || v.pub_days !== void 0 || v.pub_time !== void 0 || v.pub_timezone !== void 0, { message: "Provide at least one pub_* field" });
 //#endregion
+//#region ../dto/src/tool-output.ts
+const nullableNumber = z.number().nullable();
+const nullableString = z.string().nullable();
+const truncationMarkerSchema = z.looseObject({
+	field: z.string().optional(),
+	returned: z.number().int().nonnegative().optional(),
+	total: z.number().int().nonnegative(),
+	omitted: z.number().int().nonnegative(),
+	hint: z.string()
+});
+/** Dedicated budget-fallback envelope. Never the natural tool shape. */
+const truncatedOutputSchema = z.looseObject({
+	preview: z.string().optional(),
+	items: z.array(z.json()).optional(),
+	__truncated: truncationMarkerSchema
+});
+/**
+* Add the shared size-budget fallback to a tool's natural result shape.
+* Truncation is a dedicated `{ items|preview, __truncated }` envelope, so it cannot
+* validate as the natural object and drop the marker.
+*/
+function toolOutputSchema(schema) {
+	return z.union([truncatedOutputSchema, schema]);
+}
+/** Explicit passthrough for tools whose live API payload is not yet contracted. */
+const opaqueOutputSchema = toolOutputSchema(z.json());
+const logSetTargetOutputSchema = z.object({
+	date: z.string(),
+	workoutTitle: z.string(),
+	program: nullableString,
+	programId: nullableNumber,
+	team: nullableString,
+	teamId: nullableNumber,
+	savedWorkoutSetId: z.number(),
+	setTitle: nullableString,
+	exercises: z.array(z.object({
+		savedWorkoutSetExerciseId: z.number(),
+		title: z.string(),
+		units: z.array(nullableString),
+		prescribed: z.array(z.string()),
+		performed: z.array(z.string())
+	}))
+});
+const logTargetsOutputSchema = z.union([z.array(logSetTargetOutputSchema), programWorkoutListSchema]);
+z.object({
+	draft: z.literal(true),
+	note: z.string(),
+	would_POST: z.string(),
+	payload: z.json()
+});
+z.looseObject({
+	status: z.enum(["sent", "logged"]),
+	reference: z.string().optional(),
+	note: z.string()
+});
+z.looseObject({ removed: z.union([z.boolean(), z.number()]) });
+const athleteSessionRemovedOutputSchema = z.object({
+	removed: z.literal(true),
+	programWorkoutId: z.number(),
+	date: z.string()
+});
+z.object({
+	invited: z.literal(true),
+	teamId: z.number(),
+	result: z.json().optional()
+});
+const setLogOutputSchema = z.object({
+	savedWorkoutSetId: z.number(),
+	exercisesLogged: z.number().int().nonnegative(),
+	setCompleted: z.boolean()
+});
+const setPrescriptionOutputSchema = z.object({
+	savedWorkoutSetId: z.number(),
+	exercisesPrescribed: z.number().int().nonnegative()
+});
+const exerciseSwapOutputSchema = z.object({
+	savedWorkoutSetExerciseId: z.number(),
+	athleteId: nullableNumber,
+	newExerciseId: z.number(),
+	newExerciseTitle: nullableString,
+	originalTeamExerciseId: nullableNumber
+});
+const sessionLogSetOutputSchema = z.object({
+	savedWorkoutSetId: z.number(),
+	exercisesLogged: z.number().int().nonnegative()
+});
+const sessionLogOutputSchema = z.object({
+	date: z.string(),
+	created: z.boolean(),
+	sets: z.array(sessionLogSetOutputSchema),
+	scheduledAlternatives: z.array(z.object({
+		exerciseId: z.number(),
+		title: z.string(),
+		program: nullableString,
+		workoutTitle: z.string(),
+		savedWorkoutSetId: z.number(),
+		savedWorkoutSetExerciseId: z.number()
+	})).optional()
+});
+const personalWorkoutCreatedOutputSchema = z.object({
+	programWorkoutId: z.number(),
+	workoutId: z.number(),
+	savedWorkoutId: z.number(),
+	groupId: z.number(),
+	date: z.string()
+});
+const workoutReadExerciseOutputSchema = z.object({
+	order: z.number(),
+	title: z.string(),
+	reps: z.array(z.string()),
+	primaryUnit: nullableString,
+	load: z.array(z.string()),
+	loadUnit: nullableString,
+	instruction: z.string()
+});
+const workoutReadBlockOutputSchema = z.object({
+	order: z.number(),
+	title: z.string(),
+	instruction: z.string(),
+	leaderboard: nullableString,
+	exercises: z.array(workoutReadExerciseOutputSchema)
+});
+const workoutReadOutputSchema = z.object({
+	pwId: z.number(),
+	date: z.string(),
+	published: z.json().optional(),
+	instruction: z.string(),
+	blocks: z.array(workoutReadBlockOutputSchema)
+});
+z.object({
+	pwId: z.number(),
+	workoutId: z.number(),
+	programId: z.number(),
+	published: z.literal(false),
+	advisories: z.object({
+		notes: z.array(z.string()),
+		warnings: z.array(z.string())
+	}),
+	readback: workoutReadOutputSchema.nullable(),
+	note: z.string()
+});
+z.object({
+	published: z.number(),
+	readback: workoutReadOutputSchema,
+	note: z.string()
+});
+z.object({
+	sent: z.literal(true),
+	comment: z.json()
+});
+z.object({
+	deleted: z.literal(true),
+	response: z.json().optional()
+});
+z.object({ deleted: z.number() });
+z.object({ forgotten: z.number() });
+z.looseObject({ id: z.union([z.number(), z.string()]) });
+const mainLiftPrOutputSchema = z.object({
+	family: z.enum([
+		"cleanjerk",
+		"snatch",
+		"deadlift",
+		"squat",
+		"bench",
+		"overhead"
+	]),
+	label: z.string(),
+	exerciseId: nullableNumber,
+	title: nullableString,
+	weight: nullableNumber,
+	reps: nullableNumber,
+	units: nullableString,
+	date: nullableString
+});
+z.object({
+	athleteId: z.number(),
+	athleteName: nullableString,
+	prs: z.array(mainLiftPrOutputSchema)
+});
+z.object({
+	containerId: z.number(),
+	programId: z.number(),
+	title: z.string(),
+	kind: z.enum(["calendar", "fixed"]),
+	requestedName: z.string(),
+	nameApplied: z.boolean()
+});
+z.object({
+	programId: z.number(),
+	containerId: nullableNumber
+});
+//#endregion
 //#region ../dto/src/workout.ts
 /** A single exercise prescription inside a block. */
 const exerciseSpecSchema = z.object({
@@ -369,6 +724,12 @@ function toId(value) {
 }
 const READ = {
 	readOnlyHint: true,
+	destructiveHint: false,
+	openWorldHint: true
+};
+const ADDITIVE = {
+	readOnlyHint: false,
+	destructiveHint: false,
 	openWorldHint: true
 };
 const DESTRUCTIVE = {
@@ -390,32 +751,36 @@ async function attempt(fn) {
 }
 /** Conservative per-result character cap, below the smallest host cap. */
 const DEFAULT_RESULT_BUDGET = 6e4;
+/** Smallest cap that can still carry a useful structured truncation envelope. */
+const MIN_RESULT_BUDGET = 256;
 /** Reserve for the `__truncated` marker so wrapping cannot push back over budget. */
 const MARKER_RESERVE = 300;
 const DEFAULT_ARRAY_HINT = "Result was truncated to fit the size budget. Narrow it with a filter/search argument or paginate to see the rest.";
 const DEFAULT_OBJECT_HINT = "Result was truncated to fit the size budget. Request a more specific id or sub-resource.";
 /**
 * Clip an array to its first `keep` items and attach the `__truncated` marker describing what was
-* dropped. The marker is model-facing (tools instruct the model to key off `__truncated`), so its
-* shape has exactly one definition here: the size-budget path (`boundedSerialize`) and any tool
-* that deliberately caps a list (e.g. `athlete_exercises`) emit the same thing.
+* dropped. Every budget fallback that trims a list uses this envelope (`{ items, __truncated }`),
+* including in-place object-array truncation (the sliced array becomes `items` and `field` names
+* the original key). `athlete_exercises` uses the same helper for a client-side catalog cap.
 */
-function clipArray(items, keep, hint) {
+function clipArray(items, keep, hint, field) {
+	const marker = {
+		returned: keep,
+		total: items.length,
+		omitted: items.length - keep,
+		hint: hint ?? DEFAULT_ARRAY_HINT
+	};
+	if (field !== void 0) marker.field = field;
 	return {
 		items: items.slice(0, keep),
-		__truncated: {
-			returned: keep,
-			total: items.length,
-			omitted: items.length - keep,
-			hint: hint ?? DEFAULT_ARRAY_HINT
-		}
+		__truncated: marker
 	};
 }
 /** Active budget. Overridable via TH_MCP_RESULT_BUDGET on Node; the default on workerd. */
 function resultBudget() {
 	const raw = (globalThis.process?.env)?.TH_MCP_RESULT_BUDGET;
 	const n = raw ? Number(raw) : NaN;
-	return Number.isFinite(n) && n > 0 ? n : DEFAULT_RESULT_BUDGET;
+	return Number.isFinite(n) && n >= MIN_RESULT_BUDGET ? n : DEFAULT_RESULT_BUDGET;
 }
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -432,13 +797,6 @@ function largestPrefixCount(pieces, charBudget) {
 	}
 	return k;
 }
-/** Last resort: cap a string at the budget and label it as truncated, non-JSON output. */
-function hardCap(text, budget, hint) {
-	if (text.length <= budget) return text;
-	const note = `\n\n[TRUNCATED: output exceeded ${budget} chars and is NOT valid JSON. ${hint ?? "Narrow the query (filter, paginate, or fetch a specific id)."}]`;
-	const keep = Math.max(0, budget - note.length);
-	return text.slice(0, keep) + note;
-}
 function largestArrayValuedKey(obj) {
 	let best = null;
 	let bestLen = -1;
@@ -452,56 +810,79 @@ function largestArrayValuedKey(obj) {
 	}
 	return best;
 }
-/**
-* Serialize `data` as JSON within `budget` characters. Small results are pretty-printed.
-* Oversized results degrade in order: trim a top-level array (wrapping it as
-* `{ items, __truncated }`), then a top-level object's largest array property (annotated
-* with `__truncated`), then a last-resort hard character cap. Pure and side-effect free.
-*/
-function boundedSerialize(data, budget, hint) {
-	if (typeof data === "string") return hardCap(data, budget, hint);
-	const compact = JSON.stringify(data) ?? "null";
+function jsonValue(data) {
+	return JSON.parse(JSON.stringify(data) ?? "null");
+}
+function previewEnvelope(source, budget, hint) {
+	const total = source.length;
+	const makeValue = (preview, markerHint) => ({
+		preview,
+		__truncated: {
+			total,
+			omitted: total - preview.length,
+			hint: markerHint
+		}
+	});
+	let markerHint = hint ?? "Narrow the query (filter, paginate, or fetch a specific id).";
+	while (JSON.stringify(makeValue("", markerHint)).length > budget && markerHint.length > 0) markerHint = markerHint.slice(0, -1);
+	if (JSON.stringify(makeValue("", markerHint)).length > budget) throw new RangeError("Result budget is too small for a structured truncation envelope.");
+	let keep = Math.max(0, budget - JSON.stringify(makeValue("", markerHint)).length);
+	let value = makeValue(source.slice(0, keep), markerHint);
+	while (JSON.stringify(value).length > budget && keep > 0) {
+		keep = Math.max(0, keep - (JSON.stringify(value).length - budget));
+		value = makeValue(source.slice(0, keep), markerHint);
+	}
+	return value;
+}
+function boundedResult(data, budget, hint) {
+	if (typeof data === "string" && data.length <= budget) return {
+		text: data,
+		value: data
+	};
+	const value = jsonValue(data);
+	const compact = JSON.stringify(value);
 	if (compact.length <= budget) {
-		const pretty = JSON.stringify(data, null, 2) ?? "null";
-		return pretty.length <= budget ? pretty : compact;
+		const pretty = JSON.stringify(value, null, 2);
+		return {
+			text: pretty.length <= budget ? pretty : compact,
+			value
+		};
 	}
-	if (Array.isArray(data)) {
-		const k = largestPrefixCount(data.map((el) => JSON.stringify(el) ?? "null"), budget - MARKER_RESERVE);
-		const out = JSON.stringify(clipArray(data, k, hint));
-		if (out.length <= budget) return out;
-	} else if (isPlainObject(data)) {
-		const key = largestArrayValuedKey(data);
+	if (Array.isArray(value)) {
+		const truncated = clipArray(value, largestPrefixCount(value.map((element) => JSON.stringify(element)), budget - MARKER_RESERVE), hint);
+		const text = JSON.stringify(truncated);
+		if (text.length <= budget) return {
+			text,
+			value: truncated
+		};
+	} else if (isPlainObject(value)) {
+		const key = largestArrayValuedKey(value);
 		if (key !== null) {
-			const arr = data[key];
-			const pieces = arr.map((el) => JSON.stringify(el) ?? "null");
-			const restLen = (JSON.stringify({
-				...data,
-				[key]: []
-			}) ?? "{}").length;
-			const k = largestPrefixCount(pieces, Math.max(0, budget - MARKER_RESERVE - restLen));
-			const clone = {
-				...data,
-				[key]: arr.slice(0, k),
-				__truncated: {
-					field: key,
-					returned: k,
-					total: arr.length,
-					omitted: arr.length - k,
-					hint: hint ?? DEFAULT_OBJECT_HINT
-				}
+			const array = value[key];
+			const truncated = clipArray(array, largestPrefixCount(array.map((element) => JSON.stringify(element)), budget - MARKER_RESERVE), hint ?? DEFAULT_OBJECT_HINT, key);
+			const text = JSON.stringify(truncated);
+			if (text.length <= budget) return {
+				text,
+				value: truncated
 			};
-			const out = JSON.stringify(clone);
-			if (out.length <= budget) return out;
 		}
 	}
-	return hardCap(compact, budget, hint);
+	const truncated = previewEnvelope(typeof data === "string" ? data : compact, budget, hint);
+	return {
+		text: JSON.stringify(truncated),
+		value: truncated
+	};
 }
 /** A successful tool result carrying JSON (or text) for the model, size-bounded. */
 function jsonResult(data, opts) {
-	return { content: [{
-		type: "text",
-		text: boundedSerialize(data, resultBudget(), opts?.hint)
-	}] };
+	const { text, value } = boundedResult(data, resultBudget(), opts?.hint);
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		structuredContent: value
+	};
 }
 /** A tool-level error: returned in-band (isError) so the model can self-correct. */
 function errorResult(message) {
@@ -1830,12 +2211,14 @@ function registerProfileTools(server, ctx, whoami, userId) {
 		title: "Who am I (athlete)",
 		description: "The logged-in account's identity (id, name, roles) from /user/simple.",
 		inputSchema: {},
+		outputSchema: toolOutputSchema(userSimpleSchema),
 		annotations: READ
 	}, () => attempt(async () => jsonResult(await whoami())));
 	server.registerTool("athlete_profile", {
 		title: "Athlete profile + lifetime totals",
 		description: "Lifetime training totals in one call — all-time session count (summary.sessions_count), total reps and volume, first/last logged date — plus the profile (name, units, dob). Use this for any 'how many sessions all-time / total volume ever' question rather than summing athlete_workouts windows. Set useMetric for kg/metric totals.",
 		inputSchema: { useMetric: z.boolean().optional() },
+		outputSchema: toolOutputSchema(athleteProfileOutputSchema),
 		annotations: READ
 	}, ({ useMetric }) => attempt(async () => {
 		const id = await userId();
@@ -1849,12 +2232,14 @@ function registerProfileTools(server, ctx, whoami, userId) {
 		title: "Athlete preferences",
 		description: "Notification and display preference flags for the athlete account.",
 		inputSchema: {},
+		outputSchema: toolOutputSchema(athletePrefsSchema),
 		annotations: READ
 	}, () => attempt(async () => jsonResult(await fetchAthletePrefs(ctx.client))));
 	server.registerTool("athlete_working_maxes", {
 		title: "Working maxes",
 		description: "The athlete's working max per exercise (drives % prescriptions). An entry can carry a null value: the exercise has a working-max slot but no number has been set yet, which means there is effectively no working max for it.",
 		inputSchema: {},
+		outputSchema: toolOutputSchema(athleteWorkingMaxListSchema),
 		annotations: READ
 	}, () => attempt(async () => jsonResult(await fetchWorkingMaxes(ctx.client))));
 	server.registerTool("athlete_leaderboard", {
@@ -1866,6 +2251,7 @@ function registerProfileTools(server, ctx, whoami, userId) {
 			pageSize: z.number().int().positive().max(200).optional(),
 			gender: z.number().int().optional()
 		},
+		outputSchema: opaqueOutputSchema,
 		annotations: READ
 	}, ({ workoutId, page, pageSize, gender }) => attempt(async () => {
 		const opts = {};
@@ -1922,6 +2308,7 @@ function registerExerciseTools(server, ctx, userId) {
 			limit: z.number().int().positive().max(200).optional(),
 			summary: z.boolean().optional()
 		},
+		outputSchema: toolOutputSchema(athleteWorkoutsOutputSchema),
 		annotations: READ
 	}, (args) => runAthleteWorkouts(ctx, args));
 	server.registerTool("athlete_exercises", {
@@ -1931,6 +2318,7 @@ function registerExerciseTools(server, ctx, userId) {
 			q: z.string().optional(),
 			limit: z.number().int().positive().optional()
 		},
+		outputSchema: toolOutputSchema(athleteExerciseCatalogOutputSchema),
 		annotations: READ
 	}, (args) => runAthleteExercises(ctx, args));
 	server.registerTool("athlete_exercise_history", {
@@ -1942,6 +2330,7 @@ function registerExerciseTools(server, ctx, userId) {
 			since: dateString.optional(),
 			until: dateString.optional()
 		},
+		outputSchema: toolOutputSchema(exerciseHistoryOutputSchema),
 		annotations: READ
 	}, ({ exerciseId, raw, since, until }) => attempt(async () => {
 		const detail = await fetchExerciseHistoryDetail(ctx.client, toId(exerciseId), await userId());
@@ -1952,6 +2341,7 @@ function registerExerciseTools(server, ctx, userId) {
 		title: "Exercise personal records",
 		description: "The all-time PR board for an exercise (reps/weight per rep-max, strength-standard filters). Get the exercise id from athlete_exercises. A lift is often logged under several name variants, each with its own board, so if a PR looks missing check the other variants. For a point-in-time snapshot use athlete_exercise_stats; for the dated session trend use athlete_exercise_history.",
 		inputSchema: { exerciseId: idParam },
+		outputSchema: toolOutputSchema(personalRecordListSchema),
 		annotations: READ
 	}, ({ exerciseId }) => attempt(async () => jsonResult(await fetchPersonalRecords(ctx.client, toId(exerciseId)))));
 	server.registerTool("athlete_exercise_stats", {
@@ -1961,6 +2351,7 @@ function registerExerciseTools(server, ctx, userId) {
 			exerciseId: idParam,
 			date: dateString
 		},
+		outputSchema: toolOutputSchema(exerciseStatsSchema),
 		annotations: READ
 	}, ({ exerciseId, date }) => attempt(async () => jsonResult(await fetchExerciseStats(ctx.client, toId(exerciseId), await userId(), date))));
 }
@@ -1977,6 +2368,7 @@ function registerLogTargetsTool(server, ctx) {
 			teamId: idParam.optional(),
 			raw: z.boolean().optional()
 		},
+		outputSchema: toolOutputSchema(logTargetsOutputSchema),
 		annotations: READ
 	}, ({ startDate, endDate, program, programId, teamId, raw }) => attempt(async () => {
 		const workouts = selectWorkoutsByProgram(await fetchAthleteWorkouts(ctx.client, startDate, endDate), definedProps({
@@ -1994,11 +2386,8 @@ function registerSessionTools(server, ctx) {
 		title: "Create personal workout session",
 		description: "Create a new personal workout session for a given YYYY-MM-DD date on the athlete's personal calendar. Returns programWorkoutId, workoutId (pass to athlete_session_add_exercises), savedWorkoutId, groupId, and date.",
 		inputSchema: { date: dateString },
-		annotations: {
-			readOnlyHint: false,
-			destructiveHint: false,
-			openWorldHint: true
-		}
+		outputSchema: toolOutputSchema(personalWorkoutCreatedOutputSchema),
+		annotations: ADDITIVE
 	}, ({ date }) => attempt(async () => jsonResult(await createPersonalWorkout(ctx.client, date))));
 	server.registerTool("athlete_session_add_exercises", {
 		title: "Add exercises to a personal workout session",
@@ -2010,11 +2399,8 @@ function registerSessionTools(server, ctx) {
 				order: z.number().int().positive()
 			})).min(1)
 		},
-		annotations: {
-			readOnlyHint: false,
-			destructiveHint: false,
-			openWorldHint: true
-		}
+		outputSchema: opaqueOutputSchema,
+		annotations: ADDITIVE
 	}, ({ workoutId, exercises }) => attempt(async () => {
 		const mapped = exercises.map((e) => ({
 			exerciseId: toId(e.exerciseId),
@@ -2029,6 +2415,7 @@ function registerSessionTools(server, ctx) {
 			...athleteSessionRemoveArgsSchema.shape,
 			confirm: z.boolean().optional()
 		},
+		outputSchema: toolOutputSchema(athleteSessionRemovedOutputSchema),
 		annotations: DESTRUCTIVE
 	}, ({ programWorkoutId, date, confirm }, extra) => attempt(async () => {
 		const id = toId(programWorkoutId);
@@ -2071,6 +2458,7 @@ function registerLogTool(server, ctx) {
 			...logSessionArgsSchema.shape,
 			confirm: z.boolean().optional()
 		},
+		outputSchema: toolOutputSchema(sessionLogOutputSchema),
 		annotations: DESTRUCTIVE
 	}, ({ date, exercises, confirm }, extra) => attempt(async () => {
 		const blocked = confirmGate(extra, `Log a session of ${exercises.length} exercise(s) on ${date}? This writes to your coach-visible training log.`, confirm);
@@ -2089,6 +2477,7 @@ function registerLogTool(server, ctx) {
 			...logSetArgsSchema.shape,
 			confirm: z.boolean().optional()
 		},
+		outputSchema: toolOutputSchema(setLogOutputSchema),
 		annotations: DESTRUCTIVE
 	}, ({ date, savedWorkoutSetId, results, confirm }, extra) => attempt(async () => {
 		const blocked = confirmGate(extra, `Log results to saved workout set ${toId(savedWorkoutSetId)} on ${date}? This writes to your coach-visible training log.`, confirm);
@@ -2106,6 +2495,7 @@ function registerLogTool(server, ctx) {
 			...athletePrescribeSetArgsSchema.shape,
 			confirm: z.boolean().optional()
 		},
+		outputSchema: toolOutputSchema(setPrescriptionOutputSchema),
 		annotations: DESTRUCTIVE
 	}, ({ date, savedWorkoutSetId, results, confirm }, extra) => attempt(async () => {
 		const id = toId(savedWorkoutSetId);
@@ -2132,6 +2522,7 @@ function registerSwapTool(server, ctx) {
 			...swapAthleteExerciseArgsSchema.shape,
 			confirm: z.boolean().optional()
 		},
+		outputSchema: toolOutputSchema(exerciseSwapOutputSchema),
 		annotations: DESTRUCTIVE
 	}, ({ savedWorkoutSetExerciseId, exerciseId, confirm }, extra) => attempt(async () => {
 		const sweId = toId(savedWorkoutSetExerciseId);
@@ -2149,18 +2540,21 @@ function registerCatalogReads(server, ctx) {
 		title: "Circuit history",
 		description: "Named circuit history for the logged-in athlete (GET /v5/users/circuits/{recent|history}). kind defaults to recent. Empty when the athlete has no saved circuits. Distinct from circuit *blocks* in workout_build (type 1).",
 		inputSchema: { kind: z.enum(["recent", "history"]).optional() },
+		outputSchema: opaqueOutputSchema,
 		annotations: READ
 	}, ({ kind }) => attempt(async () => jsonResult(await fetchAthleteCircuits(ctx.client, kind ?? "recent"))));
 	server.registerTool("athlete_programming_programs", {
 		title: "Subscribed programs",
 		description: "Programs the athlete is subscribed to (GET /1.0/athlete/programming/programs). Not the coach list_programs surface. Empty when the athlete has no subscriptions.",
 		inputSchema: {},
+		outputSchema: opaqueOutputSchema,
 		annotations: READ
 	}, () => attempt(async () => jsonResult(await fetchAthleteProgrammingPrograms(ctx.client))));
 	server.registerTool("athlete_recent_exercises", {
 		title: "Recent exercises",
 		description: "Recently used exercises (GET /v5/users/exercises/recent). Distinct from athlete_exercises (full logged catalog) and athlete_exercise_history (one lift).",
 		inputSchema: {},
+		outputSchema: opaqueOutputSchema,
 		annotations: READ
 	}, () => attempt(async () => jsonResult(await fetchRecentExercises(ctx.client))));
 }
@@ -2194,7 +2588,7 @@ function registerAthleteTrainingTools(server, ctx) {
 }
 //#endregion
 //#region package.json
-var version = "3.2.0";
+var version = "3.3.0";
 //#endregion
 //#region src/server.ts
 function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trainheroic-unofficial/athlete-mcp",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,13 +21,13 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
     "zod": "^4.4.3",
-    "@trainheroic-unofficial/core": "3.2.0",
-    "@trainheroic-unofficial/js": "3.2.0"
+    "@trainheroic-unofficial/core": "3.3.0",
+    "@trainheroic-unofficial/js": "3.3.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "tsdown": "^0.22.14",
-    "tsx": "^4.23.11",
+    "tsx": "^4.23.12",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },