Your AI Kitchen (YAK)

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds the genuinely useful behavioral fact that results depend on ingredient density, but says nothing about what happens when the optional 'ingredient' is omitted or what precision/rounding to expect.

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 with an illustrative parenthetical and no filler. It is efficient, though the example is what creates the 'to'-parameter ambiguity, so brevity comes at a cost here.

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 4 parameters at 0% schema coverage and no output schema, the description should explain the 'to' enum semantics, the role of the optional 'ingredient', and roughly what is returned. It covers none of these, leaving an agent under-informed for a tool it will likely call blind.

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 parameter meaning and it largely fails. The example suggests a target unit like 'grams', but the schema's 'to' enum only accepts 'us' or 'metric' — an agent following the description would plausibly pass 'grams' and fail; the optional 'ingredient' parameter is never explained either.

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 ('Convert one amount') and adds the key mechanism ('using ingredient density'), which an agent could not infer from the name alone. Sibling tools are all recipe/menu CRUD, so the conversion role is self-evidently distinct even though no sibling is named.

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 example ('1 cup flour to grams') implies the intended scenario but the description never states when to use this versus alternatives, nor any exclusions or prerequisites. Usage is inferred from the example rather than declared.

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=true and non-idempotent, so the safety profile is covered; the description adds real value beyond that with the 30-day trash window and 7-day draft retention, which tells the agent the deletion is recoverable but time-bounded. It omits what empty_trash/delete_forever irreversibly destroy and any permission requirements.

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 dense fragment with the action list front-loaded and the confirmation rule at the end; nothing is wasted. It is telegraphic to the point of omitting connective context, but 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?

For a destructive, multi-mode tool with no output schema and no schema descriptions, the definition covers the actions, retention semantics, and the confirmation protocol. It leaves open what list_trash returns and what happens on a failed restore or a missing id, which an agent calling this blind would want to know.

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: it does explain each enum value of `action` and the `confirm` gate, earning partial credit. But `id` is entirely unexplained and there is no indication of which parameters are required per action (delete_forever needs id, empty_trash does not).

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 enumerates the concrete operations (delete, list_trash, restore, delete_forever, empty_trash), which makes the tool's actual scope clear beyond the misleadingly narrow name 'delete_recipe'. It is distinguishable from siblings like restore_revision since it operates on whole recipes, though it never states that explicitly.

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 one concrete directive — 'Ask the user first, then confirm=true' — which is a real usage rule, and the retention windows hint at when to use trash-delete vs delete_forever. It does not name alternatives or say when not to use this tool versus update_recipe or restore_revision.

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 indicate a non-readonly, non-idempotent mutation. The description adds some context that this is the draft-to-saved transition, but it does not explain what happens to the draft, whether the action is reversible, permission requirements, or how inferred filing works.

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 short and front-loaded, but the second sentence, 'Filing is inferred,' is cryptic and does not clearly earn its place.

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 six-parameter mutation tool with no output schema and low schema description coverage, the description is too thin. It leaves key behaviors and optional parameter effects unexplained.

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 only 33%, and the description adds no parameter-level meaning. It does not clarify how title, visibility, inspired_by, menu_entry_id, or family_group_id affect finalization.

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 action: turning a finished draft into a saved recipe. This distinguishes it reasonably well from start_recipe_draft and save_recipe, though it does not explicitly name those 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?

There is no guidance on when to use finalize_recipe instead of save_recipe, update_recipe, or start_recipe_draft. The phrase 'Filing is inferred' is too vague to serve as a usage condition.

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 safe, idempotent read. The description adds useful context beyond annotations: the data source is USDA and results are estimates, which the agent is instructed to disclose. It still omits whether missing ingredients or unfinalized recipes affect behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the output description. The estimate caveat is direct and actionable with no wasted prose.

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 tool with no output schema and 0% parameter description coverage, the description is too thin. It explains the shape of the result but not the meaning of its inputs or any usage conditions, which an agent needs to call it 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 explain the two parameters. It says nothing about what 'id' identifies or what the 'servings' number controls, leaving both parameters undocumented.

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 specifies the resource (nutrition), scope (per serving and total), and source (USDA data), making the tool's output clear. It does not explicitly state that the id refers to a recipe, but the title and sibling set make that reasonably inferable.

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 a behavioral instruction ('Say it is an estimate') but no guidance on when to call this tool versus alternatives, nor any prerequisites such as whether the recipe must be finalized or saved first.

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, so the safety profile is covered. The description usefully adds that scaling is "for display" (implying no persistence) and that shared recipes are visible, but says nothing about return shape or what happens with an ambiguous name.

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 dense sentence with the primary lookup keys front-loaded and the optional display modifiers trailing. Nothing is wasted, though the packed parentheticals read a bit telegraphically.

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 no output schema, the description should say more about what "open" returns, and one of six parameters (include_raw) is never addressed. For a read tool with strong annotations this is adequate but leaves real gaps for an agent deciding how to call it.

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 carries the burden; it does explain id vs name, servings/factor scaling, and the units us|metric enum. However it omits include_raw entirely and gives no guidance on precedence between id and name or how servings and factor interact.

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?

