skylight-mcp

skylight_update_meal

Destructive

Update a planned meal occurrence by changing its name, recipe, meal slot, notes, date, or repeat rule; choose whether changes apply to one occurrence, future occurrences, or the whole series.

Instructions

Update a planned meal (meal sitting) — change its name, recipe, category/slot, notes, date or repeat rule. Targets one occurrence by its date and applies the change at the chosen recurrence scope. For a one-time meal omit apply_to. For a recurring meal, note that apply_to:'one' and 'future' SPLIT the series into additional sittings rather than editing in place; re-run skylight_list_meals afterward to see the resulting shape. apply_to 'future' or 'all' asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>",
      "instance_date": "<instance_date>"
    },
    "name": "skylight_update_meal"
  }
}

Input Schema

Name	Required	Description
`id`	Yes	Meal sitting id (from skylight_list_meals).
`date`	No	YYYY-MM-DD to move the meal to.
`note`	No
`rrule`	No	Replacement iCal RRULE string (plain string, NOT an array).
`frameId`	No
`summary`	No	New meal name. The create route 422s when this is non-blank and meal_recipe_id is also set; whether PATCH enforces the same rule is UNVERIFIED, so prefer setting one or the other.
`apply_to`	No	Recurrence scope for a RECURRING meal (one with an `rrule` in skylight_list_meals): 'one' = just this occurrence (splits it out of the series), 'future' = this and all later occurrences (splits the tail into a new sitting), 'all' = the whole series. Omit for a one-time meal (`rrule: null`) — Skylight rejects apply_to there; if one is sent anyway the call is retried without it.
`description`	No	Ingredients / instructions.
`confirmToken`	No	ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
`instance_date`	Yes	YYYY-MM-DD of the occurrence to act on — must be one of that sitting's `instances`.
`meal_recipe_id`	No	Link a different recipe.
`meal_category_id`	No	Move to another slot (breakfast/lunch/dinner).

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.4.8Nov 3, 2026

changedInput schema / properties / apply_to / description

Previous value: -"Recurrence scope: 'one' = just this occurrence (splits it out of the series), 'future' = this and all later occurrences (splits the tail into a new sitting), 'all' = the whole series."New value: +"Recurrence scope for a RECURRING meal (one with an `rrule` in skylight_list_meals): 'one' = just this occurrence (splits it out of the series), 'future' = this and all later occurrences (splits the tail into a new sitting), 'all' = the whole series. Omit for a one-time meal (`rrule: null`) — Skylight rejects apply_to there; if one is sent anyway the call is retried without it."

changedInput schema / required

Previous value: -[
-  "id",
-  "instance_date",
-  "apply_to"
-]New value: +[
+  "id",
+  "instance_date"
+]

Changed2 schema fields changedv1.3.0Sep 25, 2026

removedInput schema / properties / confirm

Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}

addedInput schema / properties / confirmToken

Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}

Changed1 schema field changedv1.0.1Sep 19, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Addedv0.8.1Aug 31, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the destructiveHint/openWorldHint annotations by disclosing a non-obvious side effect: apply_to 'one'/'future' splits the series into extra sittings rather than editing in place. It also documents the full confirmation protocol (elicitation prompt vs. preview + confirmToken, see MCP_CONFIRM_MODE) and the silent retry when apply_to is sent on a one-time meal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what the tool changes, then escalates to recurrence and confirmation subtleties in a logical order; the warning about series splitting is placed before the confirmation text it depends on. Some phrasing ("see MCP_CONFIRM_MODE", restated confirmation flow) is slightly verbose but each sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter destructive mutation with no output schema, the description covers the hard parts an agent would otherwise get wrong: occurrence targeting, recurrence scope semantics, split side effects, and the two-phase confirmation fallback. It also tells the agent how to verify the outcome via skylight_list_meals.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 83%, so the baseline is 3; the description still adds real cross-parameter meaning by explaining how instance_date scoping interacts with apply_to and by spelling out when confirmToken may be supplied. Minor gap: the interaction between summary and meal_recipe_id is only flagged as unverified rather than resolved.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a precise verb+resource ("Update a planned meal (meal sitting)") and enumerates the mutable fields (name, recipe, category/slot, notes, date, repeat rule). This clearly separates it from skylight_delete_meal, skylight_plan_meal, and skylight_update_recipe in the sibling list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete conditional guidance: omit apply_to for a one-time meal, use one of three recurrence scopes for a recurring meal, and re-run skylight_list_meals afterward to inspect the result. It does not route to alternatives for adjacent cases (e.g., changing the recipe definition itself via skylight_update_recipe), which keeps it just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server