update_custom_food

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so excellently. It explains the read-before-write merge behavior: omitted optional fields preserve their current values rather than being cleared. It also warns that nutrient amounts are absolute values, not %DV, which is critical for correct invocation.

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 appropriately sized for a 20-parameter tool and is well-structured: purpose, behavioral semantics, unit warning, prerequisite, then parameter list. It is front-loaded with the most important usage information before the Args section, and every sentence earns its place without fluff.

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 tool's complexity, zero annotations, and 0% schema description coverage, this description is remarkably complete. It covers the purpose, merge behavior, unit conversions, prerequisite lookup step, and per-parameter semantics. The existing output schema covers return values, so their absence from the description is not a gap.

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 0%, so the description must compensate, and it does comprehensively. The Args list documents all 20 parameters with units (g, mg, mcg), defaults for serving_unit and number_of_units, the source of food_id and serving_id, and the preservation semantics of brand_name and other omitted fields.

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 opens with a specific verb and resource: 'Update an existing custom food in the user's Garmin nutrition library.' This clearly distinguishes it from sibling tools like create_custom_food, log_custom_food, and delete_custom_food by emphasizing the 'existing' record being modified.

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?

The description gives clear contextual guidance: this is for updating existing custom foods, and it explicitly instructs the agent to 'Use get_custom_foods first to find the foodId and servingId.' It does not explicitly name create_custom_food or log_custom_food as alternatives, but the 'existing custom food' framing makes the intended scenario unambiguous.

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