"Open one recipe by id or name" gives a specific verb and resource with lookup keys, and "(own or shared)" clarifies scope. It implicitly distinguishes from multi-result siblings like search_recipes, though it never names them explicitly.

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 parenthetical "own or shared" and the id-or-name lookup imply when this single-record fetch applies, but there is no explicit when-to-use versus search_recipes or get_nutrition, nor any stated prerequisites or failure conditions.

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 establish that this is not read-only, not destructive, and not idempotent. The description adds useful behavioral context by clarifying that hiding affects only the user's own view, which explains why it is non-destructive and distinct from removing the shared item itself.

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 definition is a single compact sentence with the core operation and scope front-loaded. There is no redundant or wasted text.

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 simple tool with annotations and enum-backed parameters, the description covers the basic operation well. However, because it includes a 'list' action and has no output schema, it should clarify what listing returns and how the 'id' parameter behaves across actions.

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 the action values and item types, which partially compensates, but it never explains the 'id' parameter or whether it is required for hide/unhide and ignored for list.

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 set: hide or unhide a recipe, menu, or list shared with the user. The scope 'from their own view only' also distinguishes this from destructive sibling operations such as delete_recipe.

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 per-user visibility scope implies when this tool is appropriate compared with deleting or modifying shared content, but the description never explicitly says when to use it versus alternatives. The three action values are listed, yet no when-not guidance or sibling routing is provided.

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 openWorldHint, so the safety profile is covered; the description nonetheless adds useful behavior beyond them, namely the no-persistence guarantee and the blocked-site failure mode. It does not describe latency, what a partial extraction looks like, or any size limits.

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, front-loaded with the action and its non-persistence, then the follow-up call, then the failure fallback. No sentence is redundant.

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?

No output schema exists, and the description does say the result is meant to be handed to save_recipe, so the agent knows a recipe payload comes back; the failure path is also covered. It remains slightly thin on the shape of the returned result and on what qualifies as a supported page.

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?

One required parameter with 0% schema description coverage, so the schema contributes nothing; 'from a web page' implies the url is a page link and 'source_url' hints at provenance, but the description never states the expected format (absolute URL? recipe page only?). Partial compensation only.

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 ('Read a recipe from a web page') and immediately scopes it with '(saves nothing)', which separates it from save_recipe and get_recipe among the siblings. An agent can tell exactly what this tool does 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?

Explicitly tells the agent to call save_recipe with the result and source_url afterwards, which is real workflow routing, and gives a fallback when the site blocks the fetch. It stops short of naming where pasted text should go (start_recipe_draft vs save_recipe), so the alternative path is slightly ambiguous.

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 safety is covered. The description usefully adds that the result contains actor, change, and timestamp fields, which is return-content context beyond the annotations. It says nothing about ordering, pagination, or size limits for a potentially long history.

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?

It is short and wastes no words, but it is a sentence fragment with no verb and no front-loaded statement of action. Brevity here reflects under-specification rather than disciplined conciseness.

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 simple read tool with annotations covering safety, the description still leaves the key parameter (id = recipe id) undocumented and says nothing about ordering or result size. The return-content hint helps, but the calling contract is incomplete.

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?

