Chop it: meal planning, recipes, pantry and shopping

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

Annotations only declare it is a non-readonly, non-destructive, non-idempotent write; the description adds substantial behavior beyond that — duplicate merging, serving scaling, partial failure reporting via note, rounding rules, stock-coverage semantics, and the auth prerequisite (linked Chop It account). The disclosure that unresolved recipe IDs yield an incomplete list is exactly the kind of failure-mode context annotations cannot carry.

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?

Purpose and the two source paths are front-loaded, and every sentence carries semantic load — nothing is filler. It is nonetheless a long, semicolon-dense block for a 5-parameter tool, which makes it harder to scan than it needs to be.

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 flags the non-obvious return nuances (remainingItemCount includes unresolved stock checks; unresolved recipe IDs land in note). Combined with source selection, pantry modes, rounding, and the account requirement, an agent has everything needed to call this correctly on the first try.

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 coverage is already 80%, yet the description still adds meaning: pantryMode's ignore/focus do not read stock while use covers only comparable measured stock, and draft-mode requires matching or changing the draft first. It also explains servings scaling behavior and leaveOutPantry's reversible Chef IQ Shop coverage. Some of this repeats the schema, keeping it off 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 verb and resource — builds one consolidated, aisle-organised shopping list — plus the two possible input sources. It is clearly distinguishable from siblings like get_shopping_list, update_shopping_list and shop_week, and it names those handoff tools so the agent knows this is the creation step.

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 conditions per parameter: recipeIds is used when no menuDraftId, pantryMode should be omitted or matched for a draft, and leaveOutPantry is set 'only when asked to leave out Pantry items'. It also routes the agent forward to get_shopping_list/update_shopping_list/open_shop_handoff. It stops short of explicitly contrasting with shop_week, which is the most likely alternative.

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

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.

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

Though annotations already declare destructiveHint=true and idempotentHint=true, the description adds genuinely new context: permanence ('cannot be undone'), the catalogue-recipe safety constraint, and a linked-account requirement. These are exactly the preconditions an agent needs before invoking an irreversible mutation.

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?

Three tight sentences with no repetition: the irreversible nature is front-loaded, then the usage condition, then the two hard constraints. Every sentence carries distinct 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?

