Strega Recipes

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

Beyond the annotations, the description explains that prepared lists are saved for signed-in cooks, return a shareable URL and id, and come back unsaved for signed-out cooks unless keep=true triggers sign-in. It also discloses that allergy warnings are private and not saved in the shareable list, which is valuable behavioral context not captured by 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 information-dense and front-loads the core purpose before usage examples and behavioral details. It is somewhat packed with semicolon-separated caveats, but nearly every clause adds operational value for this relatively complex tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, eight parameters, annotations, and an output schema, the description is complete enough for correct invocation. It covers the main behaviors an agent must know: list merging, pantry handling, allergy warnings, save versus preview semantics, and routing to related tools.

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

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

Schema coverage is already high at 88%, so the schema carries most parameter semantics. The description adds useful meaning for extra_items quantities, pantry handling, likely_have behavior, and the signed-in versus signed-out effect of save/keep, though some parameters such as units and request_key are left to the schema.

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

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

The description states a specific verb and resource: merge recipes and extra items into one aisle-organized shopping list with store-unit normalization. It clearly distinguishes this from related tools by mentioning update_shopping_list and order_groceries, so an agent can identify its role 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?

It gives explicit triggering phrases such as "make me a list" and "what do I need to buy?", plus an example of adding non-recipe items. It also routes follow-up pantry decisions to update_shopping_list and saved lists to order_groceries, covering when and how to use this tool versus alternatives.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the confirmation protocol (cook_confirmed after saying yes), a prohibition ('Never write about-me text for them'), privacy guarantees ('Nothing private is ever on a profile'), and the ai_chef return flag. These are substantive behavioral facts the annotations do not convey.

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

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

Front-loaded with the core read/write split, and every sentence carries information (triggers, handle sourcing, confirmation, return flags, privacy). It is dense and packs many clauses into one block, slightly reducing scannability, but nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and 100% parameter coverage, the description nonetheless summarizes returns (name, about, links, public recipes with urls, ai_chef) and adds the privacy and confirmation context an agent needs. Nothing required for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real intent-level guidance: handle sourced from shared_by.handle or omitted for self, and update should pass 'only the fields to change' gated on cook_confirmed. It stops short of covering every field's semantics (delegated to the already-rich schema), so a 4 is appropriate.

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

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

States a specific verb+resource ('Read a cook's public Strega page, or change the signed-in cook's own') and covers both the read and write modes precisely. An agent can distinguish it from sibling tools like update_recipe or get_my_kitchen 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?

