Diet Tracking 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 Diet Tracking overview for how to turn it on.

CRUD

Core tools

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

diet_tracking_add_entry

Add a meal log to the user's Diet Tracking module. Requires the module to be active — see create_database. Resolves the meal against the foods catalog automatically (by meal text or an explicit food_id) and, for a recognized mass quantity (g/kg/oz/lb), auto-fills calories and macros by scaling the matched food's per-serving values. Explicit calories/protein_g/carbs_g/fat_g always win over anything auto-filled.

Parameters

Name	Type	Required	Notes
meal	string	Yes
calories	number	No	Calories for this entry. Optional if food_id/meal resolves to a known food and a mass quantity is given or assumed — otherwise required.
protein_g	number	No
carbs_g	number	No
fat_g	number	No
notes	string	No
food_id	string	No	Exact foods.id from diet_tracking_search_foods, if already known. Skips automatic matching.
quantity	number	No	Amount logged, e.g. 150. Only scales macros automatically when serving_unit is a recognized mass unit (g, kg, oz, lb). Defaults to the matched food's own serving size if a food resolves and this is omitted.
serving_unit	string	No	Unit for quantity, e.g. 'g', 'oz', 'cup'. Non-mass units are stored but not auto-converted.
logged_for	string	No	ISO date this meal was eaten, e.g. 2026-08-20. Defaults to today — set this explicitly when backfilling a past meal so it's not counted in today's totals.

Returns

The created entry as JSON, including its id. Returns an error asking for calories or a resolvable food_id if neither is available.

diet_tracking_list_entries

List entries in the user's active Diet Tracking 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.

diet_tracking_update_entry

Update fields on an existing Diet Tracking entry. Re-resolves the food match only when meal, food_id, quantity, or serving_unit is part of the update — an unrelated field change (e.g. notes) won't disturb a previously-resolved match. Explicit calories/protein_g/carbs_g/fat_g always win over anything auto-filled.

Parameters

Name	Type	Required	Notes
entryId	string	Yes
meal	string	No
calories	number	No
protein_g	number	No
carbs_g	number	No
fat_g	number	No
notes	string	No
food_id	string	No	Exact foods.id from diet_tracking_search_foods. Skips automatic matching.
quantity	number	No
serving_unit	string	No
logged_for	string	No	ISO date this meal was eaten, e.g. 2026-08-20.

Returns

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

diet_tracking_delete_entry

Delete an entry from the user's active Diet Tracking 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 Diet Tracking is actually used, so your agent doesn't have to fetch every entry and filter them itself.

diet_tracking_attach_photo

Attach a photo to an existing Diet Tracking 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 Diet Tracking 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.

diet_tracking_daily_totals

Sum calories and macros (protein/carbs/fat) across all meal entries logged on a given calendar day (defaults to today) in the user's active Diet Tracking module. Also returns the count of meals logged that day.

Parameters

Name	Type	Required	Notes
date	string	No	ISO date (YYYY-MM-DD). Defaults to today if omitted.

Returns

Totals for calories, protein, carbs, and fat, plus a meal count, as JSON.

diet_tracking_summary_range

Return per-day totals (calories and macros) for meal entries logged between startDate and endDate (inclusive, ISO dates) in the user's active Diet Tracking module, grouped by calendar day.

Parameters

Name	Type	Required	Notes
startDate	string	Yes	ISO date (YYYY-MM-DD), inclusive start of range.
endDate	string	Yes	ISO date (YYYY-MM-DD), inclusive end of range.

Returns

An array of per-day totals, one entry per calendar day with logged meals.

diet_tracking_search_foods

Look up candidate foods by name when the exact match for a meal is unclear. Use the returned id as food_id in diet_tracking_add_entry or diet_tracking_update_entry.

Parameters

Name	Type	Required	Notes
query	string	Yes	Free-text food name to search for, e.g. 'chicken breast' or 'brown rice'.
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.

diet_tracking_nutrient_totals

Sum fiber, sugar, sodium, and saturated fat across meal entries logged between startDate and endDate (inclusive, ISO dates) in the user's active Diet Tracking module. Only entries that resolved to a food in the catalog (via food_id or an auto-matched meal name) with a convertible mass quantity contribute — the response reports how many entries in range couldn't be included.

Parameters

Name	Type	Required	Notes
startDate	string	Yes	ISO date (YYYY-MM-DD), inclusive start of range.
endDate	string	Yes	ISO date (YYYY-MM-DD), inclusive end of range.

Returns

Totals for fiber, sugar, sodium, and saturated fat, the count of entries considered, and how many were unresolved, as JSON.