Sous Chef

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

Annotations only carry generic hints (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds genuinely non-obvious behavior — the server mints the import-*/ai-* id and any caller-supplied recipe.id is payload-only, not an upsert key. It does not address duplicate-creation risk or how the new id is returned, which matters given idempotentHint=false and an idempotencyKey parameter.

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 decisive condition in the first sentence, then routes to alternatives and ends with the id caveat. Every sentence carries distinct information, though the opening sentence is compound and could be split for faster scanning.

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 create tool with a deeply nested recipe schema, an output schema, and annotation coverage, the description supplies what structured fields cannot: the save-intent gate and the server-side id minting. Remaining gaps are the source* parameters and what a successful response contains, both partially mitigated 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?

Schema description coverage is only 25%, so the description has to compensate, and it does so for the single most confusing field (recipe.id being ignored as an upsert key). It says nothing about sourceUrl, sourceKind, or how those interact with the recipe payload, leaving three of four parameters undocumented outside 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 and resource ('Creates a NEW recipe in your library') and explicitly scopes it against three siblings: display_recipe, update_recipe, and apply_recipe_patches. An agent can pick this tool over the alternatives 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 gating condition ('only when the user explicitly asks to save/add it or taps Save') plus the negative case ('a newly generated recipe the user has not chosen to keep, use display_recipe instead'). It also names the correct alternatives for mutation cases (update_recipe, apply_recipe_patches).

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, idempotentHint=false and openWorldHint=false, so safety is largely covered. The description adds real value by disclosing that patches are validated and that the unsaved-card path does not persist, but it says nothing about what happens on validation failure, whether edits are revertible via revert_recipe_edit, or how editId/requestId/reason affect retry behavior. The 'does not modify the library' line slightly softens the destructive hint, which an agent should not read as 'safe'.

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, front-loaded with the action, then the two calling modes, then the scope exclusion. No filler, though "edit an unsaved card without persistence" is compressed to the point of ambiguity about what 'card' means.

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. But for a destructive, non-idempotent tool with seven parameters, a ten-variant patch union and nested recipe structures, the description covers only the target selection and omits the patch vocabulary entirely, leaving an agent unable to construct a valid call from the description 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 0% across 7 parameters and a deeply nested patch union of ten variants, yet the description only explains two parameters (recipeId and recipe) and their source. Nothing is said about patches, the ten patch type constants, editId, reason, requestId, editLabel, sessionId, reply, or measurementSystem. This is the highest-leverage information the description could have supplied and it is absent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Validate and apply explicit edits" gives a specific verb pair and resource, and the two-mode routing (recipeId vs. full recipe payload) makes the operation concrete. It implicitly separates itself from update_recipe by stating it does not touch the saved library recipe, though it never names that sibling 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?

Explicit when-to-use routing: recipeId for a persisted cooking session, or the payload from display_recipe for an unsaved card. The negative case ("Does NOT modify the saved recipe in your library") steers library edits elsewhere, but the description never names update_recipe as the alternative or states prerequisites such as needing an active session.

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 idempotentHint=false, and the description adds context beyond them: the effect is permanent/irreversible, it requires an authenticated owner, and it refuses public catalog entries. It does not describe the failure mode for a non-owned or unknown id, 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?

Two short sentences with the destructive nature and scope front-loaded and no filler. Slightly more could be trimmed, but nothing 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?

An output schema exists, so return values need not be explained, and the description covers the key behavioral facts an agent needs: permanence, ownership requirement, and the catalog-recipe restriction. Only error/edge-case behavior for invalid or non-owned ids is left unstated.

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% for the single 'id' parameter, so the description carries the burden; it only implicitly conveys that the id must reference a recipe owned by the caller. No format or example for the id is given, so it adds minimal meaning 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?

The description pairs a specific verb ('Permanently delete') with a specific resource ('a recipe owned by the authenticated user from their Sous Chef library'), so the operation and its scope are unambiguous. It also carves out a boundary against public catalog recipes, which separates it from read/update siblings, though no sibling is named 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 provides one clear exclusion ('cannot delete public catalog recipes'), telling the agent when this tool will fail, but it offers no guidance on alternatives (e.g., update_recipe, revert_recipe_edit, or sharing) and no explicit prerequisites beyond implicit ownership.

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 read-only, idempotent, non-destructive behavior, but the description adds the decisive nuance the annotation cannot: display is temporary, renders without saving or creating a cooking session, and persistence requires a separate call. That resolves the main behavioral ambiguity for an agent deciding whether this call has lasting side effects.

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 sentences, front-loaded with the action, then the usage preference, then the persistence caveat. No repetition of annotation-level facts and 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?

Return values need not be explained because an output schema exists, and the description covers the temporary-versus-saved distinction and routing to add_recipe. The remaining gap is payload construction — what `id` to supply for a brand-new recipe and how ingredient/step IDs must line up — which the description leaves entirely to the 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?

Schema description coverage is 0% on a single deeply nested `recipe` object, and the description says nothing about the payload. Non-obvious requirements — a mandatory `id`, mandatory `meta`/`notes`, and `steps[].ingredientIds` cross-referencing `ingredients[].id` — must be inferred entirely from the schema, 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?

States a specific verb and resource — presents a full recipe in an interactive recipe card — and enumerates what the card contains (servings, ingredients, steps, cooking mode, validated edits, Undo). It also distinguishes itself from the save path by naming add_recipe, so an agent can separate it from siblings without opening a 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 preference rule ('prefer this over plain chat formatting whenever you generate, retrieve, or substantially revise a full recipe') and concrete triggering examples like 'give me a vegan mushroom carbonara'. It also states the exclusion boundary — saving only happens through add_recipe when the user asks.

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, and closed-world, so the safety profile is covered. The description adds context those annotations cannot: the call returns the persisted canonical version and deliberately omits session-scoped edits, which tells the agent the result may lag live cooking state. It stops short of noting errors for unknown ids or any catalog-vs-library access differences.

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, no filler, with the primary behavior front-loaded and the exclusion appended. Every clause carries information an agent can act on.

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-value detail is not required, and annotations handle the safety profile, so the description need only cover selection guidance and id semantics. It is adequate on the former and silent on the latter, which for a single-parameter lookup tool is the one gap that actually matters.

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% for the single required 'id' parameter, so the description carries the full burden. It never says what the id is (library id, catalog id, slug) or whether the same id space spans both the library and the public catalog, which is exactly the ambiguity the two-source framing creates. This is the definition's weakest area.

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 gives a specific verb and resource ('Returns the saved canonical recipe') and names the two sources (library, public catalog), which is more than a restatement of the name. It does not differentiate itself from the closest sibling, display_recipe, nor from list_my_recipes, so an agent still has to infer which retrieval-shaped tool applies.

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 one useful exclusion — in-progress cooking edits live in sessions and are not returned here — which implicitly routes the agent elsewhere for live state. However, no sibling is named and no positive trigger is given (e.g., 'use this when you already have an id; use list_my_recipes to enumerate'), leaving selection between get_recipe, display_recipe, and list_my_recipes 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 already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is fully covered by structured data. The description adds only the notion of reachability, not what a failed check means, whether it touches downstream services, or latency expectations. Since an output schema exists, return-shape disclosure is correctly left out.

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 short sentence, front-loaded with the verb and resource, with no filler. It is perhaps almost too terse for the one thing an agent needs, 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?

For a zero-parameter probe with an output schema and full annotation coverage, the description covers the essentials. The only real gap is guidance on interpreting or reacting to a failed check, which is a minor omission given the tool's simplicity.

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 takes zero parameters, so there is no parameter meaning to convey and the baseline applies. The description correctly avoids inventing inputs and implicitly frames the call as parameterless.

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 (confirm) and a specific object (Sous Chef MCP server reachability). It is clearly distinguishable from all siblings, which are recipe CRUD operations, but it doesn't describe what a successful versus failed result indicates.

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?

Implies use as a connectivity probe, but never says when to call it (startup? before a batch of recipe edits? after transport errors?) or when it is unnecessary. No alternative is named because none exists, which softens the gap.

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, and closed-world behavior, so the safety profile is covered. The description adds the useful scoping detail that only the authenticated user's own saved recipes are returned, but says nothing about how many are returned by default or how the limit caps the result.

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 with zero filler, and the tool's core purpose is stated before the usage hint. Every clause carries information an agent can act on.

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 safety, so the description only needs to establish purpose and when to reach for it, which it does. The one gap is result-size behavior, which matters for a list tool with a capped limit.

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% for the single parameter, limit, so the description carries the burden of explaining it and does not. It never mentions the default page size, whether results are truncated, or that 100 is the ceiling, leaving the agent to infer behavior from the raw bounds alone.

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 ("List ... saved Sous Chef recipes") and scopes it to the authenticated user, which is enough for an agent to distinguish it from get_recipe or display_recipe. It does not explicitly name a sibling, which keeps it short of 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?

Gives an explicit trigger: use it before editing when the user refers to a recipe by name rather than id. It leaves the inverse case (call get_recipe when an id is already known) implicit rather than stated as an exclusion.

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 unknown requestIds are idempotent no-ops and that one mode operates on in-memory unsaved cards rather than persisted data — neither is inferable from the schema. It still does not state what exactly is discarded (the patch and all subsequent ones, or only the target) or any permission requirements, which matters for a destructive 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?

Three short sentences, front-loaded with the core action, then the two modes, then the edge case. No filler. A little jargon ("patch group", "drop") costs some clarity but nothing is superfluous.

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 a six-parameter nested schema, no schema descriptions, and a destructive annotation, the description covers the essential mode split but leaves the patches payload semantics and measurementSystem undocumented. The output schema means return values need not be explained, which keeps this at an adequate rather than poor level.

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 carries the burden, and it does explain targetRequestId and how recipeId/sessionId versus baseRecipe/patches select a mode. However, it never mentions measurementSystem, never clarifies that patches should be the remaining history after the target requestId, and gives no shape hints for the large patch union.

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?

"Drop a patch group by requestId" names a specific verb (drop/remove) and the resource (a patch group identified by requestId), which an agent can map to undoing a prior edit. The wording is somewhat jargon-heavy compared with the title "Revert Recipe Edit", but the intent is recoverable and it is clearly the inverse counterpart to apply_recipe_patches.

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 splits the two calling modes: pass recipeId/sessionId for persisted edits, or baseRecipe plus remaining patch history for a pure unsaved-card Undo. That is a concrete when-to-use-which-path instruction. It does not name sibling alternatives (apply_recipe_patches, update_recipe), so it stops short of full routing 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 already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new context — no ingredient patches are applied, and the recipe payload mode does not persist. However, it never reconciles the destructiveHint=true annotation with the claim of a non-persistent update, nor does it say what the recipeId mode actually overwrites.

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, no filler, with the non-obvious constraint ("without ingredient patches") placed first and the branch conditions immediately after. Every clause carries information 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?

For a four-parameter tool with a deeply nested recipe payload, the description correctly identifies where the payload comes from and what persistence to expect, which is the hard part. The remaining gaps — the sessionId parameter and the measurementSystem values — are small but real against a 0% schema description coverage.

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 does explain the dichotomy between recipeId (saved/session state) and recipe (an unsaved payload from display_recipe). The sessionId parameter is never mentioned, and the measurementSystem enum ('source', 'metric', 'imperial') is not characterized at all.

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 gives a concrete action (set the measurement system) plus a distinguishing claim, "without ingredient patches," that separates it from the closest sibling, apply_recipe_patches. It also names its own input source, display_recipe, making the two operating modes recognizable. It stops short of stating that measurementSystem accepts source/metric/imperial, but the intent is recognizable.

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 spells out the two branching cases: pass recipeId for a saved recipe's session state, or pass the full recipe payload returned by display_recipe to update an unsaved card without persistence. That is real when-to-use guidance tied to specific parameters. It does not explicitly exclude use cases or state what to do if both recipeId and recipe are supplied.

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: the page is public and search-engine indexed, it reflects current recipe state including Sous Chef edits, re-sharing mutates the same link rather than minting a new one, and a signed-in account is required. The re-share behavior concretely explains the idempotentHint and the public indexing explains openWorldHint, so the description enriches rather than repeats the structured data.

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 sentences, each earning its place: action and return value first, then the gating condition, then the risk/auth profile. No filler 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?

An output schema exists, yet the description still confirms the URL is returned. For a single-parameter mutation with public side effects, the auth requirement, permanence/idempotency of the link, and visibility of the content are all disclosed — everything an agent needs before calling.

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% for the single recipeId parameter, so the description must carry the meaning. It establishes that the argument identifies a recipe, but never says where the ID comes from (e.g. from list_my_recipes or get_recipe) or whether a slug/URL is acceptable, leaving the only real gap in an otherwise strong definition.

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 (or refreshes) a public Sous Chef link for a recipe") plus the return value (the URL). The agent can distinguish this from read-only siblings like get_recipe or display_recipe purely from the description.

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?

"Only call when the user explicitly asks to share a recipe" is an explicit when-to-use constraint with a clear exclusion, which is stronger than most. It does not name an alternative sibling (e.g. display_recipe for non-public viewing), so the routing guidance is slightly 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 destructiveHint=true and idempotentHint=false, and the description earns credit for explaining why: images and notes replace the whole array rather than appending, which is exactly the destruction an agent needs to anticipate. It leaves one behavioral gap — whether a partial `meta` object merges with existing meta or overwrites it — which matters for a destructive nested patch.

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 sentences, all load-bearing: scope first, allowed fields and replacement semantics second, exclusion plus alternative last. No repetition of schema types or annotation restatement.

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 explanation, and the description covers scope, exclusions, and array-replacement behavior for a destructive mutation. The unresolved merge-vs-replace semantics for `meta` and the absence of any failure/permission context keep it from fully covering a nested-object patch 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 description coverage is 0%, so the description must carry the parameter burden. It enumerates the patchable fields (title, subtitle, summary, description, images, meta, notes) and adds the array-replacement rule, but it does not explain the sub-fields inside `meta`, the minProperties=1 constraint, or the role of `recipeId`, leaving real meaning 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?

States a specific verb and resource ("updates allowed fields on a saved recipe in your library") and immediately bounds the operation to a named field set. The closing clause names the sibling it is not (apply_recipe_patches) and the content it will not touch (ingredients, steps), so an agent can separate it from add_recipe or apply_recipe_patches without reading 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 excludes ingredient/step edits and routes that case to apply_recipe_patches with the reason (cooking-time edits in a session snapshot). It does not cover the other plausible alternatives — revert_recipe_edit for undoing a change, or add_recipe for new content — so the routing is clear but incomplete across the sibling set.

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