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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is largely carried by structured data. The description's "Only the fields sent change" meaningfully clarifies partial-update semantics, but it never explains why an edit warrants destructiveHint=true (e.g. that an existing note is overwritten) or what happens to items omitted from the arrays.

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 sentences, mutation scope and field inventory front-loaded, no filler. The closing clause about only-sent-fields is the single most important behavioral fact and is placed last for emphasis without waste.

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 destructive, partially-applied mutation over two arrays of objects with no output schema, the description covers the editable fields and patch semantics but leaves the agent without return behavior, ID-mismatch handling, or confirmation of what the destructive flag actually destroys. Adequate but with clear gaps against the tool's complexity.

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 100%, so all nested fields are already documented, including enum-like unit and meal_type values and the values_source rule. The description adds only a coarse split between entry-level fields (title, type, note, day, time) and item-level fields (name, amount, unit, note, values), which is mild added structure rather than new parameter meaning.

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?

States a specific verb ("Corrects") and resource ("meals already in the diary") and enumerates the editable surface: meal title, type, note, day, time, plus each food's name, amount, unit, note and values. The word "already" implicitly contrasts with log_meal, but no sibling is named explicitly, so it stops just short of full sibling differentiation.

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?

Usage is implied by "corrects meals already in the diary", which suggests it is the fix-up counterpart to log_meal, but there is no explicit when-to-use/when-not guidance. Nothing tells the agent it must first read_diary to obtain entry_id/item_id values, even though the schema relies on those IDs.

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