Update meal plan

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say that omitted fields are left unchanged (patch semantics), whether setting recipe_id to null detaches a recipe, or whether updating dates can conflict with an existing plan. For a mutation tool this is thin.

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?

Two short, front-loaded sentences with no padding, which is structurally sound. However, the second sentence is largely redundant with the schema's required array, so the brevity reflects under-specification rather than efficiency.

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?

An 8-parameter mutation tool with 0% schema coverage, no output schema, and no annotations about side effects needs a description that explains field semantics and outcomes. This one provides none of that, leaving the agent unable to safely construct a partial update.

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% across 8 parameters, and the description documents none of their meaning. It only repeats the required/optional split the schema already encodes. Nothing explains the from_date/to_date relationship, the nullable recipe_id, or what meal_type_id and servings affect, so the compensation the low coverage demands is absent.

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?

"Update meal plan" restates the tool name and title verbatim without adding scope, distinguishing it from the sibling update_recipe/update_food/update_shopping_entry tools, or clarifying whether this is a partial or full replacement. The only added information, that id is required, belongs to the schema. An agent learns nothing beyond the name itself.

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?

There is no when-to-use guidance, no mention of prerequisites (does the meal plan need to exist? does recipe_id/meal_type_id need to be valid?), and no reference to alternatives such as create_meal_plan or delete_meal_plan. The agent must infer that this is the edit path for an existing plan from the name alone.

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