There is one required parameter 'id' with 0% schema description coverage, and the description never explains that this is the recipe id whose history is being listed. The agent must guess the parameter's meaning from the tool context alone, so the description fails to compensate for the coverage gap.

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 fragment describes what the tool returns (who changed a recipe, what changed, and when), which implies an audit-log read on a recipe. However, it omits the operative verb and never says it 'lists' history entries, so the purpose is inferred rather than stated. It is distinguishable from siblings like get_recipe or restore_revision only by inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this rather than get_recipe or restore_revision, and no prerequisites such as needing a valid recipe id or permissions. The word 'history' weakly implies an audit use case, but nothing is 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, idempotentHint=false, destructiveHint=false for the whole tool, yet two of the three modes appear read-only and one mutates. The description does not clarify which mode mutates, what 'unassign' actually removes (a category assignment from a recipe, presumably), or whether the change is reversible, so it neither reinforces nor explains the annotation set.

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 short with no wasted words and is front-loaded by mapping each mode to its meaning, which matches the action-dispatch design. However, the telegraphic fragment style ('taxonomy: allowed filing values.') reads like internal shorthand rather than an explanation, making it concise at the cost of clarity.

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 3-parameter, output-schema-less tool with only generic annotations, the description should at minimum explain `paths` and the effect of `unassign`. It instead leaves both ambiguous, so an agent cannot confidently construct the non-trivial arguments or predict the outcome of the mutating mode.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 3 parameters, so the description must carry the burden and it does not. The `action` enum values get one-word glosses, while `paths` (array of strings) and `recipe_id` are never mentioned at all, leaving a critical parameter entirely opaque.

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 enumerates the three action modes (taxonomy, list, unassign) so the agent can infer the tool is a multi-mode category utility, but it never states an overall purpose in verb+resource form and never differentiates itself from siblings like manage_menu or manage_family. Terms such as 'allowed filing values' are cryptic and force the agent to guess.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. An agent must infer that 'list' is the read path and 'unassign' the write path purely from the terse mode labels.

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=true, non-idempotency, and non-read-only behavior. The description usefully adds that the agent should ask before inviting, removing, or deleting, but it does not explain the consequences of destructive actions such as leave or delete_group, nor does it describe permissions or return behavior.

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 compact and front-loads the action dispatch syntax, with no wasted prose. It is dense but appropriate for an action-dispatcher tool, though the single run-on list could be slightly more structured.

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 10-action, 7-parameter tool with no output schema, the description gives enough to route basic action calls and parameter pairing. However, it leaves the plan action and return values unexplained, and does not clarify side effects or outcomes for the destructive actions.

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 compensate, and it does map parameters to actions: name for create, group_id/email for invite, group_id/member_id or email for remove_member, invite_id for accept/decline, and group_id/confirm for delete_group. This is strong action-specific guidance, though it does not clarify formats or edge cases beyond parameter assignment.

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 enumerates the concrete family-management actions (list, plan, create, invite, remove_member, invites, accept/decline, leave, delete_group) and pairs several with their key parameters. It is clearly more than a restatement of the name, but it does not provide a high-level statement of purpose or differentiate this tool from the sibling share_with_family.

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 only usage guidance is the caution "Ask before inviting, removing or deleting," which covers confirmation for risky actions but not when to choose this tool versus alternatives. There is no explicit guidance on when to use manage_family instead of share_with_family or other family-related sibling tools.

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 declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, and the description adds useful behavior beyond that: delete requires confirm, add_entry with update_list=true also modifies the menu's shopping list, and get/save should show the whole menu. It does not fully explain sharing, visibility, or broader mutation consequences, but it meaningfully supplements 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 description is dense and front-loads the resource and scope before enumerating actions. It is appropriately sized for a multi-action tool, though the long action sentence is somewhat run-on and could be structured more readably.

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 16-parameter tool with no output schema and only minimal annotations, the description covers many actions and side effects but leaves important gaps. Several parameters and action-specific required combinations remain unexplained, so an agent would still need to infer too much from the schema alone.

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 only 6% across 16 parameters, so the description must carry most semantic burden. It does clarify key action parameters such as title, type week|day|occasion, entries, id, weekday or course, recipe_id or title, entry_id, update_list, and confirm, but it omits meaning for note, slot, aisles, servings, and visibility.

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 resource and scope: saved menus, explicitly undated, with a long list of supported actions. It distinguishes itself from date-oriented menu planning by saying not to ask for dates, though it does not name the likely sibling plan_menu directly.

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 usage through the action list and the note that menus are undated, which helps route away from dated planning. However, it does not explicitly say when to use this tool versus plan_menu or other menu-related siblings, nor does it explain action-selection conditions beyond a few inline hints.

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=true and destructiveHint=false; the description reinforces this with 'Saves nothing', which is valuable because a 'plan_menu' name could imply persistence. It doesn't cover return shape or whether proposals are cached, but the safety profile is clear.

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 tight sentences, no filler, and the non-persistence caveat plus the handoff to manage_menu are front-loaded where the agent will read them first.

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 no-save behavior and the save handoff are covered, which is the critical decision info. But with no output schema and five undocumented parameters, an agent still cannot infer what the returned menu looks like or how to steer generation.

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?

