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

Adds substantial context beyond annotations: configuration-only output, no recipes selected, no account required, account diet shaping the mixes offered, the default mix being a suggestion rather than a silent choice, the chooser having no priority control, and configurationId enabling reload recovery. This is genuinely useful given readOnlyHint=false. Minor gap: it doesn't say what state persists when it 'builds the draft directly' vs. only returning configuration.

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?

Front-loads the key compatibility statement, but the middle is repetitive – 'optional visual mix configuration / choose the structure before recipe generation' restates the chooser behavior already described, and the default-mix caveat is stated twice ('balanced default is offered' and 'default mix is a suggestion'). Several sentences could be merged without losing information.

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 14-parameter tool with an output schema and existing annotations, the description covers the decision-relevant behavior: entry mode, trigger conditions for direct drafting, no-account/config-only output, diet influence, and widget round-tripping. Remaining gaps are the undocumented non-required parameters and the exact side effects when it drafts directly.

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 beyond the schema: it explains that priority must carry a user-stated priority because the chooser has no priority setting, names slotRequirements/mixPreset as triggers for direct drafting, and defers the rest to 'same parameters as create_weekly_menu.' With 71% coverage and several undocumented params (dietary, servings, exclude/includeRecipeIds), a bit more would be needed for a 5.

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?

States a specific role (compatibility planning entry point that opens a protein-mix/weekly-planning chooser widget) and explicitly names the sibling it relates to: 'create_weekly_menu is the main planner.' It loses a point because it describes two modes (interactive chooser vs. building a draft directly) and the title ('Choose a protein mix') only covers one of them, leaving the core identity slightly muddled.

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 clear routing context: this is for older callers/compatibility, create_weekly_menu is the main planner, and when the request already contains a counted mix, slotRequirements, mixPreset or 'surprise me' this tool builds the draft 'exactly as create_weekly_menu does.' It stops short of an explicit when-not statement (e.g., 'prefer create_weekly_menu unless the caller is a legacy client').

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