ask.recipes

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

Adds context beyond the annotations: existing items are updated to the new quantity (overwriting the prior amount, consistent with destructiveHint=true), name matching is loose/case-insensitive, and the whole pantry is returned. It does not spell out what happens if an existing item is re-added with no quantity, which leaves the mutation semantics partially ambiguous.

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

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

Four short sentences, zero waste, each front-loading the most decision-relevant fact in order: what it does, input source, update semantics, matching semantics, return value.

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 tool with a full output schema and annotations, the description covers the important gaps (loose matching, restock-in-place behavior) and needn't explain return values. The remaining hole is the merge rule when an existing item is supplied without a quantity.

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 nested name/quantity fields are already documented, making 3 the baseline. The description adds meaning to the 'quantity' field (free-text amounts in the user's words) but does not add format or edge-case guidance for the 'add' array beyond what the schema states.

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 (add or restock) and resource (pantry items), plus the input source ('what the user says in passing') with concrete examples. An agent can distinguish this from remove_from_pantry or get_pantry 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 a clear usage context – freeform phrases like 'bought rice and two chickens' or 'here's what's in the fridge' – which tells the agent when this tool applies. However, it never names the alternative (get_pantry for reading, remove_from_pantry for deletion) or states when not to use 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?

Adds real behavior beyond the annotations: the returned link is one-time and expires in 15 minutes, and the user—not the tool—enters credentials. That explains why the tool is non-destructive yet not readOnly (it mints a session). It does not say what the response looks like when already connected or whether the agent must re-poll after the user completes the flow, leaving a small gap.

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 triggers, then the operational caveat about expiry. No filler and nothing repeated from the title or annotations.

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 tool with an output schema, the description covers everything an agent needs: when to call it, what the user must do, and how long the returned artifact is valid. Return-value details are appropriately delegated 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. Calling convention is fully determined by the tool name and description.

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

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

States a concrete verb and resource ('Check whether the user's Cookidoo account ... is connected') plus the fallback behavior (returns a one-time login link). It disambiguates from siblings by naming the Thermomix/Bimby alias and by implying this is the entry point rather than the actual import/send operations handled by other 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?

Gives explicit trigger phrases ('connect my Thermomix', 'link my Bimby') and a concrete sequencing rule ('before the first send_to_thermomix'), naming the sibling that depends on it. It also tells the agent to hand the link to the user, so the invocation context is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: newest-first ordering, the default 30-day window and what lifts it, and the shape of each entry (day, note, recipe summary with source link).

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 ordering are front-loaded, the example utterances are tightly grouped, and the workflow hint follows. The closing sentence on the 30-day default duplicates the schema text, a small redundancy that keeps it out of the top band.

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 full schema coverage, rich annotations and an output schema, everything an agent needs is present: what it returns, default scope, ordering, and when to invoke it. No meaningful gap remains.

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 all four parameters are already documented. The description's statements about the 30-day default and recipe_id lifting it restate the schema rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb and resource (list cooked history) plus ordering ('newest first'), and the example utterances ('when did I last make the lasagna') make the retrieval shape unambiguous against siblings like mark_cooked or get_recipe.

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

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

Explicitly says to call it before planning a week so plans avoid repeating dishes and ingredients, which gives a clear triggering context. It stops short of naming an alternative tool or stating when-not to use it, so it falls just under the top band.

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

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

Annotations already declare readOnly=false, destructive=false, non-idempotent, closed-world, so safety is covered. The description adds value beyond that with the duplicate-name failure mode and the cross-user visibility consequence of shared=true, which no annotation expresses. It stops short of describing the return value, but an output schema exists.

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, each doing distinct work: create, sibling routing, and shared semantics. The opening quoted example is slightly awkward, but nothing is padded or 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?

With annotations covering mutability and an output schema covering returns, the remaining burden is when-to-use and edge cases—both addressed (duplicate name, save_recipe overlap, household prerequisite). Minor omission: no statement about what permissions or scope the new cookbook lands in beyond shared.

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 all three parameters are already documented—including the household requirement for shared and example names. The description's shared=true sentence mostly restates the schema's own wording, adding only the household-scoping phrasing; baseline 3 applies.

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

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

States a specific verb and resource ('Create an empty cookbook') and immediately anchors it to a real-world intent ('make me a BBQ cookbook'). Crucially, it distinguishes itself from save_recipe, the sibling that also creates cookbooks, so an agent can tell the two apart without opening schemas.

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

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

Explicitly says when this tool is NOT needed ('Not needed before save_recipe, which creates a cookbook it does not know'), which is exactly the routing decision an agent would otherwise get wrong. It also names the failure condition (duplicate name), giving a clear precondition.

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

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

Beyond the annotations' destructiveHint and idempotentHint, the description explains the actual consequence: no recipe is lost, and recipes only in that cookbook move to the default. This is exactly the behavioral context an agent needs before invoking 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 action, followed by the key safety behavior and the main restriction. Every sentence carries useful 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 one-parameter destructive tool with annotations and an output schema, the description covers purpose, side effects, and the key restriction. 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 description coverage is 100%, and the input schema already documents the single cookbook parameter in detail. The description adds only "by name," so it meets the baseline without adding substantial parameter semantics.

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

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

The description states a specific verb and resource: "Delete a cookbook by name." This clearly distinguishes it from create_cookbook and update_cookbook without requiring schema inspection.

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 a clear usage condition and an explicit exclusion: the default cookbook cannot be deleted. It does not name sibling alternatives, but the delete operation is unambiguous.

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=true, and the description adds real value beyond that by scoping what is and isn't destroyed: only the stored login goes, while already-sent and imported recipes persist. It stops short of saying whether re-authentication is required afterward or what happens on disconnect failure.

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, both front-loaded and load-bearing: the first defines the action, the second preempts the most likely agent/user misconception about data loss.

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, no parameters, and annotations carrying the safety profile, the description covers everything an agent needs to invoke it correctly. Only the post-disconnect state (e.g., whether the account must be reconnected) is left implicit.

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, which is the baseline-4 case; there is nothing for the description to compensate for and the empty schema is fully consistent with the no-argument behavior described.

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 ('Remove') and resource ('the user's stored Cookidoo login') scoped to ask.recipes, which lets an agent distinguish it from connect_cookidoo and the recipe-level 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?

The description implies when the tool applies (removing a stored login) but never names an alternative or an explicit when-not condition, such as pointing to connect_cookidoo for re-authentication or clarifying that it doesn't touch Cookidoo-side data.

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

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

Annotations already declare read-only/idempotent, so the description correctly spends its words on non-obvious behavior instead: pantry ingredients count toward completion ranking, saved profile silently applies allergen/dislike exclusions and a default time budget, and max_total_minutes=-1 is the documented escape hatch. The 'check' result field and its implication (verify ingredients via get_recipe before recommending) is exactly the kind of caveat an agent could not infer from structured fields.

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 ranking are front-loaded, and the dense single-paragraph format packs a lot of decision-relevant content with little filler. It is longer than ideal and would scan better with structure, but no sentence is genuinely expendable.

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 24-parameter tool with an output schema and full annotation coverage, the description supplies the missing layer: profile-driven allergen/dislike exclusion, pantry counting, the 'check' flag contract, and the escape hatch for the default time budget. Nothing an agent needs to call this correctly is absent.

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 baseline is 3; the description earns above that by explaining semantics the schema omits entirely — the -1 sentinel on max_total_minutes (which has no schema description) and the profile-derived defaults that filters override. It does not cover 'limit' or 'query' beyond what the schema already says, so it stops short of a 5.

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

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

States a specific verb and resource ('Find recipes that use ingredients the user already has') and immediately explains the ranking logic, which is what makes this tool distinct from search_recipes. An agent can tell this apart from search_recipes and from get_pantry 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?

Explicitly covers the scenarios that select this tool: leftovers/full fridge/about-to-turn ingredient, pantry-only cooking with no ingredients passed, and the degraded case where the pantry is also empty and ask_user should carry the question. It also names the sibling it shares filters with ('takes the same diet, nutrition and exclude_ingredients filters as search_recipes') and the downstream verification step (get_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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description goes beyond them by disclosing the domain consequences of membership (shared pantry, shared cooking diary, shared-marked cookbooks, members' allergens/dislikes applying household-wide) and what in_household=false means. It does not describe caching, privacy scoping, or failure modes, but for a zero-argument read the added context is substantive.

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 identity of the tool is front-loaded in the first sentence and the routing hint is placed at the end where it belongs. The middle sentence about shared pantry, diary and allergens is long and reads more like product documentation than tool guidance, though it does earn its place by explaining why household membership matters to nearby tools.

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, read-only tool with an output schema, the description supplies everything an agent needs: what is returned, how to read in_household, where to go next, and example intents. Return-value detail is correctly 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?

The tool takes zero parameters, which is the baseline-4 case. The description adds a small amount of interpretive value by explaining that in_household is a signal to check rather than an input, but since it is a response field and an output schema exists, no further parameter explanation is required.

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 first sentence gives a specific verb and resource ("Read the user's household: its name and who is in it") plus the exact shape of the returned identity data. It is clearly distinguishable from write-side siblings like update_household, invite_to_household and leave_household, which the description implicitly frames as the alternative paths.

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 names a concrete alternative with the condition that selects it: when in_household=false, "invite_to_household starts one." The closing phrases ("who's in my household", "is my partner connected") give real triggering utterances. It stops short of stating explicit exclusions, e.g. that changing the household requires update_household rather than 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 already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds meaningful context the annotations cannot: the data reflects only what the user has told the assistant, and quantities are optional, so the agent knows gaps are possible rather than treating the list as authoritative.

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 with zero filler, and the core definition is front-loaded before the usage triggers and the sibling relationship. 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?

Output schema exists, annotations are rich, and no parameters need explaining, so the description only has to supply purpose, triggers and sibling routing — all present. Nothing required to call this correctly is missing.

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

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

Zero-parameter tool, so there is no parameter semantics to document and the baseline of 4 applies. Nothing in the description misdescribes the (empty) input.

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 what the user has told you is in their kitchen: pantry, fridge and freezer') and pins down the scope detail that quantities only appear when provided. It is immediately distinguishable from add_to_pantry and remove_from_pantry, which mutate the same resource.

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

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

Gives three explicit trigger conditions — answering 'what do I have', before suggesting a shopping list, and before recommending a recipe — plus an explicit alternative route: find_by_ingredients with no ingredients searches from this list. That is when-to-use and alternative-selection guidance in a single sentence.

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 safety (readOnly, idempotent, non-destructive), yet the description adds real behavioral semantics: household allergens and dislikes are excluded from every search, a person's constraints apply whenever they eat unless a search passes who, diets stay on, and the time budget is the default time limit. The set=false branch also pre-empts an empty-result misread.

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?

Content is front-loaded with the field list and every sentence carries operational content, but the middle argument about allergens/diets/time budget is a dense run-on that could be broken into clearer sentences without losing meaning.

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 detailed, yet the description still flags the one return value an agent must act on (set=false). Usage triggers, downstream constraints for searches, and default behaviors are all covered for a zero-parameter read 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?

The tool takes no parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It does clarify the semantics of the 'who' filter on the related search tools and of set=false in the response, which is adjacent useful context rather than parameter documentation.

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 and resource ('Read what is saved about how the user eats') and enumerates the concrete fields returned: household size, allergens, dislikes, likes, diets, cuisines, time budget, units, goals, and per-person roles. That enumeration distinguishes it from get_household and update_profile in spirit, 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?

Gives concrete triggers: 'Call it before planning a week and when the user asks what you know about them,' plus a branch on set=false to offer set_up_my_kitchen questions. It also tells the agent it rarely needs to pass diets or time budget itself. There is no explicit when-not or named alternative tool, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: how ratings are composed (source ratings averaged with ask.recipes stars, user's own surfaced as my_rating), that nutrition_for indicates per-serving vs whole-yield, and that scaling is skipped with a scale_note when yield doesn't state servings. The units paragraph discloses conversion rules (dry goods by weight, liquids by volume, spoons unchanged, oven temps and pan sizes converted) and that an empty units field in the result means source-as-written.

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 use case are front-loaded, then scaling, then units — a logical order. The units block is long and packs output semantics (what 'units in the result' means) into a parameter discussion, and it partly restates the schema's units description, costing it a point on tightness.

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-value documentation is not required, yet the description still flags the non-obvious fields (nutrition_for, my_rating, scale_note, units). For a three-parameter read tool with edge cases around scaling and unit conversion, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it explains the intent of servings (meal prep, a crowd), the concrete metric/us conversion effects, and the fallback behavior (scale_note, nutrition stays per serving). The units explanation overlaps the schema's own units description, so the marginal gain is real but partly duplicated.

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 ('Get one recipe in full') and immediately enumerates the payload: ingredients, instructions, times, yield, nutrition, rating, source link. An agent can distinguish this from search_recipes or list_saved without opening the schema, since this is the single-item full-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?

Gives a clear trigger condition: 'when the user picks a recipe from a search or asks how to make it,' and the id parameter is described as coming from a previous search, which implies the prerequisite lookup flow. It does not explicitly name the sibling to use instead when the user has not yet picked a recipe (search_recipes/list_saved), so it stops short of full when-not guidance.

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

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

Annotations declare destructiveHint=true and idempotentHint=true; the description explains both by disclosing that re-importing the same recipe refreshes the copy, and adds the privacy constraint that imported recipes are visible only to this user and cannot be shared. It does not mention the prerequisite Cookidoo account link, which is the main operational unknown left.

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 verb and destination, then use cases, then the two behavioral caveats (privacy, refresh semantics). Nothing is repeated from the schema or annotations.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the annotations carry the safety profile while the description reinforces it. The remaining gap is the unstated dependency on connect_cookidoo before importing can succeed.

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% for the single required parameter, and the schema itself already documents accepted id formats (r123456, created-recipe ids, URL). The description adds no further meaning about cookidoo_id, so the baseline 3 applies.

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

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

States a specific verb and resource ('Copy one Cookidoo recipe into the user's private ask.recipes collection') plus the target scope, which separates it from the plural sibling import_recipes and from save_recipe. It never names the alternative import tool explicitly, so differentiation is implied by 'one' rather than stated.

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 downstream uses ('read it in full, adapt it, build a shopping list, or compare it with other recipes') that tell an agent when this import is worthwhile. It stops short of explicit exclusions — e.g. when to prefer import_recipes or save_recipe, or that a Cookidoo connection must exist first.

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

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

Goes well beyond the annotations by disclosing that the tool only mints a link (the actual import happens on the user's upload), that the link is single-use and expires in an hour, that results are private cookbooks named after the file with photos preserved, that Paprika stars map to my_rating, that nutrition is estimated afterwards, that limits are 100 MB / 3000 recipes, and that duplicates are skipped on re-upload. These are exactly the operational facts the readOnly/destructive hints 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 action and the link mechanism, then limits, then triggers, then follow-up — a sensible order. It is dense and long-jammed into a few run-on sentences (limits, dedup, and expiry all in one breath), but nearly every clause carries information an agent would otherwise guess wrong.

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?

Despite zero parameters, the description covers the full interaction: supported formats, what gets created, what the user must do with the link, size caps, dedup behavior, and the natural next step. With an output schema present it rightly does not describe the response payload.

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 no parameters and the description makes the interaction model clear — the file is dropped via the returned link rather than passed as an argument, so there is nothing for an agent to supply. No further parameter detail is needed.

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

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

Opens with a specific verb+resource: returns a one-time upload link for recipe-app exports, naming the exact file formats (Paprika, Mela, Crouton, schema.org zip). It also explicitly distinguishes itself from upload_recipe, so an agent can tell the bulk and single paths apart 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 concrete trigger phrases ("import my Paprika recipes", "bring my recipe collection over") plus a quantitative rule ("more than a few recipes to add at once") and names the competing tool: "upload_recipe stays the tool for a single recipe." It even prescribes the post-import follow-up (list_saved with the new cookbook).

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 one-time link semantics, 24-hour expiry, 6-member cap, one-household-per-account limit, automatic account creation for invitees, and the side effects of joining (pantry merge, cooking diary becoming the household's). These are exactly the behavioral traits an agent needs before invoking a non-idempotent mutation.

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

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

Front-loaded with the purpose, then constraints and flow in a logical order. The three quoted example utterances are somewhat redundant and could be trimmed, but no sentence is wasted overall.

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. The description covers all the operational constraints an agent needs: invite flow, expiry, member cap, side effects, and account creation, leaving no significant 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 100%, so the schema already documents both parameters. The description restates that my_name is what the family calls the user and that it is required when the household is created, adding only marginal meaning beyond the schema's own descriptions.

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

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

States a specific verb and resource: 'Create a one-time link that lets another ask.recipes user join the user's household.' It is clearly distinguishable from siblings like get_household, update_household, and remove_from_household, and the example utterances reinforce the intended use.

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 when-to-use signals through example utterances and explains the first-call-creates-household behavior, including when my_name is needed. It does not explicitly exclude alternatives (e.g., update_household for renaming, get_household for viewing), so it falls short of a 5.

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

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

Annotations declare destructive=true and idempotent=true, and the description adds substantive consequence detail beyond them: shared pantry, diary entries and shared cookbooks stay with the household, the departing user gets an empty pantry but keeps their own diary entries, and the household is dissolved when the last member leaves. It also correctly adds a user-confirmation requirement for a destructive zero-param call.

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?

Data-consequence information is front-loaded (what stays, what is lost, what happens to the household) with no filler sentences. The quoted intent list ("for 'leave the household', 'stop sharing my kitchen'") is slightly awkward in phrasing but earns its place as a routing trigger.

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?

Annotations cover safety and idempotency, an output schema exists, and the description covers data loss, household dissolution, and the confirmation requirement — everything needed to call correctly. The only missing piece is disambiguation from the remove_from_household sibling in a 32-tool set where both mutate membership.

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

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

Zero parameters, so there is nothing to disambiguate; the baseline applies. No parameter text is needed or present.

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?

Specific verb + resource ("take the user out of their household") with concrete user-intent phrasings ("stop sharing my kitchen"). It does not distinguish itself from the sibling remove_from_household, which is the most plausible confusion (leaving oneself vs. removing someone else).

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 intent triggers that select this tool and a hard prerequisite ("Confirm with the user before calling"). It lacks an explicit when-not or a pointer to remove_from_household as the alternative, which is the one routing decision an agent could get wrong here.

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, so the safety profile is covered. The description adds domain behavior an agent cannot infer: every user has a default cookbook, others are user-named, and shared cookbooks surface for all household members.

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

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

Three compact sentences: what it returns, when to call it, then domain context about defaults and sharing. Purpose is front-loaded and nothing is padding.

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

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

A zero-parameter read tool with an output schema, rich annotations, and a description that explains the result set's structure and household visibility. Nothing needed to invoke it correctly is missing.

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

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

Zero parameters, so the baseline is 4. The description goes slightly further by characterizing the returned fields (recipe counts, shared flag, default cookbook), though most of that is also carried by the output 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 ('List the user's cookbooks') and adds the payload detail 'with how many recipes each holds'. This distinguishes it cleanly from recipe-level siblings like get_recipe and list_saved.

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?

Two concrete triggers are given: answering 'what cookbooks do I have' and resolving 'the usual one' before a save. It doesn't name a competing tool or a when-not case (e.g. vs create_cookbook/update_cookbook), 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 readOnlyHint, idempotentHint, and no destructive behavior, but the description adds useful operational context: it returns Cookidoo ids and that only names and links are available until import. That is meaningful behavior beyond structured metadata.

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

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

The description is compact and front-loaded with the core action, then user-intent examples, sibling differentiation, and return-value guidance. Every sentence contributes directly to selection or invocation.

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 zero parameters, rich annotations, and an output schema, the description supplies everything needed: when to choose it, what it returns, and how to use those return values. No important selection or invocation context is missing.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The baseline for no parameters is 4, and the description appropriately does not invent parameter details.

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 the user's own Cookidoo recipes, including ones sent via send_to_thermomix. It explicitly distinguishes itself from list_saved by naming the 'Bimby side' versus the 'ask.recipes side'.

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 user phrasings for when to use it, names the alternative list_saved and its domain, and explains the next step: pass returned Cookidoo ids to import_cookidoo_recipe. The routing guidance is explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds useful context beyond that: each entry includes its cookbooks, the user's note, and last-cooked time/count as recorded by mark_cooked, which tells the agent what fields are meaningful and where they come from.

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 purpose and immediately followed by the sibling exclusion. Slightly dense with quoted example phrases, 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?

A one-optional-parameter read tool with an output schema; the description covers purpose, triggering intents, filtering, sibling disambiguation and the provenance of the returned metadata. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter already documents name-based cookbook filtering. The description restates the same behavior ("pass cookbook to see one cookbook only") without adding syntax, matching rules, or edge cases, so the schema does the heavy lifting — baseline 3.

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 the recipes the user saved") plus the owning surface (ask.recipes), and explicitly excludes the nearest sibling ("Not the Thermomix / Bimby / Cookidoo side; that is list_cookidoo_recipes"). An agent can distinguish it from list_cookidoo_recipes and list_cookbooks 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 concrete user phrasings that trigger it ("my recipes", "what did I save", "what's in my Stews cookbook") and states the filtering condition for the one parameter. It also names the alternative tool to use for Cookidoo content, so both when-to-use and when-not-to-use are explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description justifies these by explaining that each call creates a new entry rather than toggling a flag, and adds that the recipe need not be saved first. It also discloses the return payload (entry plus cook count and last-cooked date). It does not surface that a supplied rating replaces the earlier one, which is the concrete destructive effect.

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, then param rules, then return behavior. The quoted user utterances are dense with routing value rather than filler. Slightly longer than strictly necessary, with the third example ("the lasagna was a hit") adding little beyond the first two.

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-param mutation with full schema coverage, annotations, and an output schema, the description covers what to record, when, and what comes back. Minor residual gaps are overwrite semantics for rating and behavior on an unknown id, neither of which is essential to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns the extra point by adding invocation rules rather than restating types: when to supply date versus default to today, and when a rating should be included at all. Note size limits and rating scale live in the schema, appropriately.

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 ("Record that the user cooked a recipe") plus the unit of record ("One entry per time it was cooked"), which separates it from rate_recipe and cooked_history without opening either schema. The example utterances anchor the intent unambiguously.

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

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

Gives concrete when-to-use triggers ("we made that tonight", "cooked the curry yesterday") and routing rules for the optional params: pass date only when a day other than today is named, pass rating when a verdict was given "so the cook and the rating land in one call". It implies rate_recipe should not be called separately for the same event but never names that sibling explicitly, which is the one missing piece.

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 the upsert semantics (one rating per user and recipe, rating again replaces it), how the user's stars feed the aggregate rating and rating_count returned by every tool, and that the user's own stars surface as my_rating. This makes the destructive/replacement behavior concrete rather than leaving the agent to infer it from destructiveHint.

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 intent and trigger phrases are front-loaded and every sentence carries information, but the middle sentence covering aggregation, rating_count, and my_rating is dense and slightly overlong. It is efficient overall, with no filler.

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

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

For a three-parameter annotation-covered mutation with an output schema, the description covers the trigger, the write semantics, the replacement behavior, and the cross-tool delegation to mark_cooked. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still adds value by mapping colloquial utterances to the stars parameter and stating the allowed range inline. It also frames the note as an optional "why", giving the parameter a purpose beyond the schema's field description.

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 verb and resource (record stars for a recipe), gives the natural-language phrasings that should trigger it ("five stars", "that one was a 3", "best curry we've had"), and distinguishes it from the sibling mark_cooked. An agent can identify the intent without opening any schema.

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

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

It gives an explicit routing rule: when the user also says they cooked it, use mark_cooked with rating to do both in one call. That names the alternative and the condition that selects it, which is exactly the guidance an agent needs to choose between the two rating paths.

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 behavior beyond the annotations: it discloses the authorization constraint (only the creator can do it), the succession rule (longest-standing member takes over when the creator leaves), and precisely what is preserved (account, diary entries, shared pantry and cookbooks stay). This is exactly the destructive-operation context an agent needs.

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

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

Front-loads the core action and scope, then adds constraints and consequences in compact clauses. Every sentence earns its place with no filler.

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

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

With an output schema present and annotations covering safety, the description supplies the remaining critical context – permissions, succession behavior, and what survives the removal. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% and the schema already describes the name parameter identically, so the description doesn't expand parameter meaning much beyond restating that it comes from get_household. Baseline 3 is appropriate when the schema carries the full burden.

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 (remove) and resource (another member of the user's household), and the word 'another' distinguishes it from a self-removal like leave_household. An agent can differentiate it from sibling household tools without opening the schema.

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

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

Tells the agent how to obtain the required name ('by the name get_household lists') and to confirm with the user before calling. It doesn't explicitly contrast against leave_household or invite_to_household, so routing to alternatives is implied rather than spelled out, but the operational 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety is covered. The description adds genuinely new behavioral context: loose name matching and that the whole pantry is returned after the change. It stops short of saying what happens to unmatched names, which slightly limits it.

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

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

Two front-loaded sentences cover purpose, when to use, matching behavior, and return value with no filler. The quoted examples slightly duplicate the schema's own descriptions, a small redundancy.

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 full param coverage, the description need only carry intent and behavior. It supplies the triggering scenarios, the destructive/loose-match semantics, the paired follow-up call, and the return shape, leaving nothing an agent needs 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. The description still adds value by framing all=true as an ordered operation followed by add_to_pantry and by tying remove to real user phrasings, clarifying the intent behind each parameter rather than just restating types.

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 ("Take items out of the pantry") plus the full-empty variant (all=true). The mention of add_to_pantry and the pantry-return behavior distinguishes it clearly from sibling pantry tools like get_pantry and add_to_pantry.

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

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

Gives concrete triggering utterances ("used the last onions", "we're out of milk") and an explicit alternative workflow: use all=true when the user lists the current kitchen contents, then follow with add_to_pantry. Both when-to-use and the paired call are spelled out.

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 beyond the annotations by disclosing the create-on-first-use side effect for cookbooks, the default-cookbook fallback, that a recipe may live in several cookbooks, and that a repeat save only updates the note. That last point softens the destructiveHint=true annotation but does not contradict it outright, since overwriting a note is still a mutation.

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

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

Front-loaded with the core action, then defaults, then edge-case semantics. The quoted utterance examples are mildly verbose but earn their place as routing cues.

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

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

An output schema exists and annotations cover the safety profile, so the description only needs to cover side effects and defaults, which it does. It leaves unstated what happens to an existing note when note is omitted on a re-save.

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 already documents all three parameters, so the baseline is 3; the description still adds real meaning by clarifying that the note is scoped per cookbook and is what gets replaced on a repeated save, and by tying cookbook names to auto-creation.

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 ('Save a recipe to one of the user's cookbooks') plus the scope of the target container, which cleanly separates it from siblings like unsave_recipe, list_saved, and create_cookbook.

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 user-utterance triggers ('save that one', 'put it in my BBQ cookbook') and a rule for when to pass cookbook versus omit it. It does not explicitly name an alternative tool or a when-not-to-use case, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: results are subscription content with a hard quoting restriction (name and link only unless imported), and the return value is Cookidoo ids meant for import. This is policy/constraint information the schema and 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?

Three tight sentences: purpose and audience first, then routing to the sibling, then output/next-step and the licensing constraint. No filler, and the most decision-relevant content is front-loaded.

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

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

Output schema handles return shape and annotations handle safety, so the description only needs to cover routing, downstream use, and the quoting restriction — all of which it does. Nothing an agent needs to call or act on this result is missing.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including the default/max for limit and the language expectation for query. The description adds no further syntax or format detail, so the baseline 3 is appropriate.

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

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

States a specific verb and resource — search Cookidoo's catalogue of Thermomix recipes through the user's connected account — and explicitly demarcates it from the sibling list_cookidoo_recipes for the user's own recipes. The agent can pick between the two Cookidoo search/list 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 user-utterance triggers ("find a Bimby recipe for", "search my Bimby for"), names the alternative for own recipes, and states the downstream step (pass returned ids to import_cookidoo_recipe). When-to-use and what-to-do-next are both explicit.

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

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

Annotations already declare readOnlyHint/idempotent, and the description adds substantial beyond-schema behavior: profile defaults applied on top unless overridden, ask_user signaling no saved profile, check flag warning that exclusions match whole words and sauces can hide allergens, and instructions to verify with get_recipe. This is rich operational context.

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 purpose and use cases well, and every clause conveys actionable behavior. It is a dense single-block paragraph run-on; a little structure or trimming of filter enumerations already in the schema would sharpen it.

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 23-parameter search tool with an output schema, it covers the essentials: profile interaction, exclusions, ranking, and the allergen check reminder. Return values need not be explained since 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?

Schema coverage is 100%, so baseline is 3; the description adds cross-parameter meaning beyond the schema — that main_protein is judged from ingredients (stock doesn't count), exclude_ingredients is whole-word and maps to diet filters, and main_protein values can build week rules. It largely restates many params already fully documented, so it doesn't exceed a 4.

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

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

Opens with a specific verb+resource and frames the concrete use cases (dinner tonight, macros for a cut, meal prep). It clearly says what it returns (recipes linking to source, rating semantics). Sibling differentiation is only implicit — it doesn't name find_by_ingredients or search_cookidoo — so it stops 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 explicit when-to-use framing plus when-not/exception behavior: min_rating/min_reviews never drop unrated or private uploads, nutrition filters exclude recipes without serving-yield data, max_total_minutes=-1 lifts the profile default, and who='' means everyone. Alternatives and edge conditions are spelled out.

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

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

The description adds key behavior beyond the annotations: every call creates a new Cookidoo recipe (consistent with idempotentHint=false), the account language comes from connect_cookidoo, and the server refuses a mode the machine lacks. It does not cover failure modes such as missing account connection or partial-send behavior, so it falls short of the richest behavioral disclosure.

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 purpose and trigger phrases are front-loaded, but the description is a single dense paragraph mixing workflow instructions with a long reference catalogue of Thermomix settings. The catalogue is useful but verbose and poorly delimited, making it harder to scan than necessary.

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

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

For a mutation tool with an output schema, the description covers the workflow, prerequisite account context, language handling, machine-model constraints, rewriting rules, and the user-confirmation step. An agent has enough information to invoke it correctly in context.

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 goes well beyond the schema: it explains what name, ingredients and steps should contain (account language, grams and millilitres, one action per step), how machine interacts with mode support, and why ingredient amounts must stay in step text. It also clarifies the model-dependent limitations of the mode parameter, which the schema only lists as an enum.

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 (send), resource (one recipe), and destination (the user's Cookidoo account as a private created recipe) and explains the visible outcome (shows on the Thermomix/Bimby with guided cooking). This clearly separates it from sibling tools like save_recipe or share_recipe.

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

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

It names the exact user phrasings that should trigger this tool and gives an explicit ordering: first get_recipe, then rewrite, show the user the rewritten steps before sending. It also explains the fallback for older machines that lack guided modes.

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 the result is a share.ask.recipes URL, works without an account, is unlisted and not indexed, credits source and licence, and carries schema.org Recipe markup. It also states the Cookidoo sharing restriction, which is a meaningful behavioral constraint not captured by 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 front-loaded with the core action, then adds usage examples, access scope, return behavior, and the Cookidoo exclusion. Despite being a dense paragraph, each sentence adds practical value and there is no wasted framing.

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 sharing tool, the definition covers selection intent, access scope, output URL characteristics, privacy/indexing behavior, machine-readability, and the main exclusion. An agent has everything needed to call it correctly and understand what the returned link enables.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful semantics by clarifying that the ID can refer to recipes the user can read, including corpus and household uploads, though it does not explicitly reconcile this with the schema's narrower phrase 'id of a recipe the user uploaded.'

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: 'Create a share link for a recipe.' It immediately distinguishes the tool's output as a public share URL rather than a recipe read or save operation, so an agent can select it without ambiguity.

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 intents such as 'send this to my wife', 'give me a link', and 'add this to MacroFactor', then states the readable-recipe scope and a clear exclusion for Cookidoo imports. This is strong when-to-use and when-not-to-use 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 and idempotentHint=true, so the safety profile is known. The description adds meaningful context beyond that: removal only affects cookbook membership, and the underlying recipe remains searchable. It doesn't discuss reversibility or permissions, but adds real behavioral 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?

Front-loads the core action and scope, then adds a useful clarifying sentence. The quoted example phrases are a bit informal but earn their place as trigger cues; no wasted sentences.

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, full parameter descriptions, and annotations covering safety, the remaining description gap is small. It covers the key ambiguity (scope of removal and non-destruction of the recipe), though it could mention prerequisites such as the cookbook existing or recipe ownership.

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 parameter meanings are already documented. The description restates the cookbook parameter's semantics in nearly the same terms as the schema ('With cookbook set it leaves only that cookbook; without it the recipe is removed from every cookbook'), adding clarity but little new information beyond structured fields.

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 ('Take a recipe out of the user's cookbooks') and makes the scope explicit in both modes. It is clearly the inverse of save_recipe and cannot be confused with delete_cookbook, especially since it notes the recipe itself is untouched.

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

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

Provides user-utterance triggers ('remove that from my saved', 'take it out of Christmas') and explains the cookbook-scoped vs. global behavior. It does not explicitly contrast with siblings like delete_cookbook or list_saved, but the context is clear enough for confident selection.

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

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

With annotations marking this as a non-read-only, destructive, idempotent mutation, the description adds real non-annotated facts: recipes remain in place and the default cookbook stays personal. It does not explain the destructiveHint=true — nothing about what a rename might break (e.g., references, name collisions) or what the response contains.

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

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

Two compact sentences with the actions front-loaded and example phrasings that double as usage cues. Nothing is padded, though the quoted examples occupy space that a single terse clause could have covered.

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

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

For a 4-parameter mutation with full schema coverage, existing annotations, and an output schema, this covers the essentials: what changes, what does not, and one important constraint. The main residual gap is the unexplained destructive flag and any rename-collision behavior.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already explains optional-vs-keep semantics for name, description, and shared. The description only implicitly maps its three operations to those parameters, adding little syntax or constraint detail beyond the 'default cookbook stays personal' 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?

The description names three specific verbs (rename, change description, share) against one resource (cookbook), so it is immediately distinguishable from create_cookbook and delete_cookbook in the sibling list. The quoted example intents ('call it Sunday Roasts instead', 'share my Christmas cookbook') make the operation concrete.

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

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

Usage context is clear through the two example intents, and the closing sentences set scope boundaries (recipes are untouched, the default cookbook cannot be shared). It never explicitly names an alternative tool or says when not to use it, which keeps it short of a 5.

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

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

The annotations already declare this is a non-read-only, idempotent, non-destructive, closed-world operation. The description adds valuable behavioral context by explaining that the names affect search results and diary cooked_by labels, which is a downstream consequence not captured by 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 definition is a single, compact sentence with the core action front-loaded and examples embedded efficiently. The final clause about search and cooked_by is slightly awkwardly worded but still earns its place by explaining downstream impact.

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 and idempotency, so the description need not explain return values. It supplies purpose, examples, and downstream naming effects; only minor details such as permission requirements or whether both names can be updated together are absent.

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

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

Schema description coverage is 100%, and both parameters already document that empty values keep the existing name. The description adds meaning about the effect of names but does not provide additional per-parameter syntax or constraints beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb and two resources: renaming the household and changing the household-specific name for the user. The example utterances make the purpose concrete, though it does not explicitly distinguish this from the sibling update_profile 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?

Concrete example phrases such as "call our household Casa Silva" and "in the household I'm Mum, not Ana" map directly to the two parameters and clearly indicate when to use the tool. It lacks explicit exclusions or comparison to alternatives like update_profile, but the 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?

Goes well beyond the annotations: discloses additive list semantics ('added to or removed from, never replaced'), that 0 clears numeric fields, the downstream effects on every later search (whole-word exclusion, diet filters, default time limit), and the one-time allergy caveat to relay. Remaining gap: it never says whose profile is written when a household is shared (invite_to_household/update_household exist as siblings), so precedence between members' units and diets is unstated; the 'nothing already saved is lost' phrasing also sits slightly awkwardly with destructiveHint=true, though the explicit remove_* fields resolve that.

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 highest-value content (the example-to-field mapping) and dense rather than padded; length is justified by 19 parameters. The single-paragraph block makes the allergy safety note and the return-value instruction easy to skim past, which costs it a point.

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 19-parameter mutation tool it covers what matters: which fields change, how clearing works, what happens downstream, and what comes back ('returns the whole profile after the change; read it back in one short list') even though an output schema exists. Nothing needed to call it correctly is absent.

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 74% schema coverage the schema already documents most fields, yet the description adds real value: worked examples for likes/dislikes/allergens, the 0-clears convention for all numeric goals, and the rule that a person's role makes them addressable by group in who. It does not, however, explain the four remove_* fields that have no schema description, nor fat/carbs/calories/protein interaction.

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?

Specific verb+resource ('Save what the user says about how they eat') with the scope stated immediately: persistence across sessions and clients. It is clearly distinguished from read-side siblings (get_profile, get_household) and from update_household by naming exactly which household attributes it owns.

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 utterance-to-field routing ("we don't eat cilantro" → add_dislikes, "my daughter can't have berries" → people[].add_allergens, "grams please" → units=metric), plus the decision rule for household lists vs per-person lists. An agent can map free-form user speech to parameters without inference.

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

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

Annotations only say this is a non-read-only, non-idempotent, non-destructive write; the description adds real context: every call creates a NEW private recipe (consistent with idempotentHint=false), it is visible only to this user in searches and saves, and when markup is passed the server extracts name, ingredients, steps, times, nutrition and rating from it. Missing only error/failure behavior and whether duplicates are detected.

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 core action and followed by the web-page path and the privacy/non-idempotency consequence. Some of the markup explanation duplicates the schema's markup description, but it earns its place because it describes the primary extraction workflow.

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 here; the description covers the two distinct input paths, the extraction behavior, and the visibility model. With 8 optional parameters and 63% schema coverage, the three undocumented scalar fields are low-risk name-obvious fields.

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 63%, and the description carries the most consequential semantics: markup can be full HTML or just the JSON-LD block and supersedes the other fields, source_url is kept as attribution, and name may be omitted when markup carries the recipe. yield, description and total_minutes are left to their self-explanatory 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?

States a specific verb and resource ('Add a recipe the user supplies themselves') and enumerates the accepted input modes: pasted, dictated, family recipe, or a web page. It distinguishes this from source-based siblings implicitly by insisting the user supplies the content, but never names add_to_pantry, save_recipe, or import_cookidoo_recipe, so the boundary is inferred rather than stated.

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

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

Clear context for when this applies: user-supplied text, or a web page where the agent passes raw HTML/JSON-LD in markup along with source_url and lets the server extract facts. It does not explicitly say when NOT to use it (e.g. versus import_cookidoo_recipe for Cookidoo URLs or save_recipe for existing recipes).

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