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

Annotations already declare readOnly/openWorld=false/destructive=false, and the description adds substantial context on top: the exact stored representation returned, the correction flag, that storage identifiers are stripped, and the specific degraded behavior when no meal of that type exists (reply names the meal types that day does have). This goes well beyond the safety profile the annotations provide.

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?

The core is front-loaded: identity, returned contents, the day_summary alternative, and the date idiom all land in the first half. The trailing 'statement is the customer-facing IZeat message... For write operations' paragraph is generic boilerplate that does no work for a read-only tool whose output schema already exists.

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?

An output schema exists, so return structure need not be re-explained, and the description still covers the pieces an agent needs: failure mode when no meal matches, date-input semantics, the alternative for whole-day reads, and the copy-before-revise workflow. Nothing required to call it correctly is missing.

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 coverage is 50% — date is documented in the schema but meal_type carries only an enum. The description compensates by teaching the intended date idiom (omit for today; pass the customer's own word; YYYY-MM-DD only for a fully stated date; never compute one yourself), which is meaningfully richer than the schema text. It says little about what distinguishes the six meal_type values, but that is a minor gap.

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 and resource (returns one recorded meal) and enumerates exactly what comes back — ordered rows with named fields, meal totals, and the already-corrected flag. It explicitly contrasts itself with the sibling day_summary, so an agent can separate the two without opening either schema.

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?

Gives explicit when-to-use triggers (before update_meal action 'revise' to copy untouched rows; whenever the customer asks what one meal contains) and an explicit when-not (use day_summary for the whole day). It even prescribes next-step handling when no matching meal is recorded, telling the agent to ask the customer rather than re-read the day.

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