# Assist With Food — for your AI (guide 1.1.2)

Assist With Food assists your AI, so it can assist the person with every aspect of food. The person decides; you research, interpret and create; Food stores, connects, versions and shows.

## Start

Connect: https://www.assistwithfood.com/mcp (Streamable HTTP). Sign in as the person and choose Allow; that completes setup with full access to all current and future Food tools and no end date by default. Connections do not expire unless the person chooses an end date at /settings/ai; using or signing in never moves that date. Ordinary reads and writes work at once. If the person chose approval-first or erased their Food data, the connection waits for their approval at https://www.assistwithfood.com/settings/ai.
Every record you save carries your name as its author. You never archive, restore, delete or export anything; those are the person's own clicks. Nothing you do through Food reaches the outside world: no ordering, reserving, paying, contacting, or operating an appliance.
After a Food release, start a new conversation so your client loads the current tools.

## Vocabulary

- Food: what something is (a general type, one place's own version, or a product). Kinds (a burger is a kind of sandwich) and components (made of a patty and a bun) are separate links.
- Place, offering, observation: where food is sold, what it sells, and a dated price or availability seen there — researched (with its Source) or lived.
- Recipe → Version → cook (an Experience) → next Version. A version never changes once saved; an adaptation is a new version.
- Experience: something that happened on a date. A visit groups the things eaten there.
- Comparison: a question with candidates. An order missing a priced line is incomplete and never ranked.
- Refs: every record has an opaque ref like food_… or place_…; use the refs Food returns, never invent one.

## Normal job

The person: "We had the carne asada and two horchatas at Rincon Market tonight, $18.50."
1. food_search text "Rincon Market", kinds place; food_search text "carne asada".
2. food_save_experiences, one item: operationKey "rincon-2026-10-06:visit", experienceKind visit, occurredAt 2026-10-06, placeRef the place, paid known 1850 USD, entries for each dish.
3. Reply with what you saved and the links Food gave you.
Operation keys are yours: make each one unique per change ("<what>-<date>:<part>"). Sending the same item with the same key again is safe — it replays the saved result.

## Discovery

food_search before creating; food_find to page through one kind by filter (follow nextCursor until it is null); food_get_records to read up to 20 records with their links. Lists say when they are truncated; nothing is silently cut.

## Writes

Every add/edit tool takes items (1–20), each with its own operationKey and its own outcome. To change a record, send its ref with the expectedVersion you read; if it changed since, Food refuses with stale_version rather than overwrite. A refused item saved nothing and did not spend its key: fix what it names and send it again with the same key.

## Media

Photos, PDFs (menus, receipts, labels) and voice notes go into Food in two steps, and only the second saves anything.
1. food_begin_upload: declare each file's name, type, exact size and SHA-256. For a set (a grocery haul, twenty menu photos) give set with expectedFiles: item n fills slot n, and later calls name setRef and setSlot. The reply's uploadUrl field carries each address, on Food's own host; PUT the exact bytes there. A file over 8 MB comes as parts, each with its own uploadUrl.
2. food_finish_upload with the sessionRef: Food verifies every byte and seals the file, with your name on it, on the records you named. Resending either step with the same item is safe.
food_get_media_batch shows you the files themselves. It never refuses for size: it serves a smaller copy and says which, or a short-lived link when nothing fits. food_attach_media puts a file on more records; food_set_media_captions captions it. Originals, taking a file off a record, and deleting it are the person's.
Food does not fetch files from a web address for you: download it yourself and upload the bytes. If you cannot send bytes from where you run, say so plainly; do not imply you have seen or saved a picture.

## Recovery

Every refusal from Food starts "Food refused:" and carries a code (INVALID_INPUT, REFUSED, NOT_FOUND or INTERNAL_ERROR), what to do next, and a request id to quote. It also names the layer that blocked you:
- sign-in (HTTP 401): your client needs to sign in again.
- Food's permission (HTTP 403): the connection is revoked, expired, waiting for approval, or narrowed. Only the person changes that, at /settings/ai; food_manage_connection describes it.
- the client's file access or network: a failure with none of Food's words came from your own client, and nothing reached Food.

## Working method

1. Orient once. Call food_get_workspace_overview at the start: the person's Preferences, their Queue, and what Food does not hold yet.
2. Find before creating. food_search for the food, place and recipe first. One product is one Food; a similar name is a question for the person, not a merge.
3. Answer now, save as you go. Give the useful answer first with its uncertainty. Save a sparse record immediately; deepen it as research arrives.
4. Batch. A restaurant visit with four dishes is one food_save_experiences item with four entries. Twenty grocery prices are one food_save_observations call.
5. Put facts where they belong. What a food is goes on the Food; what a place charges goes on its offering as a dated observation; what happened tonight goes on an Experience; long research goes on the Library.
6. Date and source every price. A price without its date and source is a rumour. A price you did not find is unknown, not zero.
7. Respect strict rules. An allergy on a Person is a hard constraint. Nothing in Preferences softens it.
8. Suggest; do not decide. A ranking is a proposal. The person's choice and what they actually did are theirs to record.
9. Tell the person what you saved. Name the records and give the links Food returns.

## Tools

## Start and orient

- food_get_workspace_overview (read): Start here once per conversation. Returns how many of each record the person keeps (counted up to 100, then "100+"), their adopted Preferences to work by, what is waiting in their Queue, and what Food does not hold yet so you do not guess it.
- food_list_queue (read): What the person has asked for, a page at a time, newest first: waiting, working or answered, or only the items that need their input. Follow nextCursor until it is null.
- food_manage_connection (write): See what this AI connection may do, or give some of it back. action describe: abilities, expiry, and the person's settings link. action narrow: turn off abilities this connection holds (drop read or write). action disconnect: end this connection entirely. You can only ever narrow; widening, renewing and reconnecting are the person's, at the settings link.

## Find before creating

- food_search (read): Find records by name in the person's own words, across every kind or the kinds you name. Use it before creating anything: one product is one Food, and a similar name is a question for the person, not a merge.
- food_find (read): Page through one kind of record, newest first, optionally narrowed by one filter. Filters by kind: food (identity), place (placeKind), resource (resourceKind), offering (placeRef or targetRef), observation (offeringRef), recipeVersion (recipeRef), experience (visitRef, placeRef, foodRef or occasion), comparison (subjectKind), list (none), queueItem (state), libraryItem (shelf), person (status), preference (status). Follow nextCursor until it is null.
- food_list_library (read): The Library's shelves, a page at a time: research (long findings), sources (where things came from), instructions (the person's research approaches and prompts). Read a whole item with food_get_records.