An output schema exists and annotations cover the safety profile, so the description need only supply the human-facing constraints – irreversibility, catalogue exclusion, and account linkage – all of which are present. Nothing an agent needs before calling is missing.

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 coverage is 100% and the recipeId description already points to list_saved_recipes as the source. The tool description only echoes that the target is one of the user's own recipes, adding no syntax or sourcing detail beyond the schema; baseline 3 applies.

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 verb and resource ('Permanently deletes one of the user's own saved recipes') and immediately scopes it against siblings by clarifying it applies only to the user's own saved recipes, not catalogue recipes. An agent can distinguish this from update_recipe, get_recipe, or save_recipe without opening any schema.

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 explicit when-to-use guidance ('suits a request where the user has confirmed which recipe to delete') and a clear exclusion ('Catalogue recipes can't be deleted'). It stops short of naming a concrete alternative for non-deletion intents (e.g. update_recipe), which would be needed for a 5.

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

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

Beyond the annotations' destructiveHint=true, it discloses what the annotations cannot: deletion is permanent, the call is refused when expectedTitle mismatches the current title, refused when the week is This Week, and it requires a linked Chop It account. Those refusal paths are exactly the behavioral detail an agent needs before invoking a destructive 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?

One tight multi-clause sentence with permanence and scope first, followed by the confirmation-token behavior and the auth prerequisite. No filler and no restatement of the title.

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?

Return values are covered by the output schema, and the destructive/refusal/auth picture is well drawn. The one thing left implicit is post-deletion retry behavior (a second call on an already-deleted week), which matters given idempotentHint=false.

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%, but the description compensates: savedWeekId identifies the target saved week, and expectedTitle is explained as the week's current title as list_saved_weeks reports it, making its guard-rail function explicit. It never states where savedWeekId itself is obtained, so one small gap remains.

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 verb+resource ('Permanently deletes ... a Saved Week') keyed by savedWeekId, which clearly separates it from rename_saved_week, delete_recipe and list_saved_weeks. The irreversibility is front-loaded so an agent recognizes the destructive class immediately.

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?

Explicitly scopes usage to 'an explicit request that names the week', which is a real when-to-use condition, and it names list_saved_weeks as the source of expectedTitle. It stops short of naming an alternative tool for adjacent intents (e.g. removing the current week, which is refused), so it is clear but not fully routed.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description earns credit for adding context annotations cannot express: it requires a linked Chop It account, and the returned preferences are applied automatically by all planning, search and recipe tools — a meaningful side effect on other calls.

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-loaded with the resource and the anchor, then scope, then constraints. Slightly heavy in enumerating diet values and the 'fourteen common foods' detail, which an output schema already carries, but the extra words cost little and no sentence is filler.

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, so return shape needn't be re-explained, yet the description still previews the three field groups. Combined with the zero-arg signature, the auth prerequisite, and the read-only guarantee, an agent has everything needed to call it correctly on the first attempt.

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?

Zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly says nothing about inputs rather than inventing any.

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 verb and resource ('Returns the account's food preferences') and immediately anchors it to a known artifact ('the same record the app's Food preferences settings show'). It enumerates the returned fields, so an agent can distinguish it from update_food_preferences and from pantry/week tools without opening the schema.

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?

Clear context for when this is the right call: it is the read side of preferences and the values feed every planning, search and recipe tool, which tells the agent why it might want them. The 'Read-only' line implicitly routes writes elsewhere, but the sibling update_food_preferences is never named as the alternative, so the routing is inferred rather than explicit.

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

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

Annotations declare readOnlyHint=false, and the description explains why: reading a pre-sign-in draft 'attaches it to that account' once the user links — a real side effect no annotation conveys. It also discloses that reads follow revisions of that exact draft and what happens when a draft is unavailable.

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-loaded with what is returned, then usage, then edge cases; no sentence is filler. It is five dense conditional sentences, though, so the structure is efficient rather than maximally tight.

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?

Covers the hard cases an agent would otherwise get wrong — pre-sign-in drafts, account linking, unavailable drafts and their recovery route, and the draft/Saved Week/This Week boundary. An output schema exists, so the description carries no obligation to detail return shape.

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 coverage is 100% and the schema already explains both menuDraftId and configurationId, including the omit-only-when-reading-by-configurationId rule. The description only loosely implies when menuDraftId is unreliable ('latest menuDraftId is uncertain') and adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 verb and resource ('Returns the current state of a menu draft') and enumerates the payload (slots, labels, choices, selection/lock state, servings, slotIssues). It also explicitly separates the resource from its look-alikes: 'Drafts are separate from Saved Weeks and This Week.'

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 three concrete trigger conditions ('before an edit, after the user has chosen dinners in the widget, or whenever the latest menuDraftId is uncertain') and an explicit alternative path: unavailable drafts are recovered through open_saved_week with the known savedWeekId, otherwise the user reopens the week.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world. The description adds valuable context beyond annotations: it clarifies that Drafts and Saved Weeks do not affect the result and that a linked Chop It account is required. These are behavioral traits not in the annotations, though it stops short of describing return format or edge cases.

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 is front-loaded with the core purpose and remains efficient. 'Read-only' slightly duplicates the annotations, but overall every sentence adds useful information and there is no fluff.

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?

Given the tool's simplicity, empty schema, rich annotations, and available output schema, the description provides everything needed to call it correctly: what it returns, its scope, auth requirement, and how it differs from drafts/saved weeks.

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 tool has zero parameters, so parameter semantics are not applicable. Per scoring rules, zero parameters sets a baseline of 4.

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 states a specific verb (Returns) and resource (dinners currently set as This Week), and explicitly distinguishes it from Drafts and Saved Weeks. An agent can immediately tell this retrieves the active week's dinners, not a draft or saved week.

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 clear use-case examples ('what's for dinner tonight?' or 'what's on this week?') and says 'without planning anything new,' which implicitly excludes planning tools. However, it does not name specific alternative tools (e.g., get_menu_draft, list_saved_weeks) to route to, leaving that to inference.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context beyond those annotations: it says live pantry data supersedes remembered or earlier details and that a linked Chop It account is required.

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 is front-loaded with what the tool does, then adds relevance, data-freshness behavior, read-only status, and the account prerequisite in compact sentences. Every sentence adds useful selection or invocation context without padding.

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?

Given the tool's low complexity, zero parameters, existing output schema, and rich annotations, the description covers the important gaps: purpose, when to use it, when not to use it, data freshness, and the linked-account requirement. Nothing an agent needs in order to call it correctly is missing.

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 tool has zero parameters, so there are no parameter semantics to explain. The schema baseline for a parameterless tool is 4, and the description provides no parameter-specific details because none are needed.

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 uses a specific verb and resource: it lists the items in the user's Chop It pantry. It enumerates the returned fields (name, location, quantity, how full, expiry) and clarifies the scope with 'the same pantry the app shows', which distinguishes it from pantry-updating and generic recipe tools.

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 clear when-to-use guidance ('when the user wants to cook from what they have or use things up') and an explicit exclusion ('general dinner ideas don't need it'). It does not name a specific alternative tool for general dinner ideas, so it falls just short of a 5.

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

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

Annotations already declare read-only, non-destructive, closed-world, but the description goes well beyond them: servings scaling uses Shop rounding, scaledFrom holds the written count, scalingNote means embedded instructions must be reviewed and the recipe stays at its original servings, and it explicitly warns not to claim the recipe was adapted. It also explains optional: true garnishes and when/why nutrition is withheld -- real behavioral context an agent cannot infer from annotations.

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 core purpose is front-loaded, but the description packs unrelated instructions into semicolon-chained fragments ('Do not claim it was adapted; review ingredients and method together before a separate copy; the weekly widget asks for the dinner's servings'), which reads as jumbled and forces re-parsing. Long for a two-parameter read tool, though most content is substantive.

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 flags the edge cases an agent would otherwise misuse (scaling notes, optional garnish flags, withheld nutrition) and clarifies that per-serving nutrition is an estimate, not medical advice. Nothing needed to call or interpret the result is missing.

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 coverage is 100%, so the baseline is 3, and the description partially repeats the schema's scaling wording. It still adds meaning: what scaledFrom means relative to servings, that omitting servings yields the recipe's own count, and the practical consequence of scalingNote.

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 verb and resource ('Returns one complete recipe by recipeId') and enumerates what comes back (ingredients with quantities, method steps, timings, photo). This is clearly distinguishable from siblings like search_recipes or update_recipe, which are list/mutation tools.

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?

Explicitly lists where recipeIds come from -- search_recipes, a menu draft, a week, or list_saved_recipes -- and covers both catalogue and user-saved recipes as valid targets. It doesn't name a 'do not use this for X' case, but no sibling competes for the same job, so the guidance is practically complete.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description adds substantial non-obvious behavior: 24-hour expiry, that retrying an unavailable ID cannot recover it, that rebuilding does not restore ticks or partial coverage, and that a linked Chop It account is required. This is exactly the kind of context annotations cannot carry.

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 first sentence front-loads purpose well, but the recovery/rebuild material spans several sentences and reads as create_shopping_list or open_saved_week territory rather than this read tool's job. Roughly half the text is tangential to invoking get_shopping_list.

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?

With an output schema present and annotations covering the safety profile, the definition gives the agent everything needed to call it correctly, including the expiry failure mode and account prerequisite. The only gap is that it never says what to do on expiry beyond 'cannot recover', which nudges the agent toward a sibling tool by inference rather than instruction.

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 coverage is 100% and the single parameter already carries a warning against inferring the list from an old widget, so the schema does the heavy lifting. The description reinforces exactness and links the returned revision number to downstream tools, but adds little about the parameter's format or source beyond what is already structured.

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 verb and resource ('Returns the latest saved revision of a shopping list') and enumerates what comes back: lines with stable IDs, tick/partial-coverage state, and the revision number. It names the sibling consumers (update_shopping_list, open_shop_handoff) that take the returned revision, so an agent can place it precisely among the 35 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?

Usage is implied rather than stated: it establishes that saved state supersedes earlier conversation output and that the ID must be exact ('Never infer the list from an old widget' is in the schema), which tells the agent when this tool is authoritative. However, it never explicitly contrasts with create_shopping_list or says when to read versus re-create, leaving the routing decision partly to inference.

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

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

Annotations only say it is a non-readonly, non-idempotent, open-world, non-destructive write. The description adds real context beyond that: it consumes rate limits (limited per conversation), requires an authenticated/linked account, may require paid credits, and returns a needs_review state with a preview plus issues instead of silently saving.

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 front-loaded: capability and required input come first, then failure fallback, paid confirmation, limits and preconditions. The needs_review return-format sentence slightly overlaps the output schema but still earns its place by naming the corrective sibling.

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 mutating, open-world import tool, the description covers the happy path, the fetch-failure path, the paid-confirmation gate, rate limiting, and account linkage, while an output schema handles return values. Nothing an agent needs to call it correctly is missing.

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 coverage is 100%, so all four parameters are already documented, and the description largely repeats the imageUrl fetchability constraint. It adds a little sequencing context for confirmPaidImport but never mentions requestId, so it does not meaningfully exceed the schema baseline.

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 verb+resource (imports a recipe from a photo) plus the processing it performs (restructures to Chop It's recipe standard and saves to the library). It also implicitly distinguishes itself from import_recipe_from_url and save_recipe by naming them for different situations.

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?

Explicit routing: use this when you have a fetchable http(s) imageUrl; fall back to import_recipe_from_url with the text as caption if the fetch fails; correct a needs_review result with save_recipe; call confirmPaidImport only after the user agrees. Prerequisites (linked account, per-conversation limit) are also stated.

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

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

Annotations already declare it is a non-idempotent, open-world, non-read-only write, so the bar is lower; the description still adds real value by disclosing the account link requirement, a per-conversation rate limit, and a paid-processing confirmation gate. The rate limit is stated only as 'Limited per conversation' without numbers, which keeps it from a 5.

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 core purpose and source types are front-loaded in the first sentence, and each subsequent sentence adds a distinct operational fact (review path, paid confirmation, limits, auth). It is dense but nearly every clause earns its place; a small trim of the redundant 'requires a linked Chop It account' phrasing would tighten it further.

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 multi-step, account-gated, potentially paid import tool, the description covers the main decision points: review outcome, follow-up save, payment confirmation, and rate limits, and an output schema exists so return shapes need not be explained. It could still be clearer about failure behavior when neither url nor caption works, and about how it differs from the image-import sibling.

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 coverage is 100%, so the schema already documents url, caption, requestId lifecycle, and the confirmPaidImport credit condition in detail. The description's parameter-related statements (caption as fallback, requestId/confirmPaidImport flow) largely restate the schema, so the baseline 3 applies despite minor flow-level reinforcement.

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 verb and resource with source scope: 'Imports a recipe from a link (TikTok, Instagram or any recipe website), or from pasted caption text,' and names the outcome (restructured to Chop It's standard, saved to library). It does not explicitly distinguish itself from the close sibling import_recipe_from_image, leaving the link-vs-image boundary 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 usage context: use caption when the link can't be read, follow a needs_review result with save_recipe, and call confirmPaidImport only after the user agrees. It also states prerequisites (linked account, per-conversation limit). Missing an explicit 'use this instead of X' contrast against import_recipe_from_image or save_discovered_recipe.

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

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

Beyond the annotations, the description discloses the key side effects: recipes are copied into the user's library, a private menu draft is created, and a menuDraftId is returned. It also specifies important invariants—the source week and the user's This Week remain unchanged—and the account prerequisite, with no contradiction of the non-destructive annotation.

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 is front-loaded with the core action and effect, followed by the invariants and account requirement. Every sentence adds useful information, with no repetition or wasted phrasing.

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?

Given that an output schema exists, the description need not fully explain return values, but it still names menuDraftId and its intended follow-up uses. Combined with annotations and complete parameter schema coverage, the description is complete enough for correct invocation.

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 input schema has 100% description coverage for the sole parameter shareCode, including the crucial distinction that it is an intentional public share code and never a private collection or draft ID. The description references shareCode but does not add meaning beyond the schema, so the baseline 3 is appropriate.

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 states a specific verb and resource: it copies a shared week identified by shareCode into the user's account. It also describes the concrete effects—recipes join the library and a private menu draft is created—so an agent can distinguish it from share_week, preview_shared_week, and save_week without opening schemas.

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?

Usage context is clear because the description says the created menuDraftId is used for review, save_week, or shopping, and it notes the prerequisite of a linked Chop It account. It does not explicitly contrast with preview_shared_week or state when not to use this tool, so it falls short of fully explicit routing.

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

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

Beyond the readOnly/safe annotations, it discloses sort order, the page-vs-total distinction, a required paging loop, a staleness/restart rule, and the prerequisite of a linked Chop It account. That is substantial behavioral context an agent cannot infer from the annotations.

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?

Four short sentences, front-loaded with what is listed and its ordering, followed by paging mechanics and the read-only/account caveats. No filler.

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?

With an output schema present, return-shape explanation isn't required, yet the description still clarifies what the page field and total field mean. Combined with pagination and auth notes, an agent has everything needed to call this correctly.

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 coverage is already 100%, so baseline is 3; the description goes further by explaining the offset protocol semantically (start at 0, pass nextOffset, restart if data shifts). It doesn't add format or bound details beyond the schema's own minimum/maximum.

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 verb and resource (lists recipes in the user's Chop It library) plus scope qualifiers — includes imported/chat-saved recipes, ordered most-recently-updated first. It does not explicitly contrast with the sibling search_recipes, so an agent could still hesitate between a full-library listing and a search.

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 operating conditions: iterate nextOffset until hasMore is false, collect every page before proposing edits, and restart the read if records change mid-pagination. It stops short of naming alternatives such as search_recipes or get_recipe for single-item lookups.

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

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

Beyond readOnly/ idempotent annotations, it discloses an auth precondition ('Requires a linked Chop It account'), a consistency hazard ('restart if records change during the read'), and a data-provenance limitation ('Provenance is not recorded for personal snapshots'). Those are exactly the non-obvious traits an agent could otherwise get wrong.

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-loaded with purpose, then paging protocol, then identity/provenance caveats — no filler sentences. It is slightly dense for a one-parameter list tool, but each sentence carries a distinct operational or safety constraint.

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?

Covers the full set of things an agent needs before calling: what comes back at a high level, how to page to exhaustion, the auth prerequisite, and how to match a week to a prior save. With an output schema present and annotations carrying the safety profile, nothing material is missing.

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 coverage is 100%, so the offset parameter is already documented, and the description reinforces the contract by explaining the nextOffset/hasMore loop rather than repeating the field type. It adds pagination protocol (must read all pages, restart on change) that the schema alone does not convey.

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 verb and resource ('Lists the user's Saved Weeks') and names the returned payload fields (dinners, savedWeekId), which separates it from siblings like list_saved_recipes or get_my_week. The purpose sentence ('browsing or picking a week to reuse') ties the read to an actual downstream intent.

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 a concrete when-to-use framing (browsing, picking a week to reuse) plus procedural rules: page with nextOffset until hasMore is false, and collect all pages before editing. It also cross-references save_week as the source of the savedWeekId and warns against identifying weeks by position or recency. It stops short of naming an explicit alternative tool for a different listing need, so it is clear context without full alternative routing.

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

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

Adds context beyond the annotations: the draft is private and editable, the source Saved Week and This Week remain unchanged (reinforcing destructiveHint=false), and a linked Chop It account is required. It doesn't state what happens on repeated calls, so the idempotentHint=false implication is left implicit.

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 sentences, front-loaded with the action and effect, followed by the ID consumers and a short constraints clause. Nothing redundant and nothing buried.

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?

The output schema covers the return value and the description still usefully flags menuDraftId and its consumers; auth and non-mutation of the source are covered. The only real gap is sourcing savedWeekId, which neither schema nor description explains.

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% – savedWeekId carries only type/format uuid. The description implies the parameter identifies the Saved Week being copied but never says how to obtain the id (e.g., list_saved_weeks) or what happens with an invalid one.

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 verb and resource: 'Creates a private, editable menu draft copied from a Saved Week'. It also scopes what is copied (dinner order and servings), which separates it from create_weekly_menu and get_menu_draft without opening either schema.

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?

Names the downstream consumers of the returned menuDraftId (revise_weekly_menu, save_week, create_shopping_list), giving clear follow-on context. It does not explicitly contrast with create_weekly_menu or say when to build fresh rather than reopen a saved week, so no 5.

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

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

Beyond annotations, the description adds important behavior: the link is time-limited, the user reviews and ticks off items on that page, the tool buys nothing, and a linked Chop It account is required. It does not contradict the annotations; readOnlyHint=false fits creating a handoff link rather than a read-only lookup.

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 is three focused sentences and front-loads the core action before clarifying scope and constraints. There is little waste, though the phrasing could be slightly tighter around the menu-draft alternative.

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?

Given annotations and a present output schema, the description covers the essential operator context: what link is created, what the user does with it, that no purchase occurs, and that an account is required. A minor gap is that it does not explicitly say when to prefer a shopping list versus a menu draft.

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 100%, so the schema already explains menuDraftId, shoppingListId, and expectedRevision. The description adds only light context about using a shopping list or a menu draft's derived list at its current revision, which is useful but does not materially go beyond the documented parameters.

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 uses a specific verb and resource: it 'Creates a time-limited Chop It review link' for groceries still to buy on a shopping list or menu draft. This is far more precise than a generic 'open shop' summary, though it does not explicitly contrast itself with siblings such as shop_week.

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 implies when to use the tool by describing the review-link flow and noting that purchases happen on a supermarket site, but it gives no explicit when-not-to-use guidance or direct comparison to related siblings like shop_week. The account requirement is a helpful prerequisite, not an alternative-selection rule.

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

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.

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so 'changes nothing' largely restates them. The one genuinely additive fact is that it works without an account, which annotations don't express — useful auth context, but the description stops there.

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?

A single front-loaded sentence naming the resource and the parameter, with no filler. The trailing 'changes nothing' clause is mildly redundant with the read-only annotation, a minor inefficiency.

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?

With an output schema covering return values, full annotation coverage, and a single required well-documented parameter, the description is almost sufficient. The remaining gap is the relationship to import_shared_week, which matters for correct tool selection.

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 coverage is 100% and the schema itself explains that shareCode is an intentional public share code, never a private ID. The description only repeats the parameter name in parentheses, adding no syntax, format, or source guidance beyond the schema.

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 verb (shows) and resource (dinners and cooking details behind a shared week link), and pins the input as shareCode. It's clear on its own, but it never mentions the sibling import_shared_week, so the boundary between previewing and importing a shared week must be inferred.

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?

'Available without an account and changes nothing' implies a read-only preview context, and the absence of any exclusion is fine. However, the agent is not told when to choose this over import_shared_week or how the two interact, leaving the main usage decision implicit.

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

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

Annotations already declare non-destructive, idempotent and closed-world, yet the description still adds real value: it scopes the blast radius ('dinners, servings and This Week are unchanged') and states an auth prerequisite ('Requires a linked Chop It account') that annotations do not cover. The idempotency sentence partly repeats idempotentHint but clarifies the keying dimension.

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?

Four short sentences, front-loaded with the action and the identifier, then effects, then the prerequisite. Slight redundancy in restating idempotency already declared in annotations, but nothing is wasted.

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?

Output schema exists, so return values need not be explained, and annotations cover the safety profile. The auth prerequisite and non-effects are disclosed, leaving only minor gaps around the title parameter and error cases.

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%, so the description must carry parameter meaning. It names savedWeekId explicitly, but title is only implied by 'Renames' — it never says title is the new display name or mentions the 2–50 character constraint. Half the parameters get real semantics.

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 verb (renames), a specific resource (one of the user's Saved Weeks), and the keying identifier (savedWeekId). This cleanly separates it from delete_saved_week, open_saved_week, list_saved_weeks and save_week without needing to name them.

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?

Usage is implied by 'one of the user's Saved Weeks' plus the account prerequisite, but there is no explicit when-to-use vs. alternative guidance (e.g. when to rename versus save_week creating a new week). An agent must infer the boundary from the sibling names.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses non-obvious traits: every edit creates a new menuDraftId revision, unrelated dinners/locks/dietary rules/pantry choice are preserved, stale-edit errors return the current draft with changeApplied=false and support a partial retry, and undoLastChange does not touch Saved Weeks or prior shopping lists. None of this contradicts the annotations.

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 outcome and return value are front-loaded, and nearly every clause carries distinct operational information. The mid-section is a dense run-on enumeration of operations that would scan faster as a list, but there is little filler to cut.

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 15-parameter mutation tool with nested objects and an output schema, the description covers the remaining gaps an agent needs: revision semantics, preservation guarantees, error/retry behavior, auth gating and ID sourcing. Return-value details are left to the output schema, which is appropriate.

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 coverage is high (87%), so the baseline is 3, but the description adds real meaning: it maps parameter combinations to intents (slotId + replacementRecipeId also locks; reroll needs slotId; refillShortSlots takes no slotId; servings without a slot applies to the whole week; pantryMode/focusIngredients re-rank pantry) and warns that choices is atomic and must not be combined with other edits. A few parameters, such as focusIngredients and slotRequirement sub-fields, are left entirely to the schema.

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 specific verb and resource ('Changes a menu draft and returns the updated draft with a new menuDraftId') and enumerates every supported operation (choice selection, reroll, refill, requirement change, servings, pantry, lock, undo). That makes it clearly distinguishable from siblings like create_weekly_menu, prepare_weekly_menu, save_menu and get_menu_draft, which it also references for slot IDs.

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 explicit routing rules: use refillShortSlots 'instead of rerolling short slots one by one' and only when slotIssues is non-empty; chooseForMe only on an explicit user request; chat-only changes leave the draft untouched. It also states the prerequisite boundary (choosing works before sign-in; saving/shopping needs a linked account) and points to get_menu_draft for exact IDs.

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

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

Annotations already establish that this is a non-destructive, idempotent write. The description adds operational context beyond the annotations: the recipe is saved unchanged, an existing copy is reused, a linked account is required, and it returns the library copy's recipeId and appUrl.

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?

Three compact sentences, front-loaded with the action and scope, followed by input source and return value. Every sentence contributes useful information without repetition.

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?

Given the simple single-parameter schema, the presence of an output schema, and the annotations covering safety and idempotency, the description provides enough context for an agent to call this correctly. It covers account prerequisites, input source, reuse behavior, and return shape.

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 schema has only one parameter and 0% description coverage. The description compensates by explaining that recipeId comes from search_recipes, get_recipe, or a menu draft, which adds meaningful source semantics beyond the bare schema field.

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 states a specific verb and resource: saving a Chop It catalogue recipe unchanged into the user's own library. It also distinguishes this from a generic save by noting that an existing saved copy is reused, and it identifies the input source as search_recipes, get_recipe, or a menu draft.

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?

The description gives clear usage context: the recipeId must come from search_recipes, get_recipe, or a menu draft, and the user must have a linked Chop It account. It does not explicitly compare against sibling tools such as save_recipe or import_recipe_from_url, so it stops short of full when/when-not guidance.

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

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

Adds real context beyond the annotations: the destructive effect is spelled out ("replaces whatever week the user currently has set"), plus an auth requirement ("Requires a linked Chop It account") and a compatibility/deprecation signal ("for older callers"). It partially restates idempotentHint with "Idempotent for the same draft" and doesn't say whether the replaced week survives in list_saved_weeks, which matters for a destructiveHint=true operation.

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 compatibility framing and then the concrete action, with every sentence carrying routing or behavioral information. It is slightly long at five sentences and the save_week contrast is made twice, but nothing is filler.

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 single-parameter mutation with a full annotation set and an output schema, the description covers action, alternatives, destructive scope, auth, and idempotency. An agent has everything needed to decide and call correctly; return values are already covered by the output schema.

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?

Only one parameter and schema coverage is 100%, with the schema itself explaining that menuDraftId comes from create_weekly_menu. The description adds no further meaning to the parameter, so the baseline 3 for schema-documented parameters applies.

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 compound verb+resource: saves a completed menu draft as a Saved Week and makes it This Week in one step. It explicitly distinguishes itself from save_week (save only, leaves This Week unchanged) and set_this_week (the other half of the canonical workflow), so an agent can separate the three without opening any schema.

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 an explicit use case ("an explicit request such as 'make this my week now'"), names the preferred modern alternative (save_week followed by set_this_week), and adds a confirmation condition (confirm with the user when they already have a week in progress). Nothing about when to choose this over siblings is left to inference.

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

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

Beyond the annotations, the description discloses that a linked account is required, that validation is against the brief, and that status needs_revision saves nothing while returning fixes and a fresh token. It also explains that status saved means the recipe is in the library and appUrl opens it, which is substantial behavioral context for a write operation.

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 is front-loaded with the core action and then adds only decision-relevant details: source scenarios, token dependency, validation behavior, success/failure outcomes, and account requirement. Despite its density, every sentence contributes to correct invocation or interpretation.

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 complex mutation tool with an output schema, the description covers the essential context: account prerequisites, token provenance, validation rules, and the two meaningful status outcomes. The output schema can carry return-shape details, so the description is complete without needing to restate them.

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 13 parameters and only 69% schema description coverage, the description adds important meaning for recipeDraftToken by tying it to start_recipe and explaining the validation brief. It also clarifies required-field expectations around UK ingredient names, metric quantities, sections, method cues, and plain title, though it does not explain several optional params such as tags, servings, or times.

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 states a specific verb and resource — saving a structured recipe into the Chop It library — and explicitly names the three supported origins: cookbook photo, user-created recipe, or corrected import. It also links the call to start_recipe and its recipeDraftToken, so an agent can distinguish this from import and discovery 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 gives clear usage context: call after start_recipe and pass the returned recipeDraftToken. The three source scenarios imply when this tool is appropriate, though it does not explicitly name when to prefer import_recipe_from_image, import_recipe_from_url, or save_discovered_recipe instead.

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

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

Adds substantial context beyond the annotations: exactly what is preserved (recipes, order, slot labels, locks, per-dinner servings), the side effects that do NOT occur, the idempotency contract with its status value ('already_saved'), and the conflict behavior on a stale draft revision. Annotations already flag idempotentHint, but the description explains what idempotency means here.

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-loaded with the core operation and densely informative, with no filler sentences. Slightly over-packed in the middle (return values plus three sibling cross-references), and the savedWeekId return note is partly redundant given an output schema exists, but nothing is wasted.

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?

Covers everything an agent needs for a mutation tool with one param: preconditions, side effects, idempotency, error/conflict recovery path, and how to chain into related tools. The output schema handles return shape, and cross-tool id lifetimes are explained rather than assumed.

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?

Only one required parameter with 0% schema description coverage, so the description must carry the load. It characterizes menuDraftId functionally — a completed draft, revision-sensitive, reusable as the same id for create_shopping_list and regenerable from savedWeekId. It stops short of stating the id's origin or format, but the semantics are clear enough to supply the right value.

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 verb and resource ('Saves a completed menu draft ... as a reusable Saved Week') with the exact scope ('every dinner selected'). It distinguishes itself from save_menu/save_recipe family by naming which draft artifact it persists and explicitly contrasting with create_shopping_list and open_saved_week.

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 the precondition ('a completed menu draft (every dinner selected)', 'Requires a linked Chop It account'), the exclusions ('Leaves This Week unchanged and creates no shopping list'), and routes to concrete alternatives for both follow-up needs (create_shopping_list, open_saved_week, get_menu_draft for conflicts).

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

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

Goes well beyond the readOnly/destructive annotations: it discloses the fallback parsing model (query text is parsed for protein, time, dietary and dinner intent when filters are absent), that dinner-intent searches exclude sides/dips/starters, and that no account is required. It also clarifies a non-obvious side-effect boundary — searches don't mutate a menu draft.

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 purpose and return shape, then layers use cases, filter semantics, and behavioral caveats. Every sentence carries content, though five dense sentences is slightly more than this three-parameter tool strictly needs.

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?

Given a nested filters object, an output schema, and a large sibling set, the description covers what the tool does, when to reach for it, how structured filters interact with free-text query, and the read-only/no-account posture. Nothing an agent needs in order to call it correctly is missing.

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 coverage is only 33%, but the description compensates for the highest-risk ambiguity by explaining that filters are hard constraints while query is a soft fallback, and gives a worked mapping ("quick chicken dinners" → filters.protein ['chicken'], filters.maxTimeMins 30). cuisine and limit remain undescribed in both schema and description, so it isn't exhaustive.

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 verb and resource ("Searches Chop It's catalogue of 1,000+ tested recipes") plus exactly what comes back (recipe cards with title, photo, time, tags, protein). The catalogue scope plus the closing note that results don't touch a menu draft implicitly separates it from saved-recipe and menu tools in the sibling list.

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 triggering intents: "dinner ideas, a named dish, protein, cuisine or dietary need, or ideas built around ingredients the user mentions." It never names an alternative sibling (e.g. list_saved_recipes, get_recipe) or states when not to use this tool, so it stops short of explicit routing.

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

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

The description adds important behavior beyond the annotations: it replaces the current This Week, leaves the Saved Week reusable, creates an independent working copy, and returns the working copy servings or null when unset. This directly supports the destructive and idempotent annotation profile rather than contradicting it.

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 is front-loaded with the core action and side effect, then adds the relevant workflow and prerequisite. It is dense but every sentence provides actionable context for invoking the tool correctly.

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?

Although an output schema exists, the description also mentions the return value and null case. Combined with the auth requirement, replacement behavior, reusability of the source Saved Week, and the portions workflow, it is complete enough for an agent to call this tool correctly.

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%, so the description must carry the burden for savedWeekId. It does clarify that the argument should be the exact new savedWeekId after saving a revised menu, but it does not directly define where to obtain a savedWeekId or restate its UUID format.

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 states a specific verb and resource: it makes a Saved Week the user's This Week. It also clarifies that this creates an independent working copy with the same servings, which is enough to distinguish it from sibling tools like open_saved_week or save_week.

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 explicitly says what request it suits and gives a concrete alternative workflow when portions need to change: open_saved_week, revise_weekly_menu, save_week, then activate the exact new savedWeekId. It also names a prerequisite, a linked Chop It account.

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

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

Annotations already declare destructive/openWorld/idempotent, and the description adds real context on top: anyone with the link sees dinners and recipe contents (the exposure that justifies the destructive hint), and a linked Chop It account is required. It does not explain repeat-call behavior or revocation, so idempotency remains implicit.

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?

Three short sentences led by the action, no restatement of the title. The trailing "so it suits a request to share" is slightly redundant with the preceding exposure statement but still functions as routing guidance.

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?

Output schema exists, so return values need not be described; the account prerequisite and public-visibility consequence are covered. The main gap is what happens on repeated calls or how a link is revoked, which matters for a destructive, idempotent-flagged mutation.

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 coverage is 0%, so the description must carry the load, and it does: savedWeekId is a Saved Week ID and draft IDs are explicitly invalid inputs. That is meaningful filtering guidance beyond the schema's bare uuid type.

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 verb and resource ("Creates a public link to ... Saved Weeks") plus the effect (others can preview and import a copy). It is clearly distinguishable from preview_shared_week and import_shared_week, which consume rather than create a link.

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?

Says this "suits a request to share" and warns that Draft IDs are private and never share codes, which tells the agent when the call is valid. It does not name the sibling tools (preview_shared_week, import_shared_week, delete_saved_week for revocation) as explicit alternatives.

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

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

Annotations already declare destructiveHint=false, openWorldHint=true and idempotentHint=false; the description goes further by naming the side-effect boundary ('Never purchases anything', 'Leaves Saved Weeks and This Week unchanged') and the auth dependency. That is real added value. It stops short of clarifying the positive write implied by readOnlyHint=false – i.e., whether the built list is persisted and where.

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?

Four short sentences, front-loaded with the action and its return, followed by negative guarantees and the prerequisite. No filler and nothing repeated from the schema.

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, so return values need not be explained, and the description still summarizes them usefully. Auth and side-effect scope are covered. The remaining gap is the relationship to sibling list tools and the failure mode for a non-completed draft.

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 coverage is 0% – menuDraftId is an unannotated string – so the description must compensate. It adds meaningful qualifiers ('exact', 'completed') that constrain which ID is valid, but it does not say where to obtain that ID (e.g., via get_menu_draft) or what happens with an incomplete draft.

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 verb and resource – it builds the shopping list for a given menuDraftId and returns a summary plus a Chop It review URL in a single call. The precondition 'exact completed menuDraftId' sharpens the purpose. However, it never contrasts itself with the closely-related siblings create_shopping_list and get_shopping_list, so the agent must infer the difference.

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?

The phrase 'exact completed menuDraftId' implies usage after a menu draft is complete, and 'Requires a linked Chop It account' states a prerequisite. But there is no explicit when-not guidance and no routing to alternatives such as create_shopping_list, which an agent could reasonably confuse with this tool.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive, closed-world), the description adds that it makes no AI call, saves nothing, and requires a linked Chop It account — the auth prerequisite is exactly the kind of context annotations cannot carry. It also explains the token is a signed, user-visible copy holding no secret and granting no access, which prevents an agent from misreading it as a capability grant.

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 key facts — what is returned, the save_recipe contract, side-effect freedom, and the account prerequisite — are front-loaded in four dense sentences. The token security aside is slightly over-explained, but it earns its place by heading off a plausible agent misconception.

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, so return values need no prose, and the description still covers the workflow dependency, safety profile, and auth requirement. The remaining gap is input guidance for the undocumented parameters, which matters for a tool whose output quality depends on pantryMode and focusIngredients being set correctly.

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 57% schema coverage and 7 parameters, several inputs (servings, pantryMode enum values, focusIngredients) carry no explanation in either schema or description. The description gestures at pantry context, which maps loosely to pantryMode, but does not distinguish pantryMode='use' from 'focus' or explain how focusIngredients interacts with it.

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 uses a specific verb and names the concrete artifacts returned: the recipe brief (structure, UK ingredient names, metric quantities, method detail), pantry context, and a recipeDraftToken. It explicitly contrasts with the sibling save_recipe, which consumes the token, so an agent can place it in the workflow without opening the schema.

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?

Usage is clearly implied and partly explicit: call this to obtain the brief before writing a recipe, and pantry context is included 'when the user wants to cook from their pantry'. It does not, however, state exclusions against adjacent siblings like import_recipe_from_url, search_recipes, or save_discovered_recipe, so the alternative-selection guidance is incomplete.

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

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

Annotations already declare non-read-only, idempotent and non-destructive, so the description earns credit for what they don't say: omitted fields are preserved, supplied lists replace wholesale, the call returns the saved preferences, and the change propagates to the next planning/search/recipe call on every surface. The linked-account prerequisite and the explicit 'not built for managing allergies' limitation are exactly the behavioral context annotations cannot carry.

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-loaded with the verb and fields, then the mutation semantics, then downstream effects and prerequisites — a sensible ordering. A few clauses are dense, notably the long allergy disclaimer sentence, but each still carries decision-relevant information for an agent deciding whether it may claim allergy safety.

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?

With an output schema present, the description needn't detail return shapes, and it covers everything else an agent needs: all parameters optional, replacement semantics, the required linked account, and the downstream scope of the change. Nothing material is missing for correct invocation.

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 100%, and the schema already documents each parameter's omit-to-keep and empty-list-to-clear semantics plus the enum of 14 avoidable foods. The description restates the whole-list replacement rule but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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 verb and resource ('Changes the account's food preferences') and immediately enumerates the exact fields affected: diet, foods to avoid, dislikes. The reference to get_food_preferences makes the read/write split with its closest sibling unambiguous.

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?

Explicitly routes the agent to get_food_preferences to obtain the current value before a partial change, and states the replace-whole-list rule so the agent knows how to express a single-item edit. It does not state a 'do not use for X' exclusion beyond the allergy caveat, so it stops short of a full 5.

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

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

Beyond the destructiveHint/idempotentHint annotations, it discloses non-obvious behavior: top-ups are additive, only location-compatible items are topped up, ambiguous items return candidates while the rest of the batch still applies (partial success), staples like salt/pepper/oil are silently skipped, and a linked Chop It account is required. This is exactly the context annotations cannot carry.

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-loaded with the verb and the three modes, then behavioral caveats in descending priority. The opening sentence is dense but each clause maps to a distinct operation; "Edits the same pantry the app shows" is the only mildly redundant line.

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?

Covers auth precondition, destructive/additive behavior, ambiguity resolution, and skip rules, which is everything needed before invoking a batch mutation. An output schema exists, so return-value explanation is rightly omitted.

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 coverage is 100%, so the baseline is 3; the description goes beyond it by explaining location semantics (stock placed directly and only compatible items topped up) and by advising to omit unknown quantity/expiry rather than guess. It adds meaning rather than repeating field descriptions.

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 verb and resource ("Updates the user's Chop It pantry") and enumerates the three operation families: add/top-up, remove by name, and change or delete exact rows by pantryItemId. The scope (the same pantry the app shows) makes it immediately distinguishable from the read-only sibling get_pantry.

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 condition-based guidance per mode: use add for bought/have items, remove names for used-up items, pantryItemId rows when precision is needed, and "read back before retrying a top-up, which is additive" warns against a common misuse. It does not explicitly name get_pantry as the read-back tool, so the alternative is implied rather than named.

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

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

With destructiveHint=true already flagged, the description adds the operational safeguards: preview/confirm flow, changeSetId receipt recovery, conflict behavior, 24-hour undo limits, and no AI credit debit. It also states external dependency on a linked Chop It account.

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?

Every clause carries a real constraint, but the description is a dense wall of semicolon-linked policies that is not front-loaded or scannable. It would benefit from bullet structure; as written the agent must parse a lengthy paragraph.

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 mutation tool with an output schema and destructive annotation, the description covers the key risks and workflow. Minor gaps remain around some optional fields and the exact shape of receipts/conflicts, but the core operational picture is complete.

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 coverage is 71%, so the description carries some burden and does explain action, changes, complete ingredient/step replacement, and changeSetId/confirmed semantics. It leaves numeric fields like cookTimeMins and prepTimeMins to the schema, which is acceptable but not fully compensating.

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 names the resource (1–20 recipes), the core operation (review/edit), and distinguishes preview/apply/undo and update vs copy. It stops short of explicitly contrasting with sibling tools like save_recipe or delete_recipe, so an agent must infer that boundary.

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 explicit routing: read every library page first for whole-library work, use update only for title/description/tags, use copy for culinary changes, preview then apply only after approval, undo only within 24h if unchanged, and omit action for single-recipe edits. It also prescribes retry-on-uncertain-write behavior.

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

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

Annotations already mark the tool as non-read-only, idempotent, and non-destructive; the description adds concrete behavior beyond them: repeated values are safe, revision conflicts indicate concurrent changes, and a linked Chop It account is required. It also clarifies that only purchase quantities are affected.

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 is front-loaded with purpose and examples, then moves to parameters, behavioral guarantees, conflict handling, and prerequisites. Every sentence carries operational information, and there is no redundant filler.

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?

Given the mutation semantics, the presence of annotations, and an output schema, the description covers what an agent needs: scope, prerequisite auth, idempotency, conflict handling, and parameter interpretation. No material invocation detail is missing.

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 only 33% schema description coverage, the description compensates by explaining all three required parameters at a useful level: shoppingListId, expectedRevision, and changes keyed by line ID with excluded or coveredQuantity. It also explains the meaning of a revision conflict, which the schema does not describe.

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 states a specific verb and resource: ticking off, un-ticking, or partially covering shopping-list lines, with concrete examples. It clearly distinguishes the tool from retrieval via get_shopping_list and from recipe/pantry mutation by saying recipes and pantry are untouched.

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 explains the required data source for IDs, the idempotent repeat case, the revision-conflict recovery path through get_shopping_list, and the linked-account prerequisite. It also scopes the tool to shopping-list quantities only, making clear it is not for recipes or pantry changes.

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