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

The description adds a required authentication header (X-App-User-Id) and explicitly states partial-update semantics ('Pass only the fields you want to change'). These go beyond the annotations, which only indicate non-readonly, non-idempotent, and non-destructive. It does not describe error behavior, but the annotations already cover safety aspects.

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 description is two sentences long, front-loads the primary purpose, and contains no fluff. Every sentence adds value: one states the purpose and scope, the other gives usage guidance and an auth requirement.

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?

Given the 14-parameter schema and minimal annotations, the description does not fully cover the tool. It omits the idempotency_key parameter, does not mention the output schema, and the 'portion' reference introduces ambiguity. However, the output schema exists, so missing return-value details are less critical.

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 only 14% schema description coverage, the description must compensate by explaining the parameter list. It names broad categories ('macros, nutrients, portion, date or meal_type'), but 'portion' does not exist in the schema, and the exact nutrient mappings are left implicit. It does add the useful 'pass only fields to change' guidance, which clarifies optionality.

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 uses a specific verb ('Correct') with a clear resource ('a previously logged meal') and lists the targeted fields ('name, macros, nutrients, portion, date or meal_type'). This clearly distinguishes it from sibling tools like log_meal (create) and delete_meal.

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?

It clearly states this is for correcting an existing meal and instructs users to pass only the fields to change. It does not explicitly mention alternatives like log_meal for creating, but 'previously logged' provides enough context to infer when this tool should be used.

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