Skip to main content
The 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.
  • Type: Write
  • Important Input Fields:
    • clientId (string, required): Unique client ID.
    • startDate and endDate (string, required): Plan window in YYYY-MM-DD format, maximum 366 inclusive days.
    • plan fields (required): Plan metadata, targets, and slots.

​
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.
    • startDate and endDate (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 of add, replace, or remove.
    • clientId (string, required): Unique client ID.
    • planId (string, required): Unique identifier of the nutrition plan.
    • slotKey (string, required): Existing slot key.
    • item (object): The item to add. Required when action is add.
    • itemRef (object): Reference criteria (itemId, sourceId, itemIndex, or title) selecting the existing item. Required when action is replace or remove.
    • replacement (object): The new item to place in the slot. Required when action is replace.

​
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.
    • startDate and endDate (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.
  • Type: Write
  • Important Input Fields:
    • action (string, required): One of add, replace, or remove.
    • clientId (string, required): Unique client ID.
    • planId (string, required): Unique identifier of the nutrition plan.
    • slotKey (string, required): Existing slot key.
    • item (object): The item to add. Required when action is add.
    • itemRef (object): Reference criteria (itemId, sourceId, itemIndex, or title) selecting the existing item. Required when action is replace or remove.
    • replacement (object): The new item to place in the slot. Required when action is replace.
Use search_food_products, search_recipes, or search_supplements first when the item should reference an existing catalog entry.

​
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.

​
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.
    • startDate and endDate (string, required): Target range in YYYY-MM-DD format, maximum 31 inclusive days.
    • mode (string, optional): create_only, upsert, or replace_planned.
  • Output Highlights:
    • materialization.successCount and materialization.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 (archive or soft_delete, optional): Defaults to archive.
    • confirmActive (boolean, optional): Must be true to archive an active plan.
Both V1 and V2 support archiving. In V1, archive persists isArchived and archivedAt, keeps the plan and its date range, and returns status Archived. It does not mark the plan as deleted. soft_delete additionally persists isDeleted and deletedAt. Archived V1 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 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 V1 plan whose activation is still in progress also returns this conflict; retry after the activation finishes. No lifecycle change is applied in either case.

​
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.”

​
JSON-RPC Call Example (list_nutrition_plans)