Pantry Persona

Use this when the user wants recipe ideas, asks what to make/cook ("what's for dinner", "what can I make with X"), or asks for recipes by name, ingredient, tag, or diet (keto/vegan/low-carb/paleo — pass forDiet so diet results are grounded in saved data, not guessed). Prefer their saved recipes over generic ideas. Pass excludeRecipeIds when rejected. Returns data only. If they ask what's already scheduled ("what's for dinner tonight"), call show_meal_plan instead.

find_recipes

Use this when the user asks "how much do I spend", "what brands do I buy", "when will I run out of X", "how am I doing this week", "am I hitting my target", or "what nutrients am I low on". Returns analytics — spending, price history, brands, shopping patterns, restock predictions, consumption, receipts, weekly nutrition trends, hit rate, top deficits — no widget. Not for recipe or pantry lookups (→ find_recipes, get_pantry) or today's intake totals (→ get_user_context).

get_insights

Use this when the user says hello, asks about their household, asks about nutrition intake today ("what's my sodium today"), or starts a meal-planning session that needs the full kitchen snapshot upfront. Returns dietary profiles, pantry highlights, expiring items, today's meal plan with logged/target nutrition totals (Pro), shopping status, staple tracking, and saved planning workflow. Do not use for specific recipe-discovery prompts ("dinner ideas", "what should I cook") — call find_recipes. Not for weather or general knowledge.

get_user_context

Use this when the model needs ingredient data internally — to match pantry contents against a recipe, check availability before suggesting meals, or reason over inventory before answering. Returns the pantry as data for the model; no widget. Do not use when the user asks about their own pantry ("what's in my pantry", "what's expiring", "do I have X") — call show_pantry. Not for "running low"/restock (→ get_insights) or "what should I do next" (→ get_next_steps).

get_pantry

Use this when the user asks what to do next or seems unsure how to use the app — "what should I do next", "what's next in my kitchen", "what can I do", "what features haven't I tried", "help me get started". "My kitchen" means their Pantry Persona kitchen, not a physical room. Returns 2-3 personalized next-step suggestions across profiles, pantry, recipes, shopping, meal plan, and receipts. Do not use when the user has a specific action in mind.

get_next_steps

Use this when the user reports eating a meal — a recipe they cooked ("I made the chicken pasta", "just cooked dinner") or an ad-hoc/restaurant meal given by its macros with no recipe ("ate out, 800 cal 50g protein"). Logs it toward nutrition; a recipe also deducts pantry and updates cook history. Do not use for browsing or planning meals — call find_recipes.

post_cook

Use this when the user puts a recipe into a named group — "add to Ben Approved", "throw this into favorites", "create a weeknight dinners collection" — removes one, or lists them ("pull up collections"). Creates, renames, deletes, lists, and edits collection membership. Auto-creates the collection if missing. Do not use for likes or dislikes — call manage_profiles — or to save a recipe — call manage_recipes.

manage_collections

Use this when the user names a recipe for a day, or asks to replace, swap, or change a planned meal, e.g. "replace Wednesday dinner with a salmon recipe"; freeform meal names work without recipeIds. One-meal or guest dietary scopes ("Mark is vegetarian Saturday") belong here, not manage_profiles. Commits one day at a time: set assigns, clear removes, move relocates; never set_week for bulk. Preview, then re-call with the confirmationToken; never narrate a meal change without that completed call.

manage_meal_plan

Use this when the user corrects their pantry inventory ("I don't have X anymore", "we used the Y", "add these groceries"), or reports cooked leftovers. Adds, removes, updates, or consumes pantry items, logs leftovers, clears expired items, and recategorizes miscategorized items. Handles batches of up to 100 items per call. Do not use this for shopping list changes — call manage_shopping instead — or to display the current pantry — call show_pantry.

manage_pantry

Use this when the user names a product preference ("I prefer [brand]", "forget my preference", "what are my brand preferences") or sets a behavioral preference about how you respond ("give me one at a time", "step at a time", "too much info", "stop reminding me about everyone's allergies", "don't show that recipe again" — pacing, info density, decision style, dietary acknowledgement, recipe exclusions). Do not use for household dietary profiles (call manage_profiles) or recipe-level preferences (call manage_recipes).

manage_preferences