> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fitsociety.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Nutrition Plans

> Reference for managing client nutritional plan blueprints.

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.

| Key | Value |
| :- | :- |
| **Module Key** | `nutrition_plans` |
| **Sensitivity** | `operational` |
| **Consent Required** | None |

***

## 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`)

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "nut-plan-1",
  "method": "tools/call",
  "params": {
    "name": "list_nutrition_plans",
    "arguments": {
      "clientId": "client_abc123"
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.