Seven parameters at 14% schema coverage, yet the description explains none of them. 'Show it by day' hints at the days parameter, but busy_days, skip_meals, exclude_recipe_ids, servings, and title are undocumented in both places — a real gap.

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 ('Propose a menu') and constrains the source pool ('from saved and shared recipes'). It also implicitly separates itself from manage_menu by declaring it persists nothing.

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 names the alternative path — 'manage_menu action=save' — and describes the surrounding workflow (show by day, let the user swap, then save). An agent knows exactly when to call this versus manage_menu.

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 most important non-obvious behavior is disclosed: the restore is recorded as a *new* revision, so history is not destroyed. That aligns with destructiveHint=false and explains idempotentHint=false (repeat calls create additional revisions). It does not mention any auth/ownership requirements or what happens if revision_no is invalid.

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 short sentence, front-loaded with the action and with the key behavioral caveat in parentheses. Nothing is wasted, though the terseness leaves the term 'revision' ungrounded for an unfamiliar agent.

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 mutation tool with no annotations beyond a basic safety profile, 0% parameter coverage, and no output schema, the description covers the outcome (new revision) but not inputs or prerequisites. It is callable only if the agent already knows the data model.

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 both parameters carry no documented meaning in the schema. The description hints that revision_no refers to an earlier revision but says nothing about what 'id' identifies (recipe vs. revision owner) or the valid range/format of revision_no.

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 ('restore an earlier revision'), and the parenthetical clarifies the effect. It is distinguishable from siblings like update_recipe and list_history, though it never names them explicitly.

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 only implied by 'undo a recipe change' via the title and 'earlier revision' in the description. It never says when to prefer this over update_recipe, nor how to obtain a valid revision_no (e.g., from list_history).

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-readonly, non-idempotent, non-destructive; the description adds real value by disclosing that gaps are auto-filled (4 servings, private, inferred filing) and that the agent should report `assumed` items afterward. It doesn't address duplicate detection or what happens if the same title already exists, which matters for a create 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?