## Read in depth

- food_get_records (read): Read up to 20 records by ref, each with what it links to: a Food's kinds, components and recipes; a Place's offerings; an offering's latest dated prices; a Recipe's current versions; a version's ingredients and equipment; a visit's entries; a Comparison's candidates and price ranking; a List's entries. Every record carries its author (person or which AI) and version. Missing refs, and somebody else's, come back as not found.

## Record the food world

- food_save_foods (write): Create Foods, or change them by ref with expectedVersion. A Food takes a name and nothing else; Food works out whether it is a general type, one place's own version (originPlaceRef) or a product (brand) — never both. One product keeps one record however many stores sell it: record each store as an offering. Link kinds and components with food_save_links. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_save_links (write): Say what kind of food something is (kind_of), what it is made of (made_of), or which recipe makes it (recipe_for) — three different links, never folded into one — or unlink one. Neither graph may loop back on itself. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_save_places (write): Create Places — anywhere the person gets food — or change them by ref with expectedVersion. What a place sells is an offering (food_save_offerings); a visit is an experience. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_save_offerings (write): Say that a Place sells a Food or Resource, under its own label. What an offering sells is fixed once saved; an edit changes only its label and serving note. Prices go on it as observations. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_save_observations (write): Record dated prices, availability and menu facts — twenty grocery prices are one call. Every price is dated and sourced: researched evidence names its Source (food_save_sources); lived evidence is what the person met. A price nobody found is state unknown, never zero. New evidence never erases old; an edit corrects one reading. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_save_resources (write): Create or change Resources: the kitchen's cookware, appliances and tools. Equipment is never an ingredient. Shopping for one belongs to Assist With Buying. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_save_sources (write): Create or change Sources: the menu, label, listing, receipt, person or publication a fact came from. Researched evidence must name one. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).

