Read changes nothing. Write changes the member's Live Better AI data. Sensitive write makes something outside Live Better AI: an Instacart shopping-list link. Every answer is { ok: true, data } or { ok: false, error }, as structured content and as text. Muse is offered the tools marked in the last column.
search_recipes
Read · No account
Searches the Live Better AI recipe catalog, best match first unless another sort is asked for. Changes nothing. With a member's sign-in, that member's own allergies and diet apply too, and anything stated can only narrow them.
Inputs
query: What the person asked for, in their own words, up to 120 characters (for example "high-protein chicken dinner" or "kid friendly dinners"). Words naming a meal, a diet, a time, a protein or calorie wish or a family are read as filters or an order, and understood in the answer says how; the other words are matched against titles, ingredients and cuisines, and any one of them is enough. Give a query, a diet, a meal_type, a cuisine, or a protein, calorie or time limit.diet: vegetarian, vegan or pescatarian. Checked against ingredient names and the recipe's verified diet flags.allergies: Up to 10 of milk, egg, fish, shellfish, tree_nut, peanut, wheat, gluten, soy, sesame. Matched on ingredient names only.exclude_ingredients: Up to 10 other foods to keep out, as plain words (for example "cilantro").max_minutes: 5 to 240, by our recipe audit's time estimate. A recipe with no audit time never matches.cuisine: One of the catalog's cuisines (for example italian, mexican, thai, indian, mediterranean). Only recipes the catalog tags with it; an untagged recipe does not match.min_protein_g: 1 to 200. At least this many grams of protein per serving, as the app rounds it. Unknown protein does not match.max_calories: 50 to 3,000. At most this many calories per serving. Unknown calories do not match.meal_type: breakfast, lunch (salads, soups, sandwiches and other lunch dishes), dinner (main dishes only, never a side), snack (never a main), dessert or side.sort: relevance (the default: the best match first, then a sane cook time), catalog (the catalog's own order; results match the search but are not ranked by it), quickest, most_protein or fewest_calories. Every sort but catalog orders the whole match, not one page; recipes with no number for the sort come last, and ties are broken the same way every time, so the order is stable.limit: 1 to 20 results. Default 10.cursor: next_cursor from the previous page. It works only with the search and sort it came from.
Returns
recipes (summary cards: recipe_id, title, image_url, recipe_url, cook_time_minutes (our recipe audit's estimate), calories_per_serving, protein_g, carbs_g and fat_g (the panel the app shows, in whole numbers), servings and cuisines, and diet_labels; no ingredients or steps), next_cursor, sort, understood (the words matched, the meal_type, diet labels, carb cap and order the query asked for, and one plain line per phrase it read), filters (the cuisine, protein and calorie filters applied), screened_for (what was screened, never who asked), screen_basis "ingredient_names" when a screen applied, and safety_notice. The answer's second text block has one markdown image line per recipe photo.
Errors
invalid_input, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "search_recipes",
"arguments": {
"query": "high-protein chicken dinner",
"allergies": [
"peanut"
],
"max_calories": 600,
"limit": 5
}
}get_recipe
Read · No account
Reads one catalog recipe. Changes nothing. Without an account the method is withheld, as on the public recipe page; a partner key and a signed-in member get the steps.
Inputs
recipe_id (required): Digits only, from search_recipes or suggest_week, as a string or a whole number.
Returns
recipe_id, title, cook_time_minutes (our recipe audit's estimate), calories_per_serving, protein_g, carbs_g and fat_g (the panel the app shows, in whole numbers), servings and cuisines, diet_labels, image_url, recipe_url, ingredients with amounts, steps, macros_per_serving (the panel's detail; null when unknown, never guessed), content_source and safety_notice, plus a markdown image line for its photo. When the method is withheld: steps is empty, method_withheld is true and method_note says where to read it. One not_found answers every well-formed id that is not a public recipe; an id that is not digits is refused by input validation before the tool runs.
Errors
not_found, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "get_recipe",
"arguments": {
"recipe_id": "1000566"
}
}suggest_week
Read · No account
Suggests a varied week of catalog recipes for a household size. Changes and stores nothing. Dinners are main dishes, never a side, and meals within the time asked for (or the member's own weeknight time, or an hour) come first; a longer one is used only when nothing else is left. The same request gives the same week. To replace one meal, ask again with its recipe_id added to exclude_recipe_ids: every meal before it stays the same, and meals after it may change. A new variation gives a different week.
Inputs
household_size (required): How many people each meal feeds, 1 to 6.days: 1 to 7. Default 7.meals: Any of breakfast, lunch, dinner. Default dinner.diet: vegetarian, vegan or pescatarian. Checked against ingredient names and the recipe's verified diet flags.allergies: Up to 10 of milk, egg, fish, shellfish, tree_nut, peanut, wheat, gluten, soy, sesame. Matched on ingredient names only.exclude_ingredients: Up to 10 other foods to keep out, as plain words (for example "cilantro").max_minutes: 5 to 240, by our recipe audit's time estimate. A recipe with no audit time never matches.cuisine: One of the catalog's cuisines (for example italian, mexican, thai, indian, mediterranean). Only recipes the catalog tags with it; an untagged recipe does not match.min_protein_g: 1 to 200. At least this many grams of protein per serving, as the app rounds it. Unknown protein does not match.max_calories: 50 to 3,000. At most this many calories per serving. Unknown calories do not match.exclude_recipe_ids: Up to 50 recipe ids (strings or whole numbers) to leave out, for example to replace one meal. Earlier meals stay the same.variation: 0 to 20. Default 0. A different number gives a different week.
Returns
days (each with meals: recipe_id, title, image_url, recipe_url, cook_time_minutes (our recipe audit's estimate), calories_per_serving, protein_g, carbs_g and fat_g (the panel the app shows, in whole numbers), servings and cuisines, and diet_labels, plus type, servings and recipe_servings), unfilled_slots and a message when the catalog cannot fill every slot (a recipe is never repeated and a screen is never relaxed), catalog_version, shop_input (ready to pass to shop_recipes), filters, screened_for and safety_notice, plus one markdown image line per meal photo.
Errors
unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "suggest_week",
"arguments": {
"household_size": 2,
"days": 5,
"meals": [
"dinner"
],
"allergies": [
"peanut"
]
}
}shop_recipes
Sensitive write · No account
Makes an Instacart shopping-list link for catalog recipes, each at its own yield or for the servings given. It changes no Live Better AI data. No order or payment is placed: the person taps the link, presses "Shop ingredients on Instacart" on our page, picks a store and checks out on the Instacart page. US only. The link comes back at once; the Instacart list itself is made when the person presses the button on our page, so a link nobody opens costs nothing. While it is made, the person may see a short "Getting your Instacart list..." page. The assistant must hand the link to the person and never open, fetch or click it.
Inputs
recipes (required): 1 to 21 of { recipe_id, servings }. recipe_id is a string or a whole number. servings is 1 to 12; leave it out for the recipe's own yield. Name each recipe once.country: US. Live Better AI serves the United States only.confirmed (required): true, only after the person asked for this list.
Returns
url (always a www.livebetterai.com/api/instacart/go link), cached, items_count, country, order_placed (always false), affiliate_disclosure, link_kind (recipe or shopping_list), next_step (the words to say to the person, quoted under Instacart shopping lists) and safety_notice. The answer's second text block says the link and next_step as markdown.
Errors
invalid_input, not_found, rate_limited, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "shop_recipes",
"arguments": {
"recipes": [
{
"recipe_id": "1000566",
"servings": 2
}
],
"country": "US",
"confirmed": true
}
}set_up_household
Write · Account
Reviews the member's household setup, or saves a reviewed one (a save replaces the household and preferences). Health and body details, allergies, restrictions and diet settings are never shown to the app; a save keeps them, and any sent are only added.
Inputs
phase (required): review, or save after the member confirmed.household: save: the household as reviewed.default_schedule: save: the weekly meal schedule as reviewed.cooking: save: cooking preferences as reviewed.food: save: food preferences as reviewed.budget: save: budget preferences as reviewed.nutrition_goals: save: optional; the stored goals are kept when left out.output_preferences: save: output preferences as reviewed.expected_profile_updated_at: save: updated_at from the review, so a change made elsewhere is not overwritten.confirmed: save: true, after the member confirmed.
Returns
review: the shareable setup and kept_private (what stays on Live Better AI). save: profile_id and updated_at.
Errors
invalid_input, conflict, unauthorized, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "set_up_household",
"arguments": {
"phase": "review"
}
}build_my_week
Write · Account
Builds a new week and grocery list, or rebuilds the rest of an owned week. Runs in the background; check it with get_week_build_status.
Inputs
mode (required): build, or rebuild_remaining.week_of: build: the Monday to plan, YYYY-MM-DD. Default: the member's next Monday.plan_id: rebuild_remaining: the week to rebuild.expected_version: rebuild_remaining: the version the member saw.confirmed (required): true, after the member confirmed.idempotency_key (required): 8 to 128 letters, digits, _ or -. The same key never builds twice.
Returns
job_id, status and poll_after_seconds.
Errors
invalid_input, not_found, conflict, rate_limited, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "build_my_week",
"arguments": {
"mode": "build",
"week_of": "2026-10-19",
"confirmed": true,
"idempotency_key": "week-2026-10-19-a"
}
}get_week_build_status
Read · Account
Reads the status of one of the member's week builds. Changes nothing. Poll at most every 10 seconds.
Inputs
job_id (required): From build_my_week.
Returns
job_id, status, plan_id and version when built, and issues.
Errors
invalid_input, not_found, rate_limited, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "get_week_build_status",
"arguments": {
"job_id": "00000000-0000-4000-8000-000000000000"
}
}get_my_pantry
Read · Account
Reads the food recorded in the member's pantry. Changes nothing.
Inputs
None.
Returns
items, each with id, name, qty, unit, expiration and source.
Errors
forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "get_my_pantry",
"arguments": {}
}edit_my_pantry
Write · Account
Adds pantry items, changes an expiry date or removes an item. This can change the grocery list.
Inputs
operation (required): add, set_expiration or remove.items: add: 1 to 100 of { name, qty, unit, expiration }.item_id: set_expiration or remove: the pantry item.expiration: set_expiration: YYYY-MM-DD, or null.confirmed (required): true, after the member confirmed.
Returns
items (the pantry after the change) and skipped.
Errors
invalid_input, not_found, conflict, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "edit_my_pantry",
"arguments": {
"operation": "add",
"items": [
{
"name": "rice",
"qty": 2,
"unit": "lb"
}
],
"confirmed": true
}
}get_my_plan
Read · Account · also offered as get_weekly_plan
Reads the member's week. Changes nothing. Without plan_id it reads the week under way on the member's own day, as the app does.
Inputs
plan_id: An owned plan. Default: this week.
Returns
plan_id, week_of, version, updated_at, meals (each addressed by day_index and meal_index, with title, type, servings, recipe_id, links, photo, ingredients, steps and nutrition; a staple side with no photo carries icon_url, its public grocery icon), grocery_items_count and safety_notice, plus one markdown image line per photo. A recipe the member imported returns its title and links only.
Errors
not_found, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "get_my_plan",
"arguments": {}
}get_meal_details
Read · Account
Reads one planned meal in full. Changes nothing.
Inputs
plan_id (required): From get_weekly_plan.day_index (required): 0 to 6.meal_index (required): 0 to 7.
Returns
plan_id, week_of, version, meal (ingredients, steps, nutrition, photo and links) and safety_notice.
Errors
not_found, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "get_meal_details",
"arguments": {
"plan_id": "00000000-0000-4000-8000-000000000000",
"day_index": 0,
"meal_index": 0
}
}swap_my_meal
Write · Account · also offered as swap_meal
Suggests replacements the app already vetted for one planned meal (changes nothing), then swaps one in after the member confirms, which rebuilds the grocery list. It takes no free recipe id: only a vetted choice, so the member's allergy screen always applies.
Inputs
phase (required): suggest, or apply.plan_id (required): The member's week.slot (required): { day_index, meal_index } of the meal to replace.choice_token: apply: from a suggest answer.expected_plan_updated_at: apply: plan_updated_at from the suggest answer.confirmed: apply: true, after the member confirmed.
Returns
suggest: choices (a choice_token and a recipe card each) and plan_updated_at. apply: the replaced and replacement meals, the new version and grocery_items_count. Both carry safety_notice.
Errors
invalid_input, not_found, conflict, rate_limited, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "swap_my_meal",
"arguments": {
"phase": "suggest",
"plan_id": "00000000-0000-4000-8000-000000000000",
"slot": {
"day_index": 2,
"meal_index": 0
}
}
}get_my_grocery_list
Read · Account
Reads a week's grocery rows as an edit names them. Changes nothing.
Inputs
plan_id (required): An owned plan.
Returns
plan_id, version, items (section, item, quantity, unit, checked, excluded, adjusted_quantity, used_in, shop_text, may_already_have), items_count and safety_notice.
Errors
not_found, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "get_my_grocery_list",
"arguments": {
"plan_id": "00000000-0000-4000-8000-000000000000"
}
}get_grocery_list
Read · Account
Reads the week's grocery list as two lists, to buy and may already have, a page at a time. Changes nothing.
Inputs
plan_id: An owned plan. Default: this week.limit: Rows per page, 1 to 200. Default 100.cursor: next_cursor from the previous page.
Returns
plan_id, week_of, version, to_buy, may_already_have, their counts across the whole list, excluded_count, next_cursor and safety_notice.
Errors
invalid_input, not_found, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "get_grocery_list",
"arguments": {
"limit": 100
}
}edit_my_grocery_list
Write · Account
Checks, excludes or adjusts grocery rows in a week.
Inputs
plan_id (required): The week.expected_updated_at (required): updated_at the member saw, so a change made elsewhere is not overwritten.updates: Up to 200 of { section, item, unit, checked, excluded, adjusted_quantity }.op: exclude_all_pantry, to take every pantry item off the list.confirmed (required): true, after the member confirmed.
Returns
plan_id, updated_at, items and safety_notice.
Errors
invalid_input, not_found, conflict, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "edit_my_grocery_list",
"arguments": {
"plan_id": "00000000-0000-4000-8000-000000000000",
"expected_updated_at": "2026-10-14T12:00:00Z",
"updates": [
{
"section": "Produce",
"item": "Limes",
"checked": true
}
],
"confirmed": true
}
}list_my_favorites
Read · Account
Reads the member's saved recipes, a page at a time. Changes nothing.
Inputs
limit: 1 to 100. Default 20.cursor: next_cursor from the previous page.
Returns
recipes, next_cursor, omitted_unavailable_count and safety_notice. A recipe the member imported returns its title and links only.
Errors
invalid_input, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "list_my_favorites",
"arguments": {
"limit": 20
}
}add_favorite
Write · Account
Saves a catalog recipe, or one the member imported, as a favorite.
Inputs
recipe_id (required): The recipe.source (required): corpus (the catalog) or saved (the member's own).confirmed (required): true, after the member confirmed.
Returns
recipe_id, favorited, the recipe card and safety_notice.
Errors
invalid_input, not_found, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "add_favorite",
"arguments": {
"recipe_id": "1000566",
"source": "corpus",
"confirmed": true
}
}import_recipe
Write · Account
Previews a recipe from a web page as a private, expiring draft, then saves it as a favorite after the member confirms. The recipe's text stays on Live Better AI.
Inputs
phase (required): preview, or save.url: preview: an http or https recipe page.draft_token: save: from the preview answer.confirmed: save: true, after the member confirmed.
Returns
preview: draft_token, expires_at and the recipe's title and links. save: recipe_id and favorited. Both carry safety_notice.
Errors
invalid_input, not_found, conflict, rate_limited, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "import_recipe",
"arguments": {
"phase": "preview",
"url": "https://example.com/recipe"
}
}send_to_instacart
Sensitive write · Account · also offered as create_shopping_list
Previews the exact shopping list for the member's week or chosen meals (changes nothing), then makes an Instacart shopping-list link after the member confirms. No order or payment is placed. US only. The link comes back at once; the Instacart list itself is made when the person presses the button on our page, so a link nobody opens costs nothing. While it is made, the person may see a short "Getting your Instacart list..." page. The assistant must hand the link to the member and never open, fetch or click it.
Inputs
phase (required): preview, or send.plan_id (required): The member's week.scope (required): { type: "week" }, or { type: "slots", slots: [{ day_index, meal_index }] }.expected_plan_version (required): The version the member saw.confirmation_token: send: from the preview answer.confirmed: send: true, after the member confirmed.
Returns
preview: the items, items_count, already_ordered_count and a confirmation_token. sent: url (our /go link), cached, items_count, expires_at, order_placed (always false), affiliate_disclosure and next_step (the words to say to the member, quoted under Instacart shopping lists).
Errors
invalid_input, not_found, conflict, rate_limited, forbidden, unavailable. Over a rate limit, or before any tool runs, the request itself can answer an HTTP error (see Errors and Rate limits below).
Example call
{
"name": "send_to_instacart",
"arguments": {
"phase": "preview",
"plan_id": "00000000-0000-4000-8000-000000000000",
"scope": {
"type": "week"
},
"expected_plan_version": 3
}
}