Recipes tools

Every tool in this module, with its full description, parameters, and return value. All of them require the module to be active first. See the Recipes overview for how to turn it on.

CRUD

Core tools

Create, read, update, and delete entries. Every module has exactly these four.

recipes_add_entry

Add a recipe to the user's Recipes / Module module. Requires the module to be active — see create_database.

Parameters

Name	Type	Required	Notes
recipe	string	Yes
ingredients	string	No
instructions	string	No
rating	number	No	Rating on a 1-5 scale.
last_cooked	string	No	ISO date, e.g. 2026-08-20
servings	number	No	How many portions this recipe makes. Used by recipes_log_as_meal to divide totals per portion.

Returns

The created entry as JSON, including its id.

recipes_list_entries

List entries in the user's active Recipes / Module module.

Parameters

Name	Type	Required	Notes
limit	number	No	Max entries to return (default 100, max 500).

Returns

Every entry in the active database, as a JSON array.

recipes_update_entry

Update fields on an existing Recipes / Module entry.

Parameters

Name	Type	Required	Notes
entryId	string	Yes
recipe	string	No
ingredients	string	No
instructions	string	No
rating	number	No	Rating on a 1-5 scale.
last_cooked	string	No
servings	number	No	How many portions this recipe makes.

Returns

The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.

recipes_delete_entry

Delete an entry from the user's active Recipes / Module module.

Parameters

Name	Type	Required	Notes
entryId	string	Yes

Returns

The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.

Specialized

Purpose-built tools

Shortcuts and queries shaped around how Recipes is actually used, so your agent doesn't have to fetch every entry and filter them itself.

recipes_attach_photo

Attach a photo to an existing Recipes / Module entry (replacing any photo already on it). If you have the image's raw bytes, pass photo_base64. If the user attached the image in a chat client (e.g. claude.ai), you cannot read its bytes: call this WITHOUT photo_base64 to get a one-time upload link, and give that link to the user so they can upload the photo themselves. The link expires in 30 minutes. Photos are stored privately; the returned viewPath is only viewable signed into the connacto web app as this user.

Parameters

Name	Type	Required	Notes
entryId	string	Yes	ID of the Recipes / Module entry to attach the photo to.
photo_base64	string	No	The photo, base64-encoded (no data: URI prefix). Omit when you cannot read the image bytes — the tool then returns an upload link for the user instead.
photo_content_type	image/jpeg \| image/png \| image/webp \| image/heic	No	MIME type of the photo, if photo_base64 is set. Defaults to image/jpeg.

Returns

JSON with a private viewPath when photo_base64 was given, or an uploadUrl to hand the user when it was not.

recipes_top_rated

List the highest-rated recipes in the user's active Recipes / Module module, ordered by rating descending (unrated recipes sort last).

Parameters

Name	Type	Required	Notes
limit	number	No	Max number of recipes to return (default 5)

Returns

The top-rated recipes as a JSON array.

recipes_log_cooked

Convenience tool for 'I made this again' — records the date a recipe was last cooked without a full update_entry round-trip.

Parameters

Name	Type	Required	Notes
entryId	string	Yes
date	string	No	ISO date, e.g. 2026-08-16. Defaults to today.

Returns

The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.

recipes_add_ingredient

Add a line-item ingredient to an existing recipe in the user's active Recipes / Module module. Resolves the ingredient against the foods catalog automatically (by ingredient text or an explicit food_id) so recipes_log_as_meal can compute real nutrition later. An unresolved ingredient is still saved — it just won't contribute nutrition when the recipe is logged as a meal.

Parameters

Name	Type	Required	Notes
recipeEntryId	string	Yes	ID of the recipe (from recipes_add_entry/list_entries) to add this ingredient to.
ingredient	string	Yes	Ingredient name, e.g. 'chicken breast' or '2% milk'.
quantity	number	No	Amount used, e.g. 200.
unit	string	No	Unit for quantity, e.g. 'g', 'oz', 'cup'. Only recognized mass units (g/kg/oz/lb) scale automatically.
food_id	string	No	Exact foods.id from recipes_search_foods, if already known. Skips automatic matching.
notes	string	No

Returns

The created ingredient row as JSON, including its id.

recipes_list_ingredients

List the line-item ingredients recorded for a recipe in the user's active Recipes / Module module.

Parameters

Name	Type	Required	Notes
recipeEntryId	string	Yes	ID of the recipe to list ingredients for.

Returns

Every ingredient row for that recipe, as a JSON array.

recipes_delete_ingredient

Delete a line-item ingredient from a recipe in the user's active Recipes / Module module.

Parameters

Name	Type	Required	Notes
ingredientId	string	Yes	ID of the ingredient row to delete, from recipes_list_ingredients.

Returns

The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.

