update_custom_food

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

The description states that a FULL REPLACE removes any nutrient or brand not supplied, explicitly noting data loss ('the brand was dropped'). That is a destructive update per the MCP semantics of destructiveHint, yet the annotations declare destructiveHint=false. The description therefore contradicts the structured safety signal, and an agent trusting the annotation would under-warn the user about losing existing field values.

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?

It is short, but a quarter of it is wasted on a duplicated subscription statement ('Requires a Garmin Connect+ subscription' ... 'Needs Connect+'). It also front-loads the prerequisite rather than the action, and the phrase 'The same PUT carrying both ids' is opaque without context for what 'the same' refers to.

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 mutation tool with a nested object, no output schema, and no field documentation in the schema, the description covers the subscription gate, the full-replace hazard, and the paired ids, which is a fair amount. It still omits how the caller obtains foodId/servingId (e.g. get_custom_foods) and whether a representation is returned, leaving the agent to guess at the surrounding workflow.

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 description coverage, the description must compensate, and it delivers the single most important semantic: omitted fields inside `input` are deleted, not merged, which directly governs how an agent constructs the payload. 'The same PUT carrying both ids' also signals that foodId and servingId are supplied together, though it does so cryptically rather than naming them.

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 never actually states the action; it opens with a subscription prerequisite and implementation trivia ('The same PUT carrying both ids'). The reader must infer from the tool name plus the FULL REPLACE note that this edits an existing custom food's nutrition fields. It conveys the resource type and mutation nature indirectly, but a specific verb+resource statement is missing.

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 gives one concrete precondition and even names the sibling to check it with ('Requires a Garmin Connect+ subscription (check with has_connect_plus)') plus a repeat of the same requirement ('Needs Connect+'). However, it never distinguishes this from create_custom_food, delete_custom_food, or get_custom_foods, so an agent gets a gate but no routing guidance.

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