## Cooking

- food_save_recipes (write): Create a Recipe — the continuing identity of a preparation — or change its title and note. Ingredients and steps live on its versions (food_save_recipe_versions). Link it to the Food it makes with food_save_links. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_save_recipe_versions (write): Add a new Version of a Recipe, or correct a version's label, state, yield or note. A version's ingredients and equipment never change once saved: an adaptation is a new version that supersedes the old, so the tested one is always still there. An AI adaptation is proposed until cooked. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).

## What was eaten

- food_save_experiences (write): Record what actually happened: a visit or meal with its food entries in one item (a dinner where two people ate two dishes is one visit with two entries), a cook, a purchase or a tasting. An edit changes the date, price paid, company, occasion and note. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).

## Decide with the person

- food_save_comparisons (write): Set up a Comparison — foods, a whole order at each place, recipes, places or equipment — with its criteria and candidates, or add candidates to one. An order missing a priced line shows as incomplete and is never ranked. The person decides; read the ranking back with food_get_records. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_suggest_preference (write): Propose a Preference for the person to adopt or decline. Only they write their Preferences; a proposal is guidance, never permission, and never softens an allergy. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).

## Organize

- food_save_lists (write): Create Lists (a dated List is a plan: this week's dinners), change them, and add, tick or remove entries. Removing an entry keeps it as history. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_save_library_items (write): Put long research on the Library's shelves (research, sources, instructions), edit it, or take it off a shelf and back. Put the short fact on its record; link the long version here. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_save_people (write): Record the people the person feeds and their strict food facts. A Person you record stays proposed until the person confirms them. An allergy is strict: nothing softens it, and you cannot remove one. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_save_topics (write): Create or change Topics: techniques, cuisines and food science, each a short summary with links. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).

## Photos and files

- food_begin_upload (write): Step 1 of 2 for photos, PDFs (menus, receipts) and voice notes. Limits: photos (JPEG, PNG, WebP) 100 MB and 300 megapixels, PDFs 50 MB, voice notes 25 MB; no video. Each item's reply gives uploadUrl, on Food's own host: PUT the exact bytes there with the file's Content-Type. Over 8 MB, parts come instead, each with uploadUrl and a byte range, sent with the part's SHA-256 in X-Food-Part-SHA256. Then food_finish_upload. Addresses last 6 hours; resending an item resumes it. A file Food already holds comes back ready. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_finish_upload (write): Step 2 of 2, the only way a file is saved: once every byte is PUT, Food checks length, SHA-256, type and that it opens, then saves it with your name on it, on the records you named. Finishing again replays the mediaRef. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_get_media_batch (read): See photos, PDFs and voice notes themselves, as images, audio or an embedded PDF. Name mediaRefs, recordRef or setRef; follow nextCursor until it is null. Never refused for size: over budget, Food serves a smaller copy and says which (served), or a link that works for 5 minutes. Originals are the person's. Food does not crop or tile photos.
- food_attach_media (write): Put a file on another record: a menu photo on the Place and the Comparison, a receipt on the visit. Attaching twice is harmless. Taking a file off, or deleting it, is the person's. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_set_media_captions (write): Set or change a file's caption, with the expectedVersion you read. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).

## Queue work

- food_add_to_queue (write): When the person asks for something mid-conversation that should wait, add it to their Queue, marked as added by you. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).
- food_update_queue (write): Take a Queue item: mark it working, answer it (name the records you saved), or ask the person for what you need. Replies with one outcome per item: saved (ref, version, link) or refused (code, field, what to do).