Loki Docs
Tools › Exercises › Suggest a substitute exercise

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 catalog slug (e.g. "barbell-back-squat") or the numeric id from find_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 unless useNiggles is false.
  • onlyWhatIOwntrue or false, optionalTrue = only what the user can do with the equipment they actually have. Needs get_my_equipment to have something in it.
  • placetext, optionalWhich place onlyWhatIOwn means: a place's name (case-insensitive), or "home" / "gym". Ignored without onlyWhatIOwn.
  • 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.