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

Annotations only say non-read-only, non-idempotent, non-destructive; the description goes well beyond by explaining that nothing is selected until the user acts, that a zero-selection draft is the expected starting state, that building works without an account but pantry-from-stock requires a linked account, and that dietary rules and time limits are hard constraints. The slotIssues explanation ('fewer cards means fewer recipes met that slot's rules, not that the catalogue is short') heads off a very likely agent misread of the return value.

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?

Dense but load-bearing: the opening sentence states the entry-point role, the middle explains the draft/selection model and the id contract, and the tail is a scannable 'Parameters:' rundown. For a 14-parameter tool the length is justified, though it arrives as one unbroken block where sub-headings or line breaks would make the parameter section faster to parse.

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 output schema exists, yet the description still names the two things the agent most needs back: the recipe-selection widget and the menuDraftId consumed downstream. A few parameters (servings, mixPreset, recipeSource, excludeRecipeIds) get no elaboration in the description and rely on the schema, which is acceptable at this coverage level but leaves a small gap in an otherwise thorough definition.

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?

Adds real meaning on top of schema coverage of 71%: dietary holds whole-week rules only ('one vegetarian dinner is a slot, not dietary'), counted proteins and slotRequirements each map to one dinner slot, maxTimeMins is global while per-slot maxTimeMins/minTimeMins mix quick and slow, and includeRecipeIds pin as selected while none else is selected. It also spells out the priority options in behavioural terms, which the terse schema descriptions don't fully duplicate.

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?

Opens with a specific verb+resource: 'Builds a draft week of dinners from Chop It's catalogue', and clarifies it produces an unselected draft plus a menuDraftId. It distinguishes itself from the tools that consume the draft (revise_weekly_menu, save_week, create_shopping_list) but never contrasts itself with the sibling prepare_weekly_menu, so the boundary with the closest alternative stays implicit.

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?

Gives concrete when-to-use routing: 'Main entry point for planning dinners', 'pantryMode stays off unless the user wants to cook from their pantry', and 'For quick weeknights plus a slower weekend, use slotRequirements instead' of maxTimeMins. It also sets the normal starting state ('status needs_selections') so the agent won't treat an empty selection as failure. No explicit exclusion against prepare_weekly_menu or revise_weekly_menu beyond naming which tools accept the id.

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