ChefSense

Return 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 `id`s are what `generate_recipe` (`for_member_ids`) and `update_household_member` accept.

get_household

Poll 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_pantry_scan

Poll 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? }`.

get_recipe_scan

List 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_pantry

List 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_recipes

List 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.

list_shopping_list

Modifies 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_pantry_item

Modifies 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 }] }`.

remove_shopping_list_items

Modifies 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

Modifies 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`.

save_recipe_from_url

Modifies 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 }`.

finalize_recipe_scan

Modifies 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_pantry_scan

Modifies 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`.

start_recipe_scan

Freeform 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)

search_recipes

Modifies 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.

iterate_recipe_start

Modifies 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`.

undo_last_change

Modifies 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_household_member

Modifies 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_pantry_item

Modifies 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

Modifies 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_diet_profile

Modifies 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.

update_recipe_image