add_pantry_item
ChatGPTModifies your ChefSense pantry: adds one or more items. This will modify your ChefSense pantry. Inputs: - items: array of { name, quantity?, unit?, category?, expires_at? } Output: { added: [...], skipped: [...] }. Each skipped entry includes a reason so you can summarise failures back to the user.
add_pantry_items_bulk
ChatGPTModifies your ChefSense pantry: bulk-adds items you already extracted (e.g. from a receipt photo or a shared shopping list). When to use: if you have already extracted the line items yourself in this conversation, use this tool. If the user wants ChefSense to do the scanning (e.g. they uploaded the image to ChefSense's UI), use start_pantry_scan instead. This is a BYO-AI tool — it does NOT count against the user's ChefSense AI quota. It DOES count against the per-tool rate limit (60/min). Field shapes documented at chefsense://schema/pantry-item. Allowed units at chefsense://schema/unit. Allowed categories live in the category.enum of the pantry-item schema. Inputs: - items (required): array of { name, quantity?, unit?, category?, expires_at?, notes? } - source_hint: free-text description of what the user shared ("receipt from Whole Foods 2026-06-01"); recorded in the audit log - confidence_hints: optional per-item 0..1 confidence (parallel to items). Items below 0.5 are tagged low_confidence: true in the response so the user can review. Output: { added: [...], merged: [...], skipped: [...] }. merged = matched an existing pantry item (same normalized name + same unit) and incremented quantity instead of duplicating.
add_shopping_list_items
ChatGPTModifies your ChefSense shopping list: adds one or more items. This will modify your ChefSense shopping list. Inputs: - items: array of { name, quantity?, unit?, category?, notes? } - list_id: optional shopping list id; defaults to the household default list Output: { added: [...], skipped: [...] }.
apply_pantry_scan
ChatGPTModifies your ChefSense pantry: commits detections from a scan that's in ready_for_review to the user's pantry. Use this after get_pantry_scan returns status=ready_for_review. The detections come from get_pantry_scan; any the user doesn't want can be dropped with reject_detection_ids. Inputs: - scan_id (required) - reject_detection_ids (optional): detections to drop before applying - location_id (optional): default pantry location for detections that don't already carry one Output: { scan_id, applied: { items_created, items_merged }, rejected_count }.
ask_cooking_question
ChatGPTSingle-turn cooking Q&A answered by ChefSense AI, for questions like "can I sub butter for oil?" or "how do I know when this is done?". Use it when the user asks for ChefSense's answer. Inputs: - question (required) - recipe_id (optional): scopes the answer to a specific saved recipe; ignored if the recipe doesn't belong to the caller Counts against the user's "cooking question" AI quota — every call costs them. Don't fire it unprompted.
check_shopping_list_items
ChatGPTModifies your ChefSense shopping list: checks or unchecks items. This will modify your ChefSense shopping list. Item ids come from list_shopping_list. Inputs: - item_ids: array of item ids from list_shopping_list - checked: true to check, false to uncheck
finalize_recipe_scan
ChatGPTModifies your ChefSense recipe book: saves a recipe-scan draft as a real recipe in the user's book. Call this after get_recipe_scan returns status=draft_ready. The draft from get_recipe_scan.draft becomes the default body; pass edits to override any subset of fields (for OCR corrections the user spotted). Inputs: - scan_id (required) - edits (optional): partial overrides for { title, description, portions, category, ingredients, instructions, time, nutrition, tags }. Same field shapes as the draft. Output: { recipe_id, title }.
generate_recipe
ChatGPTModifies your ChefSense recipe book: kicks off a new AI-generated recipe and saves it to the user's book. When to use: the user wants ChefSense to come up with a new recipe (with personalization against their pantry + diet profile). If the user already has a recipe in hand (cookbook page, URL, something you wrote out yourself), use save_recipe or save_recipe_from_url instead — those are BYO-AI and won't consume their AI quota. This will count against your ChefSense AI generation quota. Inputs: - prompt (required): natural-language ask, e.g. "quick weeknight dinner using what I have" - use_pantry (default true): currently informational — pantry grounding flows through ChefSense's prompt builder regardless; tracked here for future overrides - for_member_ids: optional household member ids (depends on CHEF-139; today the user themself is always included) Generation runs asynchronously on a queue. The tool returns { generation_id, status } immediately. Poll by calling list_recipes (the latest entry will be the new recipe) or follow up with get_recipe once the user reports it appeared.
get_diet_profile
ChatGPTReturn the authenticated user's dietary preferences and disliked ingredients. Use this BEFORE suggesting or generating recipes so suggestions stay within the user's diet, and you don't propose ingredients they've already said they dislike. Output: - diets: chosen diets (e.g. vegetarian, pescatarian) - dislikes: ingredients the user has explicitly opted out of
get_household
ChatGPTReturn the people that share the user's pantry/recipes ("household"), each with their own diet profile. Use this when the user says things like "what should we eat tonight" or "what can I cook that works for everyone". Members with their own ChefSense account are tagged kind: "real_user"; profiles the user manages for someone without an account are tagged kind: "profile_stub". Diets and dislikes are only included for the caller and their profile stubs. Member ids are what generate_recipe (for_member_ids) and update_household_member accept.
get_pantry_scan
ChatGPTPoll the status of an in-flight pantry scan started with start_pantry_scan. Statuses: - pending / processing — vision pipeline still running; poll again in ~3s - ready_for_review — detections ready; call apply_pantry_scan to commit them (you can pass accept_detection_ids / reject_detection_ids) - completed — already applied - failed — see the error in the audit log Output: { scan_id, status, kind, detections: [{ id, name, quantity?, unit?, category?, confidence?, status }] }
get_recipe
ChatGPTFetch one saved recipe in full — ingredients, instructions, times, nutrition, and cover image. Pair with list_recipes to look up a recipe id first. Returns an MCP error if the recipe doesn't exist or doesn't belong to the caller.
get_recipe_scan
ChatGPTPoll the status of an in-flight recipe scan started with start_recipe_scan. Statuses: - uploading / processing — vision pipeline still running - draft_ready — draft field is populated; show it to the user and call finalize_recipe_scan to save it (optionally with edits for OCR corrections) - saved — already finalized; recipe_id populated - failed — error_message populated Output: { scan_id, status, draft?, recipe_id?, error_message? }.
iterate_recipe_answer
ChatGPTModifies your ChefSense recipe book: submits answers to follow-up questions raised by iterate_recipe_start, or polls the iteration status with an empty answers array. Inputs: - iteration_id (required): from iterate_recipe_start - answers: array of strings matching the order of questions returned by iterate_recipe_start. Pass [] to poll without submitting answers. Returns { iteration_id, status, questions?, generated_recipe_id? }. - status='awaiting_user' → more questions, ask the user - status='in_progress' → generation still running - status='success' → look up generated_recipe_id via get_recipe - status='failure' → tell the user; CHEF-149 traces will show why
iterate_recipe_start
ChatGPTModifies your ChefSense recipe book: starts a refinement loop for one saved recipe ("make it gluten-free", "halve the servings", "swap chicken for tofu"). The eventual answer creates a new version of the recipe. This will count against your ChefSense AI generation quota. When to use: the user wants ChefSense to drive the iteration — asking follow-up questions, regenerating from its own prompt. If the user has already had you rewrite the recipe yourself and just wants the result saved as a new version, use update_recipe instead (no AI quota consumed). Inputs: - recipe_id (required): id of the saved recipe to iterate on - instructions (required): what the user wants changed Returns { iteration_id, status, questions[] }. - When status='awaiting_user', call iterate_recipe_answer with the answers. - When status='in_progress', the iteration is generating; poll by calling iterate_recipe_answer with an empty answers array — or wait and check list_recipes for the new version.
list_pantry
ChatGPTList the items currently in the user's pantry / inventory. Use this when the user asks what they have on hand, or when you need item ids for update_pantry_item / remove_pantry_item. Don't call it before generate_recipe: ChefSense already grounds generation in the pantry. Optional inputs: - query: case-insensitive substring filter on item name - category: filter to a single category slug (e.g. "produce", "dairy")
list_recipes
ChatGPTList the user's saved recipe book (titles + summaries only, no full recipe bodies). Use this when the user asks "what recipes do I have", or to look up a previously saved dish before generating a new one. Optional inputs: - query: case-insensitive substring on title or description - limit: max results (1–50, default 25)
list_shopping_list
ChatGPTList the user's household shopping lists and items. Use this when the user asks what is on their shopping list or wants to inspect items before adding, checking, or removing anything. Optional input: - list_id: specific shopping list id. Defaults to the household's default list.
remove_pantry_item
ChatGPTModifies your ChefSense pantry: removes one or more items (used after cooking, or for corrections). This will modify your ChefSense pantry. Item ids come from list_pantry. Inputs: - item_ids: array of pantry item ids (from list_pantry) Output: { removed_ids: [...], skipped: [{ id, reason }] }. Items not owned by the caller are reported as skipped, not silently ignored.
remove_shopping_list_items
ChatGPTModifies your ChefSense shopping list: removes one or more items. This will modify your ChefSense shopping list. Item ids come from list_shopping_list. Inputs: - item_ids: array of item ids from list_shopping_list Output: { removed_ids: [...], skipped: [{ id, reason }] }.
save_recipe
ChatGPTModifies your ChefSense recipe book: saves a fully-structured recipe you already have in this conversation. When to use: if you've already extracted or written out a recipe (from a cookbook photo, a blog page the user pasted, or you wrote it freestyle), use this tool to save it. If the user wants ChefSense to generate a new recipe with personalization, use generate_recipe instead. This is a BYO-AI tool — it does NOT count against the user's ChefSense AI generation quota. Field shapes documented at chefsense://schema/recipe. Inputs: - title (required) - summary - ingredients (required): array of { name, quantity?, unit?, notes? } - instructions (required): array of strings, in order - portions, prep_time, cook_time - tags, category - source_hint: free-text origin ("cookbook page", URL, "AI-generated")
save_recipe_from_url
ChatGPTModifies your ChefSense recipe book: saves a recipe you fetched and parsed from a URL. When to use: the user shares a recipe URL. You fetch and parse the page yourself, then call this tool with both the URL and the structured fields. ChefSense does NOT refetch the URL — we trust your parse. If the user wants a new recipe generated from scratch (rather than saving one they already have), use generate_recipe instead. This is a BYO-AI tool — it does NOT count against the user's ChefSense AI generation quota. Behaviour: - If a recipe with the same url already exists for this user we return the existing recipe_id instead of duplicating. The response includes deduplicated: true. - Otherwise behaves identically to save_recipe, plus stores the URL as source_url on the recipe so it links back. Inputs are the same as save_recipe plus a required url.
search_recipes
ChatGPTFreeform search over the user's saved recipe book. Returns the same summary shape as list_recipes. This is search, not generation — it never consumes AI quota. Use generate_recipe (when available) for a fresh recipe. Inputs: - query (required): natural language or keywords - scope (optional): mine (default; the user's recipe book). all (cross-account global search) is not implemented yet — the tool returns an MCP error rather than silently degrading. - limit (optional): max results (1–50, default 25)
start_pantry_scan
ChatGPTModifies your ChefSense pantry: kicks off a vision scan of an image (pantry shelf photo or receipt) and queues it for review. When to use: the user wants ChefSense to read the image — i.e. they want our scanner / categoriser / unit normaliser applied. If you have already extracted the items yourself from the image in this conversation, use add_pantry_items_bulk instead (cheaper, no AI quota burned). Image wire format documented at chefsense://schema/recipe via ADR 0004 — base64 + media_type (preferred) or image_url (fallback for big receipts). Inputs: - image_base64 + media_type (preferred), OR image_url - kind: "shelf" (default) or "receipt" - location_id: optional pantry location to assign detections to Returns { scan_id, status: "pending" | "processing" } immediately; poll with get_pantry_scan and commit with apply_pantry_scan.
start_recipe_scan
ChatGPTModifies your ChefSense recipe book: kicks off a vision scan of a recipe image (cookbook page, handwritten card) and parses it into a structured draft for review. When to use: the user wants ChefSense to read the image and extract the recipe. If you have already extracted the recipe yourself in this conversation, use save_recipe instead (cheaper, no AI quota burned). If the user dropped a URL, use save_recipe_from_url. Image wire format follows ADR 0004 — base64 + media_type (preferred) or image_url (fallback). Inputs: - image_base64 + media_type (preferred), OR image_url Returns { scan_id, status: "processing" } immediately; poll with get_recipe_scan and commit with finalize_recipe_scan.
undo_last_change
ChatGPTModifies your ChefSense data: reverses the most recent change made through this connector to a pantry item, recipe, diet or disliked ingredient (including a household member's diets and dislikes). Shopping list changes can't be undone. A "change" is everything one tool call did, so undoing a household member update restores all of its diets and dislikes at once. Call it again to undo the change before that. When to use: the user says "wait, undo that" or "scratch that last change". Inputs: - revision_id (optional, rarely needed): undo only that one revision. Omit it to undo the most recent change. Semantics: - create → delete the row - update → restore the prior column values - delete → re-insert the row from the snapshot (limited: any cascade-deleted children are NOT restored; flagged in warnings) Returns { revision_id, subject_type, subject_id, op, reverted_count, warnings[] } for the most recent revision reverted, where subject_type is one of recipe, pantry_item, diet or dislike.
update_diet_profile
ChatGPTModifies your ChefSense diet profile: adds or removes diets and ingredient dislikes. This will modify your ChefSense diet profile, which changes every future recipe generation. Inputs accept either ids (preferred, from get_diet_profile) or case-insensitive names. Unknown items appear in the returned skipped array with reason — they are NOT silently ignored. Output: the updated diet profile (same shape as get_diet_profile) plus a skipped[] array.
update_household_member
ChatGPTModifies your ChefSense household: patches a member's name, diets, and ingredient dislikes in one call. When to use: the user said something like "Dana is doing low-FODMAP now and hates cilantro" and you've worked out the change with them. Single call instead of three separate update_diet_profile invocations. Field shapes documented at chefsense://schema/household-member, diet values at chefsense://schema/diet. Semantics: - Diets / dislikes are SET to the provided list, not appended. If the user wants to add one, call get_household first, then pass the union back. - Users can edit themselves. Any household member can edit fake household placeholders, but not invited real collaborators. - Unknown diet / ingredient values appear in warnings (not errors). If any value in a preference field is unknown, that entire field is skipped and existing preferences are preserved. Inputs: member_id (required), change_summary (required), plus any subset of name, diets, dislikes.
update_pantry_item
ChatGPTModifies your ChefSense pantry: patches quantity / unit / expiry / category / notes on an existing item. This will modify your ChefSense pantry. Use list_pantry first to look up item_id. Inputs: item_id (required) plus any of quantity, unit, category, expires_at, notes, name. Omitted fields are left alone.
update_recipe
ChatGPTModifies your ChefSense recipe book: saves a partial edit to an existing recipe (made gluten-free, halved the servings, swapped an ingredient, fixed a typo in step 4, …). Creates a new VERSION of the recipe — the prior version is preserved. When to use: the user has had you rewrite the recipe in this conversation and now wants the result saved. If they want ChefSense to drive a guided iteration (asking follow-up questions), use iterate_recipe_start instead. This is a BYO-AI tool — it does NOT count against the user's ChefSense AI generation quota. Field shapes documented at chefsense://schema/recipe. Semantics: - Partial — fields not in the request are left untouched (copied from the latest version). - Arrays (ingredients, instructions) are replaced wholesale when supplied; we don't try to diff item by item. - change_summary is required and recorded as the version's iteration request so the edit history reads sensibly. Inputs: recipe_id, change_summary, plus any subset of title, summary, ingredients, instructions, portions, prep_time, cook_time, tags, category. Returns { recipe_id, version_number, updated_fields[], warnings[] }, where recipe_id is the new version's id.
update_recipe_image
ChatGPTModifies your ChefSense recipe book: sets a recipe's cover image from an image that already exists, without generating a new one. When to use: the user pointed at an image, generated one themselves, or you already produced one via your image-gen capability. To have ChefSense generate a fresh image, the user can regenerate it from the recipe page on chefsense.ai. This is a BYO-AI tool — it does NOT count against the user's image-generation quota. Inputs: - recipe_id (required): id from list_recipes / get_recipe - Exactly one of: - image_url: ChefSense fetches and mirrors. Don't pass URLs you don't trust the user has rights to. - image_base64 + media_type: inline bytes. Capped at ~14 MB encoded (same constraint as scan tools in ADR 0004). - alt_text: optional accessibility text (currently informational until the recipe-image schema gains an alt-text column) - source_hint: free-text origin recorded in the audit trail We mirror the bytes to ChefSense's storage rather than hotlinking, so the image survives the source going away. EXIF stripping + canonical resizing land via CHEF-167's shared helper.
