nutrition_plans module provides tools to view and manage customized diets
and meal plan templates assigned to clients.
Nutrition plan tools return a stable response shape across accounts, including
plan metadata, targets, slots, item references, and macro totals.
Plan date windows created or updated through MCP must include startDate and
endDate and cannot exceed 366 inclusive days. Concrete day materialization is
limited to the selected plan window, or to 366 days from the plan start for
older open-ended plans. Bulk materialization is limited to 31 inclusive days per
tool call.
Available Tools
list_nutrition_plans
List nutrition plans assigned to a client.
- Type: Read-only
- Important Input Fields:
clientId(string, optional): Filter plans for a specific client.page(integer, optional): Page number.limit(integer, optional): Items per page.
get_nutrition_plan
Retrieve detailed meal specifications and target macronutrient goals of a plan.
- Type: Read-only
- Important Input Fields:
planId(string, required): Unique identifier of the nutrition plan.
create_nutrition_plan Write
Create a coach-authored nutrition plan for a client.
If creation returns COMPANY_MCP_CONFLICT for an existing plan, inspect that
plan first. Update it when the coach wants to continue it. When the coach wants
to replace it, archive the old plan with explicit active-plan confirmation,
then create the replacement or assign a template. Template assignment follows
the same existing-plan checks; it does not automatically close another plan.
- Type: Write
- Important Input Fields:
clientId(string, required): Unique client ID.startDateandendDate(string, required): Plan window in YYYY-MM-DD format, maximum 366 inclusive days.- plan fields (required): Plan metadata, targets, and slots.
days(array, optional): Use instead ofslotswhen days differ. Legacy nutrition setups allow up to 28 days (for example a 14- or 28-day menu); Nutrition V2 plans are weekday based and allow at most 7.
validate_nutrition_plan
Validate and preview a complete client nutrition plan payload without storing it.
- Type: Read-only
- Important Input Fields:
clientId(string, required): Unique client ID.startDateandendDate(string, required): Plan window in YYYY-MM-DD format, maximum 366 inclusive days.- plan fields (required): Plan metadata, targets, slots, and optional items.
- Output Highlights:
validation.valid: Whether the proposed payload passes plan validation.validation.issues: Field-level validation issues when present.validation.plan: Preview of the plan shape that would be returned after creation.validation.macroGaps: Difference between target macros and planned totals.
preview_nutrition_plan_item_change
Preview the macro impact of adding, replacing, or removing one item in an
existing nutrition plan slot. This tool never mutates stored data.
- Type: Read-only
- Important Input Fields:
action(string, required): One ofadd,replace, orremove.clientId(string, optional): Client who owns the plan. Omit it to edit a company plan template.planId(string, required): Unique identifier of the nutrition plan or template.dayNumber(integer, optional): Day of a multi-day plan to change (1-28, as listed inget_nutrition_plandays). Omit it for single-day plans. Legacy nutrition only; Nutrition V2 plans are weekday based.slotKey(string, required): Existing slot key.item(object): The item to add. Required whenactionisadd.itemRef(object): Reference criteria (itemId,sourceId,itemIndex, ortitle) selecting the existing item. Required whenactionisreplaceorremove.replacement(object): The new item to place in the slot. Required whenactionisreplace.
update_nutrition_plan Write
Update metadata, status, date window, target macros, notes, or existing slots.
- Type: Write
- Important Input Fields:
planId(string, required): Unique identifier of the nutrition plan.startDateandendDate(string, optional): When changed, the resulting plan window must be present and maximum 366 inclusive days.- plan fields (optional): Provide only the fields that should change.
set_nutrition_plan_item Write
Add, replace, or remove one food product, recipe, supplement, or custom item in an existing nutrition plan slot. The mutation is selected with the required action parameter.
This changes the plan blueprint, including its base day. Confirm that the coach
intends to change the base plan, and call preview_nutrition_plan_item_change
first. To change one concrete date, use set_nutrition_day_item instead.
Only the selected item is added, replaced, or removed; other items remain intact.
- Type: Write
- Important Input Fields:
action(string, required): One ofadd,replace, orremove.clientId(string, optional): Client who owns the plan. Omit it to edit a company plan template.planId(string, required): Unique identifier of the nutrition plan or template.dayNumber(integer, optional): Day of a multi-day plan to change (1-28, as listed inget_nutrition_plandays). Omit it for single-day plans. Legacy nutrition only; Nutrition V2 plans are weekday based.slotKey(string, required): Existing slot key.item(object): The item to add. Required whenactionisadd.itemRef(object): Reference criteria (itemId,sourceId,itemIndex, ortitle) selecting the existing item. Required whenactionisreplaceorremove.replacement(object): The new item to place in the slot. Required whenactionisreplace.
search_food_products, search_recipes, or search_supplements first
when the item should reference an existing catalog entry.
duplicate_nutrition_plan Write
Copy a company plan template, or a client’s plan, with all its days, slots and
items into a new Draft company template. The source is not changed. Edit the
copy with set_nutrition_plan_item without clientId, and give it to a client
with assign_nutrition_plan.
- Type: Write
- Important Input Fields:
planId(string, required): Template or client plan to copy.clientId(string, optional): Client who owns the source plan. Omit it when the source is a company template.title(string, optional): Title of the copy. Defaults to the source title plus ” (copy)”.
materialize_nutrition_day Write
Create or refresh a concrete nutrition day for a client and date from one of the client’s plans.
- Type: Write
- Important Input Fields:
clientId(string, required): Unique client ID.planId(string, required): Unique identifier of the nutrition plan.date(string, required): Target date in YYYY-MM-DD format. Must be inside the plan window.
materialization.replacedOtherPlanDays). Days
with logged food are kept.
materialize_nutrition_days Write
Create or refresh concrete nutrition days for a bounded date range from one of
the client’s plans. Consumed items are never overwritten.
- Type: Write
- Important Input Fields:
clientId(string, required): Unique client ID.planId(string, required): Unique identifier of the nutrition plan.startDateandendDate(string, required): Target range in YYYY-MM-DD format, maximum 31 inclusive days.mode(string, optional):create_only,upsert, orreplace_planned.
- Output Highlights:
materialization.successCountandmaterialization.errorCount: Number of successful and failed dates.materialization.results: Per-day result with created/refreshed status or error details.
archive_nutrition_plan Write
Archive or soft-delete a client’s nutrition plan.
- Type: Write
- Important Input Fields:
planId(string, required): Unique identifier of the nutrition plan.clientId(string, required): Client who owns the assigned plan.mode(archiveorsoft_delete, optional): Defaults toarchive.confirmActive(boolean, optional): Must betrueto archive an active plan.
archive keeps the plan and its date range and returns status Archived.
For legacy nutrition, rolled-out days after today that hold only planned food
are removed (archive.removedFutureDays); today, past days and days with logged
food stay.
For legacy nutrition plans, archived plans are excluded from default plan lists
and current-plan selection. Use list_nutrition_plans with status: "Archived" to list them,
or get_nutrition_plan with the plan ID to inspect one. Archived legacy plans
cannot be edited, assigned, or used to create additional nutrition days. Existing
days, consumed items, and diary history remain stored and readable.
An already archived plan returns COMPANY_MCP_CONFLICT. A plan whose
activation is still in progress can also return this conflict; retry after
activation finishes. No lifecycle change is applied in either case.
create_nutrition_plan_template Write
Create a reusable company nutrition plan template (not linked to a client) with targets, meal slots and items. List templates with list_nutrition_plans without clientId and give one to a client with assign_nutrition_plan.
- Type: Write (requires
userConfirmed: trueand the write-tool grant) - Input Fields:
title(string, required)status(string:Draft,Active, optional)targetNutrition(object, optional)slots(array, optional)days(array, optional)notes(string, optional)idempotencyKey(string, optional)
search_assignable_supplements
Search supplements that can be assigned to a client with assign_client_supplement. Uses the client supplement catalog of the coach app (search_assignable_supplements), not search_supplements. Pass clientId to see which are already active on that client’s plan.
- Type: Read
- Input Fields:
query(string, optional)clientId(string, optional)page(integer, optional)
list_client_supplements
List the supplements on a client’s supplement plan, with dosage and coach note. Uses the client supplement catalog of the coach app (search_assignable_supplements), not search_supplements.
- Type: Read
- Input Fields:
clientId(string, required)
assign_client_supplement Write
Add one or more supplements to a client’s supplement plan, optionally with a personal dosage and note. Uses the client supplement catalog of the coach app (search_assignable_supplements), not search_supplements.
- Type: Write (requires
userConfirmed: trueand the write-tool grant) - Input Fields:
clientId(string, required)supplementIds(array, required)dosage(string, optional)note(string, optional)idempotencyKey(string, optional)
remove_client_supplement Write
Remove one supplement from a client’s supplement plan (planItemId from list_client_supplements). The catalog supplement stays.
- Type: Write (requires
userConfirmed: trueand the write-tool grant) - Input Fields:
clientId(string, required)planItemId(string, required)idempotencyKey(string, optional)
Natural Language Examples
- “List all nutrition plans created for client client_5f81.”
- “Retrieve details of the active diet plan plan_abc123.”
- “Validate this generated seven-day nutrition plan before saving it.”
- “Preview replacing the breakfast shake before changing the plan.”
- “Add Greek yogurt to Jane’s breakfast slot in her active plan.”
- “Create nutrition days for Jane from this plan for the next four weeks.”
- “Add the client’s vitamin D supplement to the supplement slot in her active plan.”