Suggest a substitute exercise
suggest_substitutionReads- What it does
- Reads only. Changes nothing.
- Permission
- Exercises, read
exercises:read
What your assistant is told
"What could I do instead of this?" — the exercises that train the SAME MOVEMENT (same pattern) in the same part of the body, at a similar difficulty, best first. Use it when a machine is taken, the user is bored of a lift, they are away from their usual gym, or **something hurts**.
**When something hurts, pass a tag.** "My knee hurts" is tags: ["knee-safe"] and then every result is a lift the catalog claims is easy on the knees — nothing else is returned, not even a close call. Read each tag's exact claim off any get_exercise result first; the five are "knee-safe", "lower-back-safe", "shoulder-safe", "no-axial-load" and "high-impact". Four are claims of safety; **"high-impact" names the hazard instead** — it sits on jumps, landings and the barbell Olympic lifts, so asking for it means "no jumping" and those rows are the ones left out. Several tags narrow, they don't widen.
**You don't have to ask.** By default this reads the user's own active niggles (get_profile → niggles, or set_niggle) and applies their tags on top of whatever you pass, so a user who told the app their knee hurts gets knee-safe swaps without saying it again. useNiggles: false turns that off — only when the user explicitly asks for the unfiltered list. appliedTags on the result says what was actually filtered on.
**The fallback.** When nothing with the same movement honours the tags, the result carries fallback: true and a list of **different movements for the same part of the body** that do — no squat is easy on the knees, so a knee-safe swap for a back squat comes back as hip thrusts and back extensions, clearly labelled. Tell the user it is a different movement, never that it is "like a squat". Tags are never relaxed to fill the list: substitutes empty **and** fallback false means nothing in the catalog honours the request, which is a real answer — say so rather than talking them into one.
onlyWhatIOwn: true (with an optional place) keeps only what they can actually do with their own equipment — every requirement met, same rule as find_exercises.
This is NOT the tool for "what's next?" — a harder or easier version of the same exercise is progression on get_exercise. And it changes nothing: to actually replace a lift in a workout, call update_session_exercise with sets: "keep" or "delete".
Parameters
exercisetext, requiredThe exercise to replace: a catalogslug(e.g. "barbell-back-squat") or the numericidfromfind_exercises. One of the user's own exercises works too, and answers from whatever the catalog knows about it.tagslist of text, optionalSafety tags EVERY result must honour, e.g. ["knee-safe"]. Pass these whenever the user says something hurts and it is not already a niggle. Applied ON TOP of the user's active niggles unlessuseNigglesis false.onlyWhatIOwntrue or false, optionalTrue = only what the user can do with the equipment they actually have. Needsget_my_equipmentto have something in it.placetext, optionalWhich placeonlyWhatIOwnmeans: a place's name (case-insensitive), or "home" / "gym". Ignored withoutonlyWhatIOwn.limitwhole number, optionalHow many substitutes to return (default 10, capped at 25).useNigglestrue or false, optionalDefault TRUE: also honour whatever the user has told the app hurts (get_profile→niggles). Pass false ONLY when the user explicitly asks to see everything regardless.