add_stock
ChatGPTAdd lots to the user's stock, for what they bought or received: each lot is an ingredient id a tool returned, its quantity and unit, and the expiry date, cost, supplier or lot number when the user gave them. All lots are added or none. Ask for a quantity or unit the user left out rather than guessing it.
advise_formulation
ChatGPTFor a formula whose metrics sit outside their target bands, report which of them the CURRENT ingredients can still reach (with the achievable range) and which they cannot, plus the classes of ingredient that would unlock the unreachable ones. Accepts a saved recipe (recipe_id) or an ad-hoc ingredient list (calculator_type + ingredients). Use it when adjusting quantities has stopped moving a metric toward its band — it tells you whether the formula is missing a component rather than mis-proportioned. It proposes no recipe and picks no trade-off; metrics already in band are omitted.
analyze_recipe
ChatGPTComprehensive recipe analysis: metrics + quality score (0-100 with dimension breakdown) + diagnosed issues + formulation-rule compliance + concrete suggested improvements. Pass a saved recipe_id or the recipe name. Shows the user nothing; to show the analysis as a scorecard, call show_card with kind=quality.
create_ingredient
ChatGPTCreate a custom ingredient in the user's library. Composition values are PERCENTAGES by mass (0-100); carbohydrate_pct EXCLUDES fibre (EU convention) and alcohol_pct is ethanol mass fraction, not %ABV. water_pct, fat_pct, carbohydrate_pct and protein_pct are REQUIRED so the calculators can use it. Fill every field you can source for complete data. Use only when no existing ingredient fits: resolve_ingredients reported needs_create, or search_ingredients found no suitable match.
create_recipe
ChatGPTCreate and SAVE a new formula authored in the conversation. Provide ingredients by ingredient_id (from resolve_ingredients) or by name (auto-resolved); unresolved names are reported so you can choose a candidate or call create_ingredient, then retry with ingredient_id; when create_ingredient is not available on the caller's plan, import_recipe with mode=confirm creates the needed custom ingredients instead. Otherwise use import_recipe only when transcribing ONE external recipe; whole files are imported in the Formul.io app. Or set from_recipe_id to clone an existing recipe. To MODIFY an existing recipe, use update_recipe (optionally with save_as_version=true) instead — only clone when you genuinely want a separate recipe.
delete_collection
ChatGPTPermanently delete a recipe collection (the recipes themselves are NOT deleted). Requires confirm:true.
delete_recipe
ChatGPTPermanently delete a recipe. Requires confirm:true — without it the call is refused so deletions are never accidental.
delete_recipe_note
ChatGPTDelete a note from a recipe. Requires confirm:true so deletions are never accidental.
find_substitutes
ChatGPTFind ranked substitute ingredients for a given ingredient_id, ranked by the same category and water/sugar/fat/cocoa composition score as the recipe picker, with functional differences lowering the score. The optional criteria NARROWS the candidate set (it filters, it does not re-rank): 'similar' (default — no filter, pure macro/category proximity), 'vegan', 'lower_water', 'lower_sugar', 'lower_fat'. Each candidate carries a ready-to-run suggested_change: pass it straight to simulate_changes to preview the swap. The preview replaces ALL rows with that ingredient_id. update_recipe does NOT take change objects: to APPLY the same swap read get_recipe, replace ingredient_id with substitute_id on ALL matching rows, preserve every row's entry_id, quantity_g, phase, stage_id, note, incorporation_mode, excluded and locked, and send the whole list as update_recipe.set_ingredients. Each candidate comes back with identity, macros and allergens; pass view="full" for the complete composition record including its reference source. Results include the caller's is_favorite and is_favorite_brand flags: for unspecified new choices prefer suitable favorite ingredients, then favorite brands; preserve explicit identities and constraints. Favorites are managed only in the app.
get_calculator_guide
ChatGPTReference for a calculator type: optimal metric ranges, a metric glossary (what each metric means + how to improve), and professional formulation rules. Call before creating/optimizing a recipe. Pass style to get ranges for the product style you are formulating — they differ sharply between styles. Returns description + optimal ranges + the shelf-life class lines + formulation rules + settings schema by default; pass section for one slice — 'overview', 'rules', 'settings', 'metrics' (the metric glossary), 'dag' (the process-graph template) — or 'all' for everything.
get_collection
ChatGPTGet a recipe collection with its member recipes. For your own collections (collection_id) it also returns the collection's user-written notes and preferences (instructions field) so they can be taken into account. Provide collection_id (yours) or slug (public).
get_recipe
ChatGPTGet recipe with full ingredient composition and metrics. Use first to understand current state. Returns a slim summary (key metrics) by default; pass view=full for the complete calculator_metrics blob. Shows the user nothing; to show the recipe as a card, call show_card with kind=recipe.
get_recipe_dag
ChatGPTRead a recipe's current multi-stage process DAG (nodes, dependency edges, params, source notes and chef instructions) with authoring annotations: locked physics-core nodes, required physics types, freedom model, and executability. Call before set_recipe_dag to know the base to deviate from — each node is returned in the shape set_recipe_dag accepts, so an unchanged node can be written back verbatim (node_id / is_physics_core / locked are read-only annotations and are ignored on write; keep id so the stage keeps its notes and pins). The response's graph_token is the compare-and-set baseline for set_recipe_dag.expected_graph_token. This read persists nothing.
get_recipe_metrics
ChatGPTCompute metrics (water activity, shelf life, nutri-score, composition %, calculator-specific) for a saved recipe (recipe_id) OR an ad-hoc ingredient list (calculator_type + ingredients; nothing is saved). Each metric comes back with its target band for this calculator and style, and how far outside it the value sits, so you do not need get_calculator_guide to interpret the numbers. Note lower_is_safer bands (water activity, free water): below the floor is a texture or yield miss, not a safety problem, and adding water to close it makes the product LESS stable. Shows the user nothing; to show the final metrics as a card, call show_card with kind=metrics. To compare several formulas at once, use simulate_changes instead of calling this per variant.
get_shopping_list
ChatGPTOne of the user's shopping lists with an openable url and its items: what is still to buy and what is checked off. Get list_id from list_shopping_lists. Returns up to 100 items starting at offset; when more_items is above 0, call again with offset raised by the number of items returned.
import_recipe
ChatGPTImport ONE external recipe you already parsed into structured fields. mode=preview resolves ordered ingredient lines against the library and writes nothing. mode=confirm atomically creates any required custom ingredients and saves the source description, phases, line notes, recipe notes, and optional process DAG. Always transcribe source step-by-step instructions into notes[] as Markdown; do not discard them. Use create_recipe for a formula authored in the conversation. For a file with several recipes, import each recipe you read from it with its own call; the Formul.io app imports whole files.
inventory_summary
ChatGPTIngredients running low (below the user's reorder point) and stock batches expiring within expiring_within_days (default 7). Quantities are in each ingredient's tracked unit. low_stock_total and expiring_total count every row, including those left out of a long answer.
list_collections
ChatGPTList recipe collections. scope=mine (default) lists the user's collections; scope=public browses shared collections.
list_recipe_notes
ChatGPTList the saved notes (caveats / tips / rationale) on a recipe, pinned first. Optionally filter by note_type. Paginated like the other list tools: page/limit (default 20, max 50), with total, has_more and next_page.
list_recipe_versions
ChatGPTList a recipe's saved versions and whether the current state is already saved. Use before any version-related edit so recipe count is never confused with version history. Hidden versions are omitted unless include_hidden=true. Saved-state metadata includes hidden history. Returns compact metadata only, newest first; full snapshots, compare, and restore are not exposed.
list_recipes
ChatGPTList the user's recipes with optional filters (calculator type, tags, quality grade, free-text search, public/private) and sorting. Use this first to find a recipe_id.
list_shopping_lists
ChatGPTThe user's shopping lists, newest first, each with an openable url and up to its first 30 items: what is still to buy and what is checked off; more_items counts the rest. Omit status to see every list: a new list stays a draft until the user starts shopping, so "my shopping list" is usually a draft. For every item of one list, call get_shopping_list.
list_stock
ChatGPTWhat the user has in stock: each ingredient with its total across lots, in the unit it is tracked in, the number of lots, the nearest expiry date and whether it is below its reorder point. Sorted by name. search narrows to names containing the words; low_only to ingredients running low. total counts every match; more counts those after this page (use offset for the next one).
resolve_ingredients
ChatGPTResolve a batch of free-text ingredient names to library ingredient_id values in one call. Call it first whenever you know which ingredients a formula needs (for create_recipe, update_recipe, simulate_changes and the other tools that take ingredient_id), with every name at once, instead of one search_ingredients per name. Each entry comes back as matched (unique product identity: exact name, synonym or SKU), alternative (review the candidates; a name that only names a group, e.g. "sugar", never binds a group member), needs_create (no row is named by the whole name), or incomplete (search failed; do not create a duplicate). Nearest rows are similar names, never matches: match.weak is true because the row carries only part of the name (another percentage or line, e.g. "Sao Palme 75%" for "Sao Palme 60%") or only its meaning. Compare their composition and allergens with the named product and never put one in a recipe without the user's confirmation; otherwise create the ingredient. Rows that share only a generic word ("paste", "cream") or are of another type than the name says are not offered. Each candidate's match.kind says what evidence found it (exact, synonym_exact, sku, prefix, taxonomy, fuzzy_name, semantic; nearest rows add partial with matched_words). Exact named products remain strict. Use actual candidate composition. For composition details or a constrained selection, use search_ingredients (mode=selection). Results include the caller's is_favorite and is_favorite_brand flags: for unspecified new choices prefer suitable favorite ingredients, then favorite brands; preserve explicit identities and constraints. Favorites are managed only in the app.
save_collection
ChatGPTCreate a recipe collection (omit collection_id) or update one. Set instructions to store user-written project preferences with the collection. Can add/remove member recipes. A new collection is private; its visibility is changed only in the Formul.io app.
save_recipe_note
ChatGPTSave a caveat / tip / rationale note on a recipe (e.g. 'this ratio works better because…', 'watch this stage'). Omit note_id to create (body required). Pass note_id to update: only the fields you send change — an omitted note_type, is_pinned or anchor keeps its stored value; send stage_id: null or recipe_ingredient_id: null to clear the anchor. Optionally anchor to a stage_id OR a recipe_ingredient_id.
search_ingredients
ChatGPTSearch ingredients (the user's custom ones + the global library) by product name, SKU, canonical brand/aliases, category, taxonomy or numeric characteristics in any dictionary-supported language. Use it to explore or filter (category, characteristics, dietary flags) and to read composition; to turn names you already know into ingredient_id values, call resolve_ingredients once with all of them instead. Match metadata distinguishes exact identity, recommendations and alternatives; rows with match.weak are similar names listed after the named rows (another percentage or line, or only a shared word or meaning), never the product asked for. General numeric requests allow ±5%, capped at ±2 percentage points; strict values and ranges are not expanded. Returns a light row by default (id, name, manufacturer, macros, allergens, vegan flag); pass view=full to add carbohydrates, the reference-data source and the custom flag. When nothing matches the catalog, also returns reference_candidates from the USDA/CIQUAL nutrition databases (full composition, no id yet) — pass their fields to create_ingredient to add one to the user's collection. Results include the caller's is_favorite and is_favorite_brand flags: for unspecified new choices prefer suitable favorite ingredients, then favorite brands, and favorites win within the allowed numeric range; preserve explicit identities and constraints and always keep actual composition. Favorites are managed only in the app.
set_recipe_dag
ChatGPTAuthor or replace a recipe's multi-stage process DAG. Each stage is a node (compose/heat/mix/gel/aerate/cool/rest/split/join/note) with params, optional source description/notes/chef instructions, an optional ingredient_set_ref, and depends_on (upstream sort_orders). Fork-join branches are supported. For fixed calculators the physics tail (water-activity/shelf-life/rheology) is preserved and auto-grafted if omitted; Custom Recipe is freeform. The candidate is validated and dry-run before persisting. Use get_calculator_guide.dag_template + get_recipe_dag first. Pass get_recipe_dag's graph_token as expected_graph_token: the write is then refused if the recipe's process changed since you read it (re-read and retry). Keep each existing node's id so its notes and ingredient pins stay anchored; omit id for new nodes.
show_card
ChatGPTShow the user one result as a visual card. The other tools show nothing, so work with them and call this once, for the result the user should see — every call draws a card. kind=recipe: a saved recipe (recipe_id or name). kind=metrics: its metrics, or an ad-hoc formula's (calculator_type + ingredients). kind=comparison: scenarios against a baseline, the same arguments as simulate_changes. kind=quality: a saved recipe's quality scorecard. Returns the same summary as the tool behind the card.
simulate_changes
ChatGPTEvaluate MANY formula variants in ONE call, without saving. Give a baseline — a saved recipe (recipe_id) or an ad-hoc ingredient list (calculator_type + ingredients) — plus named scenarios, and get each scenario's metric deltas against it, with the target bands they are judged by. This is the tool for iterating on a formula: put every candidate in one call's scenarios array rather than calling get_recipe_metrics once per candidate. Shows the user nothing; to show the final comparison as a card, call show_card with kind=comparison and the same arguments.
stock_check_recipes
ChatGPTCan these recipes be made from current stock? Give recipe_ids or collection_id, not both. Each recipe's status (ready, shortfall, no_ingredients, unit_mismatch, error) is for that recipe made ALONE. combined is for all of them made TOGETHER: each ingredient's total demand against the same stock; combined.ready is true only when every requested recipe was checked and the stock covers them all at once. Use combined for "can I make all of these / the whole collection". Quantities in grams for batch_quantity batches (default 1). Recipes beyond the first 20 come back in unchecked_recipe_ids. A long answer leaves rows out and counts them in more_recipes and more_unchecked; by_status and combined always cover every checked recipe. One call answers "what can I make"; do not call it once per recipe.
update_ingredient
ChatGPTUpdate fields of one of YOUR custom ingredients (search_ingredients view=full marks them is_custom: true). Only supplied fields change; use null to reset a nullable value. Fields with canonical derivation may be recomputed instead of staying empty. Zero, false, and an empty string are explicit values. Unknown and protected fields are rejected. Percentages are by mass (0-100). Global catalog ingredients cannot be edited.
update_recipe
ChatGPTUpdate a saved recipe IN PLACE: any of name/description/settings/tags, and optionally replace the full ingredient list (set_ingredients). Preserve each retained row's entry_id from get_recipe, including when changing its ingredient_id, to keep its identity, permissions and attached notes. Rows without entry_id are new rows. Preserve stage_id, incorporation_mode, note, phase, excluded and locked when resending the list. Omitted recipe fields are unchanged. Set save_as_version=true to save the RESULTING state as the next version; with no change fields it snapshots the current state. Pass expected_revision (the revision get_recipe returned) so the update is refused instead of overwriting an edit saved since you read the recipe. Use list_recipe_versions before version-related work.