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

Annotations supply the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the lower bar applies. The description adds PATCH-style semantics, but it omits the most consequential behavior — that the meals field replaces ALL existing meals — which sits only in the schema and partially undercuts the "send only what changes" advice. No mention of auth requirements or what the call returns.

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?

Two short sentences, zero waste, with the editable surface front-loaded and the patch instruction immediately after. Nothing could be removed without losing signal.

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 mutation tool with eight parameters, a deeply nested meals array, and no output schema, the description is thinner than ideal: it never warns that sending meals wholesale overwrites the plan, nor does it indicate what a successful call returns. Annotations cover the safety headline, so this is workable but visibly incomplete.

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?

With schema coverage at only 25%, the description carries extra weight, and it does map the three documented categories (title, targets, meals) onto the eight parameters. However, notes and the target_* variants are never named, and the partial-vs-replacement distinction between scalar fields and meals is left to the schema rather than stated here.

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?

Names a specific verb (changes) plus the exact editable facets of the resource (title, targets, meals), so the agent knows precisely what scope of mutation this is. It does not differentiate itself from siblings such as create_diet_plan, copy_diet_plan, or activate_diet_plan, but the purpose itself is unambiguous.

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?

"Send only what changes" is real usage guidance for a partial-update call, but there is no explicit statement of when to choose this tool over create_diet_plan / copy_diet_plan / schedule_diet_plan, and no prerequisite such as the plan having to exist or the caller needing edit rights.

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