mfp_update_food_entry

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

Beyond the annotations, it discloses a non-obvious behavior: MyFitnessPal may rewrite an entry during edit and return a replacement row, with current_entry_id and entry_id_changed to track the right row. This directly prepares the agent for a shifted identity, which is valuable for a mutation tool.

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 front-loads the core purpose, then adds the important rewrite caveat, followed by a scannable bullet list of parameters and a short Returns line. Every sentence earns its place and the layout supports quick parsing.

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 update operation with a potential entry-id change, the description provides the necessary source-of-truth workflow, all editable fields, and return semantics. The agent has enough context to locate the entry_id, make the desired change, and handle the possible replacement row.

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?

The description covers all six parameters in its Args section and adds meaning: entry_id comes from mfp_get_diary JSON output, date defaults to today, unit is a serving-size label, and weight_id is a raw MFP option ID. With schema coverage reported at 0%, it carries much of the semantic load, though it omits some nuances like weight_id overriding unit and constraints on quantity.

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 precise verb+resource phrase: 'Update an existing MyFitnessPal diary entry,' and enumerates what can be changed (meal, quantity, serving size, date). It also names mfp_get_diary as the source of entry IDs, which helps distinguish it from add/create/delete siblings.

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 the prerequisite—entries previously returned by mfp_get_diary—and tells callers to use response_format='json' to obtain the required entry_id. It gives strong contextual guidance for when this tool applies, though it does not explicitly list exclusions or alternative tools.

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