Provides concrete trigger phrases ('who shared this?', 'show me more from this cook'), explicitly states how to select a read of another cook (pass handle from any recipe's shared_by.handle) vs the signed-in cook's own (omit handle), and spells out the update precondition (tell them what will change, get a yes). Exclusions and alternatives are clear.

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 flag a non-readOnly, open-world, non-idempotent write; the description adds the consequences: publication is public by default and appears under My recipes unless visibility is 'private', duplicates are refused, and the call returns a url plus warnings. That is meaningful context the annotations cannot express.

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?

Single dense paragraph with the core rule (draft_id, confirmed draft) front-loaded and each remaining sentence carrying a distinct constraint. It is tight but runs long as a wall of clauses, which slightly hurts scannability for a 15-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the mutation workflow, duplicate behavior, visibility consequences, tested semantics and return value, and the output schema handles the response shape. It never states the minimum viable payload (at least one ingredient and one step), which is the main gap for a create tool with zero required parameters.

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?

At 53% schema coverage across 15 params, the description adds real semantics for the hardest fields: steps must use {tag} syntax rather than typed amounts, tested reflects only a cook-confirmed timed cook, visibility defaults to public. It stays silent on tags, servings, prep_minutes and cook_minutes, so it does not fully close 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?

Opens with a specific verb+resource ('Publish a recipe to Strega') and immediately scopes it against siblings: draft_id comes from draft_recipe, and an exact duplicate is refused with a pointer to update_recipe. An agent can distinguish this from draft_recipe, save_recipe, fork_recipe and update_recipe without opening any schema.

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

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

Gives explicit branch conditions: use draft_id after the cook confirms the draft and pass only changed fields; use bare fields only for a recipe worked out in-conversation after showing it; use update_recipe for a duplicate. It also states when to set tested and that the agent must ask rather than assume, which is a real when-to-use boundary.

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 the two-phase protocol: without confirm it is a dry run that reports what would go and whether deletion is possible; the caller must get a named yes first. It also explains the eligibility rule (no versions, reviews or saves by others) and that the alternative path is reversible where this one is not.

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

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

Front-loaded with the action and precondition, then the confirm protocol, then the fallback — a sensible escalation order. It is dense but nearly every clause carries decision-relevant information; the quoted user phrasings are useful but cost some 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?

For a destructive two-parameter tool with annotations and an output schema, everything an agent needs to act correctly is present: eligibility precondition, the confirm round-trip, what the non-confirmed call returns, and the exact alternative when deletion is refused.

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 baseline is 3, but the description adds real meaning: confirm: true is gated on a spoken yes to the recipe by name, and the unflagged call is a non-destructive preview. The slug parameter is framed by its ownership constraint and its failure mode (the answer redirects to update_recipe).

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 ("Delete a recipe") plus the ownership precondition ("the cook owns") and the hard eligibility gate ("nobody else has touched it"). It also names the sibling it is confused with by pointing to update_recipe as the fallback, so an agent can distinguish it without opening either schema.

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

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

Gives explicit trigger phrases ("delete that test recipe", "get rid of it"), an explicit when-not path ("A recipe others have cooked or saved can't be deleted"), and names the alternative tool with the exact parameters to use instead (update_recipe({ unpublished: true })). Nothing is left to inference.

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

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

Annotations only declare non-readonly, open-world, non-idempotent, non-destructive; the description adds the genuinely new facts: nothing is published, a draft id exists for a later create_recipe call, and two named result states ('existing', 'blocked') with the required agent response for each. That is exactly the kind of workflow and side-effect disclosure annotations cannot carry.

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

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

Purpose and the no-publish guarantee are front-loaded in the first two sentences, and the trailing sentences are all load-bearing state-handling rules. The prose is dense and clause-heavy ('existing means ... blocked means ...') which slows parsing slightly, 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?

For a 4-parameter, open-world draft-creation tool with an output schema, the description covers the full lifecycle an agent needs: inputs (text/url/photo read-through), what the draft is, the confirmation-and-publish next step, and behavior for the two non-happy-path outcomes. No gaps remain that would cause a miselection or misequence.

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, but the description adds conditional usage the schema only hints at: add_anyway is gated on the cook asserting it's a different recipe, and source_url is prescribed specifically for the paywalled/'blocked' case. It does not add format detail for url vs text beyond the schema's own 'pass text or url, not both'.

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 ('turn a recipe ... into a draft') and enumerates what the draft contains: matched ingredients, plain-word steps, servings, times, timers. It explicitly separates itself from the publish path ('Nothing is published ... publish with create_recipe({ draft_id })'), so an agent can distinguish it from create_recipe and save_recipe without opening either schema.

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

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

Gives concrete trigger utterances ('save my grandma's meatballs', 'add this one' with a link, a photographed card) plus the handling rule for the photo case (read it yourself and pass the text). It also routes on outcomes: 'existing' → send them to save_recipe/fork_recipe, add_anyway only if it's a different recipe, 'blocked' → pass page text with source_url.

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 this is a non-read-only, non-destructive, open-world write. The description adds substantial behavioral context on top: default visibility is public, "private" scopes it to the cook, passing only changed fields creates a partial fork, and a repeated identical change returns the existing version (already_existed) rather than duplicating. Minor tension: that dedup behavior reads as idempotent while idempotentHint is false, though the disclosure itself is accurate and useful to the agent.

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

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

Front-loaded with the core action and tightly packed — nearly every clause carries a rule an agent needs. The single dense paragraph mixes several distinct policies (confirmation, visibility, dedup, refusal), which costs some scannability but wastes little.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the full decision surface for a mutation tool of this complexity: prerequisites, confirmation discipline, partial-vs-full list semantics, default visibility, dedup outcome, and the sibling to use instead. An output schema exists, so return-shape explanation is correctly left out.

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?

At 50% schema coverage the description compensates on the highest-risk semantics: partial saves are allowed, but ingredients and steps, if supplied, must be the complete new list, and the fork is auto-named unless title is passed. It leaves several fields (servings, cook_minutes, prep_minutes, tags, seasons, chef_note, author, yield_label) to the schema, which documents most of them, so the gap is modest rather than critical.

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

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

States a specific verb and resource: saves the cook's own version of someone else's recipe, linked to the original, with the original left unchanged. It also explicitly distinguishes itself from update_recipe and notes that this tool refuses on the cook's own recipe, so an agent can pick between the two without opening either schema.

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

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

Gives concrete trigger utterances ("make it dairy-free and keep that", "halve the sugar", "save it for 8"), a prerequisite step (get_recipe first and edit it), a mandatory confirmation gate (show the changes, get a yes, never save silently), and the explicit alternative for the opposite case (update_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?

Goes well beyond the annotations: discloses latency (up to a minute), the source of the drawing (recipe's own text), mandatory labeling ('Illustration, not a photo of this dish' everywhere), that it never counts as a photo, and that refusing to replace a cook's photo is a refusal rather than an error. The refusal-vs-error distinction is exactly the kind of behavior an agent cannot infer from readOnlyHint/openWorldHint/idempotentHint.

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

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

Purpose is front-loaded, then usage, then behavior — a good ordering with no filler. The middle sentence is a dense compound that packs labeling, counting, and replacement rules together, costing some readability.

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 values need no explanation; the description instead covers the things that matter for correct invocation: consent, latency, labeling guarantees, and the disabled-feature path. Nothing an agent needs is missing.

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

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

Schema coverage is 100% and the single 'slug' param is documented, so the baseline is 3; the description adds real constraint semantics by restricting it to recipes the cook owns and that lack a photo. It does not clarify what happens if the recipe already has a photo, beyond the refusal note.

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 ('draw a labeled illustration of the dish'), plus the scoping condition ('a recipe the cook owns that has no photo'). The output is distinguished from a photograph, so an agent can tell it apart from photo-related and recipe-creation 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?

Names concrete trigger phrases ('it needs a picture', accepting the offer after create_recipe), requires asking first, and gives an explicit fallback when image generation is off (point to website photo upload). Both when-to-use and when-not-available are covered.

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 and openWorldHint=false, and the description adds genuinely new operational context: "Works signed out" (auth requirement), the delivery convention of one step per reply, and the instruction to offer the step's timer. It does not contradict the annotations, though it says nothing about paging limits or what happens past step 60.

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

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

Front-loaded with the core concept, then usage triggers, then delivery instruction. Dense but nearly every clause carries information; the parenthetical parameter routing and the checklist-on-phone note both earn their 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?

An output schema exists so return values needn't be explained, and the description covers the remaining gaps for an 8-parameter tool: auth state, per-reply delivery, and step-vs-range semantics. It leaves units/servings/allergens entirely to the schema, which is acceptable given 75% coverage, but the interaction between servings and step amounts is never addressed.

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 schema coverage at 75% the schema carries most parameter documentation, but the description still adds routing meaning: step returns just that one step while from_step returns that step and the rest. That is framed in terms of user intent rather than field types, which is real added value over the schema text.

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?

It states a specific verb (get) and resource (cook steps) and defines the exact return shape: a gather list followed by one step at a time with amounts, ingredients, tip and timer. That is distinctive against the sibling set, which contains get_recipe (full recipe) and search_recipes, because it makes clear this is a cooking-along feed rather than a document fetch.

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 literal user triggers ("walk me through it", "I'm cooking it now", "what's next?") and routes between the step and from_step parameters by user situation (single step vs. resume after a pause). What it lacks is an explicit exclusion naming get_recipe as the choice when the user wants the full recipe at once rather than walking through it.

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 readOnlyHint annotation, it discloses that pending_photos returns at most 30 private choices plus an observed version, that it neither claims recipes nor acknowledges notices, and that explicit confirmation is required before update_recipe recover_photo — 'never auto-attach or auto-confirm'. It also specifies ordering obligations for newly_assigned and fixes_asked, which annotations cannot convey.

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

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

Front-loaded with the resource enumeration and trigger phrases, and every sentence carries operational content (confirmation gating, notice-handling rules). It is dense to the point of being a wall of text with an embedded '(section: photos)' aside that slightly interrupts flow, but little 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?

For a zero-required-parameter read tool with full schema coverage, an output schema, and readOnly/openWorld annotations, the description supplies everything needed: what each section returns, pagination behavior for pending_photos, and the follow-up actions and confirmations required. No material gap remains for correct invocation.

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

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

Schema coverage is 100%, so the schema already defines every parameter; the description adds semantics the schema does not, notably the photos vs pending_photos split, why target_recipe gates that section, and the confirmation workflow around the returned choice. The limit/pending_cursor interactions remain documented only in the schema, so it does not fully exceed baseline.

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

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

The description enumerates the exact resources the tool returns (saved recipes, published recipes, versions, shopping lists, meal plans, ratings, pantry count) and anchors it with 'Same as My Kitchen on the website', which separates it from siblings like get_recipe or search_recipes. The verb itself is implied ('what the cook keeps') rather than stated as 'retrieve', which keeps it just below a top score.

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

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

It gives explicit trigger phrases ('what did I save?', 'pull up last week's list', 'show my recipes') and explicitly scopes the photos section with a sample question. It also states conditional branches: pending_photos only for an explicitly requested interrupted photo save, and what to do when newly_assigned or fixes_asked are present, naming alternatives (update_recipe recover_photo, hand_back_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 read-only/idempotent/non-destructive profile, and the description adds real context: the returned recipe-as-written basis (US units, original servings), a content_token for chaining, and an authorization boundary ('No author access to other cooks' private feedback'). It stops short of error behavior or pagination, but adds meaningful transparency beyond 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?

Purpose is front-loaded, but several sentences are agent operating instructions ('show the referenced step and amounts, ask the cook to review them') mixed with the tool description. It's information-dense but overloads what should be a simple read tool's scope statement.

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 values needn't be detailed, and annotations cover safety, so the description focuses well on privacy scope, workflow, and inference limits. The one notable gap is the undocumented slug parameter, but overall it's complete enough to invoke 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% and there is a single required 'slug' parameter that the description never explains (where it comes from, what it identifies). The description instead discusses content_token, which is a return value, not this tool's input, leaving the actual parameter 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 opens with a specific verb and resource: 'Read only the signed-in cook's saved private feedback and the recipe-as-written context.' The privacy scoping ('only the signed-in cook's') distinguishes it from get_recipe and other siblings, though the boundary against get_recipe returning feedback isn't stated outright.

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 concrete workflow guidance: show the referenced step and amounts, have the cook review them, and pass the content_token to rate_recipe. It also states when not to act ('Never infer stars, made-it, repeat choice or substitutions from a note'). Explicit context is present, though it doesn't enumerate alternatives beyond rate_recipe.

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

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

Beyond the readOnly and openWorld annotations, the description discloses important behavior: counts only, never identity, the cook's own activity excluded, and a precise definition of what counts as a cook. It also states presentation order, cross-references /me/stats parity, and says to quote definitions.cook when definitions are asked about.

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

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

The description is front-loaded with the core purpose and metrics, then moves to usage, privacy/definition constraints, and presentation guidance. Every sentence carries operational value, including the example questions and the /me/stats parity note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists and schema coverage is complete, the description provides enough complementary context: what is counted, what is excluded, how results should be presented, and where to point users for metric definitions. No essential invocation detail is missing.

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

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

Schema description coverage is 100%, so both range and recipe parameters are already documented in the schema. The description adds useful metric context ('in total and by day, per recipe and by region') but does not add parameter-specific syntax, format, or edge-case guidance beyond the schema.

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

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

The description names a specific verbless but precise resource: the cook's own recipe performance across views, shares, prints, cooks, saves, versions, and ratings. It clearly scopes this to the cook's own recipes and contrasts with identity-level feedback by saying 'Counts only, never who.' An agent can distinguish it from siblings such as get_my_recipe_feedback and get_my_kitchen.

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

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

It gives clear usage context with example questions like 'how's my recipe doing?' and 'what's my most popular recipe?' and specifies the audience as a cook who publishes. It also bounds interpretation with 'Counts only, never who' and 'cook's own activity is left out,' but it does not explicitly name alternative sibling tools for related questions.

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 readOnlyHint annotation, the description discloses key behavior: the recipe is scaled to servings, ingredient amounts are written into the steps, units can follow the cook's requested per-ingredient units, and ignored units are returned. It also explains substitution behavior, version handling, allergen implications, and that the tool works signed 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?

The opening sentence is front-loaded and useful, but the second sentence is a long chain of parenthetical usage scenarios and follow-up instructions. It remains informative, yet the density and run-on structure reduce readability and 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?

Given the complex parameter set and available output schema, the description is complete enough for an agent to call it correctly. It covers retrieval, scaling, units, substitutions, allergen handling, returned fields, and follow-up actions without needing to duplicate every schema detail.

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

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

The schema already has 100% description coverage, including detailed explanations for units, servings, allergens, units_for, substitute, and unknown_ingredients. The description mainly reinforces those semantics rather than adding substantial new parameter-level meaning, so the high-coverage baseline of 3 applies.

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

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

The description clearly identifies the resource and scope: one recipe in full, scaled, in US or metric units, with amounts embedded into steps. It also distinguishes its role from neighboring tools such as fork_recipe and update_recipe by explaining when those are downstream actions rather than retrieval.

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

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

It gives explicit triggers: use when the cook picks a recipe, asks for a specific unit conversion, or wants a dietary change. It also names alternatives and follow-up actions, including fork_recipe for saving a modified copy and update_recipe for the cook's own recipe.

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

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

Beyond the annotations (destructive, idempotent, non-read-only), the description adds the confirmation workflow and the 'works once per recipe' constraint, which an agent needs to avoid retry loops. It stops short of saying what happens to the recipe after hand-back (removed from the kitchen? returned to Strega?), which is the one behavioral detail left implicit.

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

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

Three tight sentences: action and target set first, then the negative default, then the precondition and the once-per-recipe limit. 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?

For a one-parameter destructive mutation with an output schema, this covers the trigger, the safe default, confirmation, and the repeat-call limit. The only gap is the post-condition of the hand-back, which an agent might want before confirming with the cook.

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, `slug`, with 0% schema description coverage, so the description must carry the load. It partially does by pointing at `get_my_kitchen newly_assigned` as the source of the target recipes, implying where the slug comes from, but it never says the parameter is a recipe slug or what format it takes.

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 ('hand back') and resource (a recipe added by the Strega team), and pins the target set to `get_my_kitchen newly_assigned`, which distinguishes it from delete_recipe and other recipe tools. An agent can identify both the action and the exact subset of recipes it applies to.

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 ('when the cook says "that one isn't mine"'), an explicit default to not act ('Keeping it is the default and needs nothing'), and a prerequisite ('Confirm with the cook first'). This is a full when/when-not/alternative statement.

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 this is not read-only and is open-world, but the description adds substantial behavior: cart previews, confirmation, saved-store behavior, share URLs, sign-in ownership, and commission disclosure placement. It clearly explains what side effects occur before and after ordering.

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

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

The description is front-loaded with the action and then follows the ordering workflow, but it is dense and parenthetical. Most sentences earn their place for a complex 12-parameter tool, though slightly more structure would improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity, high schema coverage, output schema, and annotations, the description covers the key workflow an agent needs: when to use it, how saved stores work, when previews and confirmations are required, and how to share results. Nothing critical is missing for correct invocation.

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

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

Schema coverage is very high at 92%, so parameter meanings are mostly already documented. The description still adds workflow semantics for preview_id, confirm, edits, store, and zip saving, which helps an agent understand how parameters interact across calls.

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: sending a shopping list to a grocer for delivery. It distinguishes the tool from list-building siblings by explaining that it hands a list to a grocer, and it names the cart/list-link/search-link outcomes.

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

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

It gives explicit trigger phrases such as "order these" and "get it delivered", plus the no-saved-store flow and the preview-before-confirm workflow. It does not explicitly say when to use sibling tools like build_shopping_list instead, but the ordering context is clear.

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 explains consent semantics: saying what they have counts as approval to save it. It also warns never to add items the cook did not mention and explains what the return value contains, including an 'unsure' list for text that did not read as food.

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

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

The description is front-loaded with purpose and packed with useful behavior rather than filler. It is dense and somewhat run-on, but most clauses earn their place given the tool's read/write modes and safety rules.

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 description covers purpose, usage triggers, input modes, consent behavior, mutation limits, and return shape. With an output schema present and annotations covering safety, it provides more than enough context for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful semantics for key parameters: text should be verbatim, add/remove take names, photo takes an upload name, and no arguments performs a read. It does not explain replace or staples in the prose, but the schema already documents those well.

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 read/change capability over the cook's pantry, inventory, and staples. It also clarifies scope by noting these are items left off shopping lists and used for what-can-I-make, which separates it from purely recipe or shopping-list tools.

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

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

It gives clear triggers: when the cook states what they have, reports running out, corrects the pantry, or asks what is in it. It also explains the calling modes (verbatim text, add/remove names, photo, or no arguments), though it does not explicitly name sibling alternatives or when not to use this tool.

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

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

Annotations only cover safety profile (readOnly=false, idempotent, non-destructive), but the description adds substantial behavior beyond that: nothing is ordered, no second offer, signed-out calls return unsaved with keep:true triggering sign-in, and the request_key idempotency window is clarified. This is exactly the extra context annotations don't carry.

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

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

Front-loaded with the core action and outputs before usage and behavioral rules, and every clause carries information. It is dense and somewhat run-on across many semicolons, but little is wasted given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 17 params and an output schema (so return format needn't be described), the description covers the critical behaviors: save vs preview, sign-in fallback, swap routing, and stop-and-wait. Minor gaps on some parameter semantics remain, but an agent can 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?

With 17 params at 71% schema coverage, the baseline is ~3, and the description lifts it by tying natural-language intents to max_budget, occasion, guest_notes, and the save/keep signed-out behavior. It still leaves several params (tags, units, servings, pantry, exclude_ingredients) to the schema alone, so not a full 5.

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

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

States a specific verb and resource ('Plan dinners and return the finished week in one call') and enumerates the concrete outputs (picks by day, merged shopping list, prep_order, substitutions, say). It also differentiates from the sibling update_meal_plan by routing swaps there, so an agent can distinguish it 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 explicit trigger phrases ('what should we eat this week?', 'four dinners under $80', people over) and maps them to parameters (max_budget, occasion, guest_notes). It also names the alternative path ('A swap goes to update_meal_plan with plan_id') and the stop condition after showing the plan.

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 only establish that this is a non-read-only, idempotent, non-destructive mutation; the description adds the crucial confirmation protocol: pass the change without cook_confirmed and nothing is saved, ask the cook via confirm.say, then retry with cook_confirmed. It also discloses that lists replace saved lists and that sensitive fields require confirmation.

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 but front-loaded: the first sentence states purpose and scope, and the remaining sentences give only operational rules. For a 20-parameter mutation tool, the length is justified and no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and annotations plus schema descriptions cover safety and many fields, while the description covers the high-risk confirmation workflow and read/write distinction. It omits some parameter families such as pantry and nutrition_targets, so it is strong but not fully complete.

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

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

With 20 parameters and 60% schema description coverage, the description adds important meaning beyond the schema for cook_confirmed, no-argument reads, list replacement, and sensitive categories. Many field-level details remain in the schema, so it is helpful but not exhaustive.

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

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

It opens with a specific verb pair, 'Read or change', and the resource 'cook's Strega preferences', then enumerates the categories and states 'No arguments reads them.' The purpose is very clear, but it does not explicitly distinguish itself from a sibling such as cook_profile, so it is a 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?

It gives explicit conditions: a no-argument call reads, a cook's own-words change uses cook_confirmed, sensitive settings such as allergies and privacy require a yes first, and the agent must never infer an allergy or diet. It does not name a sibling tool as an alternative, so the alternatives edge is missing.

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 (readOnly=false, idempotent=true, destructive=false) by explaining update-in-place semantics ("One rating per cook per recipe: calling again updates it"), preservation rules ("a comment left out is kept"), the refusal case, the 2,000-character combined limit, and that made_it completes a cook and may trigger a pantry deduction. The null-vs-omitted distinction for optional answers is exactly the kind of contract the schema can't express.

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

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

Front-loaded with purpose, then triggers, then invariants, then parameter contracts — a sensible order with no filler sentences. It is dense and rule-heavy; a few of the trailing constraints could be grouped more crisply, but every sentence carries operative information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter mutating tool it covers the full contract an agent needs: required inputs, authorization refusal, idempotency, omission vs clearing, size limits, and the cook-completion side effect. Return values are out of scope because an output schema exists.

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 30% schema description coverage across 10 parameters, the description compensates well: it clarifies stars must be explicit, comment preservation on omission, made_it semantics, content_token's source and prerequisite step context, and clearing behavior via null/empty arrays. It leaves `name` and `would_make_again`/`substitutions_made` enum values to the schema, which is reasonable since the schema is explicit there.

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

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

Opens with a specific verb+resource pair ("Post the cook's star rating (1 to 5) and comment") plus the side effect of marking a cook as made. It also names a sibling (get_my_recipe_feedback) as the source of content_token, so the agent can distinguish this write tool from the read-side feedback tool.

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

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

Gives concrete trigger utterances ("that was great, five stars", "I made the chili, a bit too salty"), an explicit guard against inferring data ("Keep stars explicit; never infer completion or preferences from notes"), a fallback instruction ("ask for the stars if they didn't give any"), and an exclusion ("Refuses the cook's own 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 declare readOnlyHint=false and destructiveHint=false, and the description adds the crucial behavioral fact that 'Moderators review every report; nothing is hidden automatically' — i.e., the write creates a queued report, not an immediate takedown. It does not mention auth requirements or any rate/duplicate-report handling beyond the idempotentHint.

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

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

Two sentences, front-loaded with the action and targets, then the gating rule and the moderators-review guarantee. Every clause carries information an agent needs; nothing is redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and 75% param coverage, the description needn't explain return values, and it correctly focuses on the human-review consequence of a non-read-only call. Minor gaps remain around whether a cook can report their own content and what happens on an invalid id.

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 75% with both enums already documented in-schema, so the schema does the heavy lifting. The description's reason list mirrors the enum and 'in their words' mildly reinforces that the note should be a verbatim quote, but it adds no syntax or format detail for id or kind.

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 ('Flag ... for Strega's moderators') plus the full set of target resources (recipe, review, photo, cook's profile), which no sibling tool covers. An agent can immediately distinguish this moderation tool from the CRUD/planning 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 an explicit trigger condition ('Use only when the cook asks') with two representative utterances, which functions as both a when-to-use and a when-not-to-use rule. No sibling overlaps, so no alternative needs naming.

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 idempotentHint=true and destructiveHint=false; the description reinforces this with "Saving twice is harmless" and clarifies that unsaving is a deliberate, opt-in action. It also mentions return content, though an output schema exists, so that adds limited extra value.

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

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

Three short sentences, front-loaded with the core action, followed by trigger phrases and a return note. Zero 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 two-parameter, idempotent toggle tool with an output schema and full schema coverage, the description covers everything an agent needs: the action, when to trigger it, the unsave semantics, and idempotency.

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

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

Schema coverage is 100% and both parameters are already documented in the schema, including the meaning of saved:false. The description reinforces the boolean semantics in natural language but adds no syntax or format details beyond the schema.

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

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

States a specific verb+resource pair (save/unsave a recipe into the cook's Saved list) and names where that list lives (My Kitchen). This is clearly distinguishable from siblings like update_recipe or get_my_kitchen.

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

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

Gives concrete trigger phrases ("save this", "add it to my favorites") and explicitly says saved:false should be used "only when the cook asks" for removal. It lacks a named alternative tool for comparison, but the when-to-use context is unusually clear.

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 readOnly/openWorld=false, and the description adds substantial non-obvious behavior: allergies/diet/avoid list are applied automatically, the cook's own recipes rank first, results are short summaries keyed by slug/url, and public recipes work when signed out. The `hidden` result behavior is fully specified, including the required response protocol (don't re-ask, state the reason first, never present 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?

Front-loads the core purpose and trigger examples, then moves to output shape and edge-case handling. The hidden-recipe instruction is a long multi-clause run-on ('don't stop to ask; go on with that slug, tell them why...') that costs some readability, 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 13-parameter, no-required-param search tool with an output schema, the description covers everything needed to call it correctly: what comes back, how filtering defaults behave, and the one genuinely tricky case (hidden recipes) with explicit guidance. Return-value detail is rightly left to 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 coverage is 92%, so the schema already documents nearly every parameter in depth. The description adds only marginal meaning — the `mine: true` usage note and a loose mapping of keywords/ingredients/time/diet to parameters, both of which restate what the schema says. Baseline 3 is appropriate here.

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

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

Opens with a specific verb+resource and scope: 'Find recipes on Strega by keywords, ingredients, time or diet.' It also explicitly delineates the boundary with get_recipe ('get_recipe has the full recipe'), so an agent can distinguish the two sibling tools 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 concrete, quotable trigger utterances ('what's for dinner?', 'something with the spinach I have') that map directly onto parameter combinations, and states the alternative path ('use suggest_from_pantry' is in the schema; 'get_recipe has the full recipe' in the description). It also specifies the when-signed-out case.

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 readOnlyHint/openWorldHint: it discloses that the saved pantry is the default input, that staples are assumed, and that allergies, diet and avoid-list are silently applied — all things an agent must know to interpret results honestly. It also tells the agent how to present results (top few, have/missing line, url). It stops short of covering empty-result or limit behavior, so not 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?

Dense but front-loaded — the ranking premise and the output shape come first, then usage triggers, then parameter guidance. Every clause carries information, though the parenthetical example sentence is slightly long for what it adds.

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 needn't be spelled out; the description still adds the one thing the schema can't — how to read and present the have/missing line. Combined with the pantry/allergy/staples semantics, an agent has everything needed to call this correctly and interpret the result.

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 50%, and the description compensates for most of it: pantry is explained as a signed-out/what-if override, must_use as hard requirements, query as keywords, plus tags and max_minutes as narrowing filters. Only 'limit' is left to the schema, which is acceptable given its default.

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 (recipes ranked by pantry coverage) and immediately differentiates itself from a plain keyword search by describing the have/missing line output. An agent can tell this apart from search_recipes or build_shopping_list 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 explicit trigger phrases ('what can I make?', 'what can I do with chicken and rice?'), a named mode (must_use for 'the chicken has to get used tonight'), and the exact condition for overriding the saved pantry ('signed out, or for what if I had…, pass pantry'). It also routes the follow-up ('a list of just the missing items is the natural next step'), which points at the shopping-list sibling.

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, it discloses that changes are in place, other days are preserved, a swapped-out dinner counts against later plans, and the whole plan is recomputed. The annotations already mark it as non-readonly and non-destructive, so this additional context is meaningful.

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 core operation and when to use it. It includes return-value and follow-up guidance that is useful but slightly more than strictly necessary given the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex mutation tool with seven parameters, the description covers operations, constraints, plan_id sourcing, behavioral side effects, return contents at a high level, and follow-up. The input and output schemas carry the detailed field and return structure.

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 high at 86%, so the schema already documents most parameters. The description reinforces constraint semantics like faster, max_minutes, tags, query, and slug, but it does not add much for units, pantry, or with_shopping_list 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 states a specific verb and resource: change the cook's saved meal plan in place, with swap/drop/add operations. It also distinguishes this from creating a plan by requiring plan_id from plan_meals and by emphasizing that other days are kept.

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

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

It gives explicit usage contexts with natural-language examples such as "swap Tuesday for something faster" and "we're out Thursday." It does not name a clear alternative for creating a new plan, but the in-place scope is clear enough to select this tool correctly.

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 declare the generic write profile (readOnly=false, destructive=false, idempotent=false), but the description adds the real behavioral facts: unpublishing is reversible and only affects other people's access, every edit creates a revision that restore_revision can undo, photos pass a photo check that may refuse and leave nothing changed, and cook_confirmed is an assertion rather than proof of consent. The "never save silently" and "never auto-confirm" directives are exactly the kind of context annotations cannot carry.

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

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

Front-loaded with purpose, then routing, then modes, then guardrails — good ordering with no filler sentences. However it is delivered as a single dense paragraph with nested quoted examples, which makes the several distinct workflows (edit, unpublish, photo, tested, restore, recover) harder to scan than a short bulleted structure would be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 21-parameter, nested-object mutation tool with an output schema, the description covers every high-risk path: partial updates, publication changes, photo intake and recovery, revision restore, and mandatory confirmation. Since an output schema exists, the absence of return-value description is appropriate rather than a gap.

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 62%, and the description fills the most consequential gap: "Pass only what changes; ingredients or steps, if passed, are the complete new list" — patch-vs-replace semantics not conveyed by the schema. It also constrains photo (only cook's own, one photo per call, separate call from unpublished), tested (ask, never estimate), and restore_revision (n undoes edit n).

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

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

Opens with a specific verb+resource ("Change the cook's own recipe or version") and immediately scopes ownership. It explicitly names the sibling it is not — "If the cook is not the owner, use fork_remote/change... 'Change the cook's own recipe or version'... 'Change the cook's own... whatever' — and explicitly routes non-owners to fork_recipe, so an agent can pick between them without reading either schema.

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

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

Gives concrete triggering utterances for each mode ("make mine private", "take it down", "use my photo for the cover", "undo that last change", "I made it tonight, took about 50 minutes") plus explicit exclusions. It states prerequisites before calling (show the changed ingredients and steps and get a yes) and names alternatives (fork_recipe for non-owners, get_my_kitchen pending_photos + recover_photo for recovery).

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 mutating-but-non-destructive and non-idempotent; the description adds the state model beyond that – remove counts as "left off", need moves items "to the buy aisles", and it states the list-vs-pantry boundary plus the confirmation step. It does not set expectations about re-running the same call (non-idempotency) or partial failure semantics.

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

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

Front-loaded with purpose then per-parameter behavior, but the sentence structure is dense with parentheticals and the closing "Returns the pared list, its estimate and the order offer" duplicates the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all five parameters, the sibling boundary, the pantry hand-off, and the example utterances an agent needs to map free-form cook speech onto the four arrays; return values are already specified 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 coverage is 100%, so the baseline is 3, but the description adds semantic mapping the schema doesn't: what the items must look like ("as they said it") and what each operation does to list state (removed items counted as left off, set-aside items returned at full size). It goes beyond restating field names.

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?

"Change a saved list" names a specific verb and resource, and the opening clause ties it to the two siblings that produce the list (build_shopping_list, plan_meals). An agent can tell this is the mutation tool for an existing list rather than the creation tool.

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 trigger conditions with quoted cook utterances ("I have the flour and oil", "I'm out of chili flakes", "skipped the salmon...") and explicitly routes pantry-remembering elsewhere: "Changes only this list, never the pantry: ask ... first, then call pantry."

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