The one call to make when the user says 'run agent chef' (or run the app / plan dinner / do the weekly thing). Returns the operating manual plus the checklist of tool calls that are due right now. Execute them in order, then call next_actions again until it returns no actions. Stop before any checkout.

Call after creating (or changing) the recurring 'Run Agent Chef.' task in your own scheduler, with a one-line description, e.g. 'Claude scheduled task, daily 9:00 and 18:00 America/Los_Angeles'. Lets the app stop reminding you and shows the owner that the loop is automated.

Hides the 'Get set up' card on the household dashboard (e.g. when the owner says they don't need it). Pass show=true to bring it back.

Agents connected to this household via OAuth sign-in (Claude, ChatGPT…), with when they connected and last used. API keys are separate.

Revoke an OAuth-connected agent's access (client_id from get_connected_agents). It must sign in again to reconnect.

START HERE. Returns the current phase and an ordered checklist of tool calls that are due right now (propose, send ballot, remind non-voters, add options for feedback, lock in, shop), with why and the arguments/message text to use. Execute them, then call again until empty. Idempotent and time-aware; safe to call on a schedule.

The full operating manual for agents: the run loop, phases, how to write recipes, messaging and safety rules. Read once per session.

Household name, recipe preferences prompt (diet, allergies, dislikes, cuisines, time budget), shopping preferences prompt (brands, organic, store quirks) plus settings: plan_day, servings, grocery_store, recipes_per_week, votes_per_member.

Update any subset of the preferences prompt and settings. Omitted fields are unchanged.

List household members with contact info, whether they have signed in to Agent Chef themselves (has_account), whether they get push notifications, and their personal vote links.

Add a household member, or edit one: name is the key (case-insensitive), or pass member_id from get_members to rename. Phone and email update when given; an empty string clears them. Use this when someone wants to add or fix a member's contact details; never remove and re-add, which breaks their vote link. Roles: member (default) can vote, rate and browse once they sign in; admin can also change settings, recipes and weeks like the owner.

Remove a household member by name (their votes and ratings stay attached to past weeks). The owner can't be removed.

What the household already has, so the shopping list can skip it. Staples (staple: true) are always on hand unless marked out; leftovers carry expires_at and drop off on their own.

Keep the pantry: add staples the household always has (omit days), add leftovers that should be skipped for a while and then drop off (days, 7 is typical), mark staples out when they run low so they go back on the shopping list, or remove items. Adding a staple that was out puts it back in stock. Don't add a week's groceries: they get cooked that week.

Recipes marked as household favorites, with ratings. Good candidates to re-propose by recipe_id.

Mark (or unmark) a recipe as a household favorite.

Full details for one recipe: ingredients, steps, servings, source, tags, ratings, comments, how often it's been cooked, a link to its page, and a public share_url anyone can open.

Every recipe the household has ever had proposed, with ratings and cook counts. Filter by text, favorites, or tag. Use recipe_id from here with propose_recipes to re-propose.

Copy a recipe from Community recipes (search_recipes with scope 'library') into this household. Pass favorite: true to also mark it a favorite. Returns the household's copy; use its id on ballots. Passing a library id straight to propose_recipes or add_candidates does the same copy automatically.

Edit a stored recipe: fix an ingredient, add steps, change servings, tags, image or source, or set public to publish it on agentchef.net/recipes. Only provided fields change.

Fetch a recipe page (most cooking sites) and save it to the library with its real photo, ingredients, and steps. Returns the recipe; pass its recipe_id to propose_recipes or add_candidates to put it on a ballot.

Save a recipe to the library from details you already have: one you read in your browser (when a site blocks import_recipe or has no recipe markup), one the owner dictated, or one you wrote. Provide the complete ingredient list with quantities and the steps; include the source page and a real photo URL when you have them. Optionally mark it a favorite.

Store a photo for a recipe permanently and set it as the recipe's image. Use for images you generated with your image tool (their URLs expire) or any photo you have as a URL or base64. Pass either image_url (we fetch and copy it) or image_base64 + content_type. Max 6 MB; JPEG, PNG, WebP or GIF.

Bulk version of import_recipe: fetch up to 15 recipe pages and save them to the library, optionally marking each as a favorite. Use when the owner is moving favorites from another app (Mealime, a meal kit, a recipe manager). Names without URLs are your job: search for a real recipe page first, then pass the URLs here. Per-URL failures are reported, not thrown.

Every recipe selected for a past week, newest first, with week, status, and ratings/comments. Use to avoid repeats and learn what landed.

Where the cycle stands: latest week + status (voting/selected/ordered/done), candidates with tallies, who has/hasn't voted, selected recipes, pending_feedback. Call this first.

Start a weekly cycle: store the candidate recipes (normally 10) and return numbered candidates, a ballot_text (with a {vote_link} placeholder for message_group), and each member's vote link. Re-calling for the same week_start replaces the candidates.

Append extra recipes to the current voting ballot (positions continue after the existing ones; votes are kept; 15 max). Use in response to ballot_feedback from get_current_week; open feedback is marked addressed. Follow up with message_group so voters know new options are up.

Record a member's comment about the current ballot (optionally about one candidate), e.g. relayed from a text message. Members can also do this themselves on their vote page.

Pass the owner's feedback about Agent Chef itself (a bug, a missing feature, something confusing) to the people who build it. Use when the owner says something like 'tell Agent Chef that…' or complains about the tool. Not for messages to the household.

Send a push notification, SMS/MMS or email to household members. '{vote_link}' in the message becomes each member's personal voting link. Channel 'auto' texts members with a phone and emails the rest. Providers now: {"sms":"dry-run","email":"resend","push":"web-push"} (dry-run = logged only).

Record one member's votes for the current week (replaces their earlier votes). Accepts recipe_ids or ballot positions. Unknown member names are created.

Historical ballots: per week, every candidate with vote count, voters, and whether it was selected.

Lock in the dinners. With no recipe_ids, picks the top N (recipes_per_week) by votes; a tie at the cutoff goes to the earlier ballot position and is reported under tie_break. With recipe_ids, those become the dinners exactly: any number, any household or Community recipe, on the ballot or not (off-ballot picks are added to the week). Call again to change them; an ordered week stays ordered. Moves a voting week to 'selected' and returns the shopping list.

Undo set_this_weeks_recipes: clears the winners and returns the week to 'voting'. Existing votes are kept. Use if winners were locked in too early.

One-off override of when the current ballot closes: an ISO timestamp, or extend_hours from the current deadline. Normally the deadline comes from the household schedule (vote_close_day/time); changing those via update_recipe_preferences re-syncs the current week.

Record post-cook feedback (1-5 + comment) for one member. Every member rates separately; a member's newer rating replaces their older one. Ratings never change the week's status.

Returns the shopping list for filling an online grocery cart: everything this week's selected recipes need minus what is on hand, grouped by item with quantities and which recipe needs it, plus the preferred store. Drive the browser to fill the cart; stop before checkout for approval; then call record_grocery_order.

Log the placed order and move the week to 'ordered'. Staples marked out that were bought are back in stock (listed under restocked). Purchased items don't join the pantry since they get cooked this week; set add_to_on_hand to keep them as leftovers for 7 days.