recipes_create_meal_plan

Create a named meal plan in the user's active Recipes / Module module, e.g. 'This week's dinners'. Add scheduled days with recipes_add_meal_plan_day once created.

Parameters

Name	Type	Required	Notes
name	string	Yes	Name of the plan, e.g. 'This week's dinners'.
description	string	No	Free-text description of the plan.

Returns

The created meal plan as JSON, including its id.

recipes_list_meal_plans

List meal plans in the user's active Recipes / Module module.

Parameters

Name	Type	Required	Notes
limit	number	No	Max entries to return (default 100, max 500).

Returns

Every meal plan in the active database, as a JSON array.

recipes_update_meal_plan

Update fields on an existing meal plan.

Parameters

Name	Type	Required	Notes
mealPlanId	string	Yes	ID of the recipes_meal_plans row to update.
name	string	No
description	string	No
is_active	boolean	No	Set false to pause/retire the plan without deleting it.

Returns

The updated meal plan as JSON.

recipes_delete_meal_plan

Delete a meal plan and all of its scheduled meal plan days.

Parameters

Name	Type	Required	Notes
mealPlanId	string	Yes	ID of the recipes_meal_plans row to delete.

Returns

The deleted meal plan as JSON.

recipes_add_meal_plan_day

Schedule a recipe on a meal plan: either a recurring weekday slot (day_of_week, repeats every week indefinitely) or a one-off override for an exact calendar date (specific_date). Exactly one of the two must be given. specific_date always takes precedence over day_of_week on that date.

Parameters

Name	Type	Required	Notes
mealPlanId	string	Yes	ID of the recipes_meal_plans row this day belongs to.
day_of_week	number	No	Recurring weekday slot, 0=Sunday..6=Saturday. Repeats every week indefinitely.
specific_date	string	No	One-off override for an exact calendar date. Takes precedence over day_of_week on that date.
meal_slot	breakfast \| lunch \| dinner \| snack	Yes	Which meal of the day this recipe is planned for.
recipeEntryId	string	Yes	ID of the recipe (from recipes_add_entry/list_entries) planned for this slot.
servings	number	No	How many portions are planned for this slot. Defaults to the recipe's own servings.
notes	string	No

Returns

The created meal plan day as JSON.

recipes_update_meal_plan_day

Update fields on an existing scheduled day of a meal plan.

Parameters

Name	Type	Required	Notes
mealPlanDayId	string	Yes	ID of the recipes_meal_plan_days row to update.
day_of_week	number	No
specific_date	string	No
meal_slot	breakfast \| lunch \| dinner \| snack	No
recipeEntryId	string	No
servings	number	No
notes	string	No

Returns

The updated meal plan day as JSON.

recipes_delete_meal_plan_day

Delete a scheduled day from a meal plan.

Parameters

Name	Type	Required	Notes
mealPlanDayId	string	Yes	ID of the recipes_meal_plan_days row to delete.

Returns

The deleted meal plan day as JSON.

recipes_get_planned_meal

Resolve what's planned to eat on a given date (defaults to today) across all of the user's active meal plans: a specific_date override if one exists for a slot, otherwise the recurring day-of-week template. Returns the resolved recipe for each meal slot that has something scheduled.

Parameters

Name	Type	Required	Notes
date	string	No	Date to resolve. Defaults to today (UTC).

Returns

An object with the resolved date and a meals array (mealPlanId, mealPlanName, mealSlot, recipe, servings).

recipes_search_foods

Look up candidate foods by name when the exact match for an ingredient is unclear. Use the returned id as food_id in recipes_add_ingredient.

Parameters

Name	Type	Required	Notes
query	string	Yes	Free-text food name to search for, e.g. 'parmesan' or 'olive oil'.
limit	number	No	Max candidates to return (default 5, max 20).

Returns

Candidate foods with their nutrition per serving and match score, as a JSON array.

recipes_log_as_meal

Convenience tool for 'I made this again, log it' — computes nutrition for a recipe from its resolved ingredients, divides by servings (default 1 if the recipe has none set), multiplies by portions_eaten, and creates a new Diet Tracking entry. Requires both the Recipes / Module AND Diet Tracking modules to be active. Fails if the recipe has no ingredients or none resolve to a known food, rather than logging a meaningless zero-calorie entry.

Parameters

Name	Type	Required	Notes
recipeEntryId	string	Yes	ID of the recipe to log.
portions_eaten	number	No	How many portions were eaten (default 1).
logged_for	string	No	ISO date this meal was eaten, e.g. 2026-08-20. Defaults to today.
meal_label	string	No	Label for the new Diet Tracking entry. Defaults to the recipe's name.

Returns

The created Diet Tracking entry, whether servings was assumed to be 1, and any ingredients skipped, as JSON.