Roughly four compact sentences, front-loaded with the action and the no-questions rule, then defaults, then the post-save reporting instruction. No filler or restatement of the name.

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 20-param create tool with an output schema (so return values needn't be documented), it covers the behavior an agent must get right: immediacy, defaulting, and the assumed-items follow-up. Missing only edge cases like deduplication or permission requirements for family visibility.

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 20 parameters at 40% schema coverage, the description compensates for the highest-risk ones: default servings (4), default visibility (private), inferred filing, plain-line ingredients, and draft_id's role. Many params (menu_entry_id, family_group_id, source_url, inspired_by, method, course, occasion) get no explanation in either place, so coverage is partial.

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 concrete verb and resource ('Save a recipe to the user's box') and enumerates the accepted sources: chat, pasted, photo/file, or import_from_url. The 'ONE call' framing and the draft_id clause implicitly separate it from the multi-step start_recipe_draft/finalize_recipe path, so an agent can place it among 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?

Gives explicit operational guidance: save immediately, don't ask clarifying questions first, fill gaps with defaults. It also names the condition for supplying draft_id. It stops short of contrasting with update_recipe or saying when not to use it (e.g. editing an existing saved 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description isn't needed there. It earns credit by adding behavior the annotations cannot: the result set spans user and shared recipes, and the paging contract (offset + limit, has_more) is disclosed inline, which the agent needs to iterate pages.

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, front-loaded with the purpose and filter scope before the routing hint and the paging note. The telegraphic fragments ("Paged: offset + limit; has_more") are dense but readable and cost nothing in length.

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?

A 16-parameter, zero-required search with no schema descriptions and no output schema is exactly the case where the description must do the work, and it doesn't. It omits how filters combine (AND vs OR), which are exact-match vs substring, default page size, sort order, and what an empty result looks like.

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 carries the full burden for 16 parameters. It names only query-ish (text), category, ingredient, and status, plus offset/limit, leaving cuisine, diet, course, method, tag, occasion, main_ingredient, quick, hidden, and shared_with_me entirely undefined. Even the named ones get no value format or combination 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 and resource ("Search the user's and shared recipes") plus the filter dimensions it covers and the scope of the corpus (own + shared). That reliably separates it from get_recipe and list_history. It stops short of naming a sibling explicitly, so it's a strong 4 rather than a 5.

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?

"Check here before the web" gives a routing preference against an external tool, which is genuine guidance. But for a 16-parameter search with zero required params, the agent gets no help deciding between this and get_recipe, or when to add filters versus search bare. Usage is implied, not 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 the operation is a non-read-only, non-destructive mutation with open-world access (consistent with fetching a URL). The description adds real value beyond them: the 5 MB limit and plan gating. It does not say whether an existing image is replaced, whether repeated calls version the recipe, or that URL fetching happens server-side.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and input modes, then the operational limits. 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?

For a 4-parameter mutation with no output schema and zero schema documentation, the description covers the key operational facts (size, plan, input modes) but leaves id semantics and mime_type handling unexplained, which an agent may need to call it 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 0%, so the description carries the burden. It does meaningfully disambiguate image_base64 versus image_url and implies mutual exclusivity ('or'), which the schema does not express. However id and mime_type are never explained, including whether mime_type is required alongside base64.

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 a specific action and resource ('attach an image' to a recipe photo) that is clearly distinct from siblings like update_recipe or get_recipe. It does not explicitly name an alternative sibling, but the operation is 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?

It conveys constraints that guide usage: two input modes (base64 or public URL), a 'Chef plan' gate, and a 5 MB cap. It does not say when to use this versus update_recipe, nor any prerequisites beyond the plan mention.

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 annotations by disclosing permission/auth rules: Home Cook cannot share, group owners can re-share items shared with them, and name resolution is scoped only to the user's own groups. It does not cover side effects such as what happens to prior shares or idempotency, but the auth context is valuable.

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 core action and packs substantial detail into one dense but efficient block with no filler sentences. It is a wall of text without formatting, but every clause carries 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?

A 6-parameter mutation tool with no output schema, so the description should clarify what modes like `status` return and what `id` identifies. It covers most behavior and parameters but leaves return-value expectations for the read-style 'status' mode unaddressed.

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 17% (just `group` is described), so the prose has to carry the load and mostly does: mode values, `group` accepting names or 'all', `members` as display names, `default` setting/reading the default for NEW recipes, and item_type as recipe/menu/list. Only `id`'s exact meaning is left somewhat implicit.

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 (Share) and the resources it operates on (recipe, menu, list) plus the targets (groups or cross-group members). Clear enough to distinguish from most siblings, though it never explicitly contrasts with family-adjacent tools like manage_family or hide_shared.

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?

Provides contextual constraints (Home Cook can't share, group owners may re-share) that imply when it applies, but gives no explicit when-to-use/when-not guidance or named alternatives. The mode enumeration hints at distinct use cases but doesn't spell them out as 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?

Annotations declare destructiveHint=true and readOnlyHint=false, and the description's 'delete (confirm)' is consistent with that, adding the useful detail that confirmation is required for the destructive path. However it never says what delete/remove actually destroy, whether removal is reversible, or what 'share' does to visibility. With annotations carrying the safety profile, this is adequate but not rich.

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 telegraphic sentence that front-loads the action list with inline parameter hints — dense but zero filler. The trailing 'Show it by section' is cryptic and slightly wastes the strongest closing slot, but overall it is efficient for a nine-action dispatcher.

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 9-action, 12-parameter tool with no output schema and a destructive hint, the description leaves critical gaps: it never distinguishes list from get, never explains what 'check' does versus 'remove', and says nothing about title, checked, visibility or return shape. An agent could call the simple actions but would likely misfire on list/get, check, and share.

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 only 25% (12 params), so the description must compensate, and it does cover menu_id, items, item_ids, confirm, exclude and aisles. But it leaves id, new, title, checked and visibility entirely unexplained, and the id vs item_ids vs menu_id relationship remains guessable rather than stated.

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 enumerates all nine actions (generate, list, get, add, categorize, check/remove, share, delete) with a specific verb+resource mapping, so an agent knows exactly what capability set the tool covers. It never states the tool's overall object in prose (shopping lists) and relies on the name/title for that, but the action breakdown is unambiguous and no sibling tool overlaps this domain.

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?

Each action is annotated with the parameter that selects it (generate→menu_id, add→items, check/remove→item_ids, delete→confirm), which is real selection guidance. The imperative 'ALWAYS pass exclude (what to leave off) and aisles' is a hard usage rule agents would otherwise miss. What's absent is any when-not guidance or explicit exclusion conditions.

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=false and destructive=false, so the description focuses on what they cannot express: this opens a live draft in the user's app (a visible side effect before anything is saved) and it is the first step of a three-call workflow. The 'ask at most ONE question' rule is genuinely useful behavioral guidance. It stops short of saying what the draft call returns or what happens to an abandoned draft, which is a minor gap rather than a contradiction.

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, front-loaded with the core action and the '(no recipe yet)' precondition, followed by workflow and the alternative-route caveat. 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?

For a mutating draft-creation tool with no output schema, the description covers the side effect, the mandatory follow-on calls, and the ambiguity-handling rule, which is most of what an agent needs. The only material omission is what the call hands back (draft or recipe identifier) so the agent knows how to chain into update_recipe and finalize_recipe.

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 only 33%, so cuisine, occasion, servings, and flavor_direction have no field-level documentation. The description partially compensates with the instruction to 'pass anything already known', telling the agent to populate whatever is available, but it gives no format or interpretation guidance for the undocumented fields. That is better than nothing but not enough to fully offset the coverage gap.

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 ('Invent a new recipe for a dish the user named') and adds the crucial scoping constraint '(no recipe yet)', which separates it from save_recipe and update_recipe. It also names suggest_dishes as the tool for a different input shape, so an agent can route 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?

It gives an explicit when: the user has named a specific dish. It gives explicit when-not: a vague cuisine or theme means calling suggest_dishes first. It also lays out the follow-on sequence (write with update_recipe, file with finalize_recipe) and caps clarification at one short combined question, so there is nothing left to infer.

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, and closed-world, so safety is covered. The description adds behavioral value by defining the return format (short numbered list, user-facing) and the expected human-in-the-loop handoff, though it doesn't say how many options are returned or what happens on no matches.

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 compact sentences with zero waste; the usage trigger is front-loaded and the follow-up routing follows immediately, matching the reading order an agent 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?

With one required parameter, full schema coverage, no output schema, and safety already carried by annotations, the description supplies the essential workflow context. Only edge behavior (empty results, option count) is left unstated, which is minor for this tool.

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 the schema's terse 'The user's words' by enumerating the kinds of input that qualify (cuisine, theme, occasion, flavor), which materially improves how the agent fills the single parameter.

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 the trigger input (a vague idea: cuisine, theme, occasion, flavor) and the output shape (options shown as a short numbered list), which makes the tool's function unambiguous. It does not name a suggest-sibling to differ from, but none exists among the siblings, and it clarifies its role in the recipe workflow.

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 scopes when to call it (vague idea, not a specific dish) and names the concrete next-step alternatives — 'Let the user pick, then start_recipe_draft or get_recipe'. The agent knows both when to reach for it and where to route afterward.

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 meaningful behavior beyond annotations: it says history is kept, that passed lists replace old ones, and that scale_to_servings or scale_factor permanently resize the recipe. It does not contradict the non-destructive annotation. It still omits some side-effect details, such as what happens when no fields are supplied.

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 in three short sentences and avoids unnecessary repetition. The phrase 'filing fields take the save_recipe values' is somewhat jargon-heavy, but overall the structure is efficient.

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 22-parameter update mutation with very low schema description coverage and no output schema, the description is too sparse. It covers history retention, list replacement, and scaling, but does not clarify required id usage, most editable fields, return behavior, or validation implications.

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 14% schema description coverage across 22 parameters, the description must compensate heavily but does not. It explains list replacement and scaling options, but leaves most parameters undocumented, and 'filing fields take the save_recipe values' is too vague to clarify which fields are affected.

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: 'Change a recipe or draft (keeps history).' It is clearly an edit/update operation, but it does not explicitly distinguish itself from the sibling save_recipe or start_recipe_draft beyond saying filing fields take save_recipe values.

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 'Change a recipe or draft,' which suggests editing an existing recipe or draft. However, the description does not say when to use update_recipe instead of save_recipe, start_recipe_draft, finalize_recipe, or other siblings, and gives no explicit exclusions.

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