skylight_update_meal

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

The annotations only include destructiveHint: true, so the description carries the burden of explaining the mutation's side effects. It does this well by warning that apply_to:'one' and 'future' SPLIT the series into additional sittings rather than editing in place. It does not mention the preview/confirm flow or other side effects, but the key surprising behavior is disclosed.

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

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

Three sentences with no waste: the first states what the tool does, the second explains targeting mechanism, and the third warns about the most important behavioral nuance. The critical splitting warning is placed where it is likely to be read before invocation, and the follow-up tool reference is concise and useful.

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

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

For a tool with recurrence complexity and no output schema, the description is complete enough: it covers the editable fields, the occurrence targeting, the apply_to semantics including the split behavior, and points to the right follow-up tool. The only missing piece, the confirm/preview flow, is already documented in the schema, so the description doesn't need to repeat it.

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

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

Schema description coverage is 83%, so the schema already documents most parameters. The description adds value by explaining the meaning of apply_to in the context of recurrence ('SPLIT the series into additional sittings') and by emphasizing that the tool targets a specific occurrence via its date. This goes beyond what the parameter list alone states, though some parameters like confirm and frameId are not addressed in the description.

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

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

The description states a specific verb ('Update') and resource ('planned meal (meal sitting)'), lists the editable fields (name, recipe, category/slot, notes, date, repeat rule), and clarifies that it targets one occurrence by date. This clearly differentiates it from siblings like skylight_plan_meal or skylight_delete_meal, which create or remove meals rather than modify an existing sitting.

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

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

The description gives clear context: use this to update an existing meal sitting, and it even advises re-running skylight_list_meals to inspect the resulting series shape after recurrence changes. It does not explicitly state when not to use it or name alternative tools such as skylight_plan_meal, but the context is sufficient for an agent to route correctly.

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