log_meal

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

Annotations already declare write, non-idempotent, non-destructive. The description adds real value beyond them: 'auto-approved' signals no review queue, and it discloses the time_check response signal and that daily totals are attributed by eaten_at date. It does not cover duplicate handling or what happens on a repeated log, which matters given idempotentHint=false.

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?

Core instruction is front-loaded, but the nutrient code enumeration consumes most of the text and the inline em-dash lattice ('nutrients — {...}; added_sugar — ...') reads as run-on. The volume is justified by the 0% schema coverage, but it could be tighter.

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 an 11-param mutation with an output schema present, the description covers what the agent must know to call it correctly: required field, formats, defaults, the estimate-by-model expectation. Only the auxiliary fields (notes, portion, nutrient_source) lack any explanation.

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 0% schema coverage across 11 params, the description carries the load and mostly succeeds: it enumerates meal_type values, gives the eaten_at ISO format and default, spells out the nutrients map keys against a long list of nutrient codes, and explains the non-obvious added_sugar distinction and per-meal scope of glycemic_index/load. notes, portion, and nutrient_source are left undefined.

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?

Opens with a specific verb+resource: 'Log a meal into the diary', plus a state qualifier '(auto-approved)' that tells the agent the entry is committed immediately rather than staged. It clearly implies a create operation, distinguishable from sibling update_meal/delete_meal, though those are never named.

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 concrete usage context: pass eaten_at as when the meal was actually eaten when logging retrospectively, and confirm with the user if the response contains a time_check. It also routes adjacent needs to siblings ('Review — query_food; daily norms — query_nutrition'). No explicit when-not-to-use or guidance on choosing between log_meal and log_from_template.

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