ask.recipes

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered. The description adds genuinely new behavior: the ranking logic (most on-hand ingredients, fewest extras needed) and that each result links back to its source — context an agent cannot get from the annotations.

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

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

Three tight sentences: purpose first, then ranking behavior, then result shape. No filler, no restatement of the title, and every clause carries information the agent can act on.

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

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

An output schema exists, so return-value detail is not required, and the description still notes that results link to their source. With 13 parameters but 85% schema coverage, the structured fields carry the parameter burden; the description is complete enough for correct selection, though it could flag the filtering dimension.

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 85%, so the schema already documents ingredients, query, and the nutritional filters with examples. The description mentions only the ingredient input and ranking, adding no syntax, format, or default information beyond what the schema already provides; 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 ('Find recipes that use ingredients the user already has') and adds the differentiating mechanism: ingredient-driven retrieval with ranking by overlap. It implicitly separates itself from search_recipes, but never names the sibling or the boundary between them explicitly.

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

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

Gives concrete triggering situations ('leftovers, a full fridge, an ingredient about to turn'), which tells the agent when this tool fits. It offers no exclusions or named alternatives for the case where the user wants a dish by name rather than by pantry contents.

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, openWorld=false and non-destructive, so the safety profile is covered. The description's contribution is a preview of the returned fields, which largely duplicates the existing output schema, and it says nothing about failure modes such as an unknown or stale id.

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

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

Two sentences, no waste, front-loaded with the resource and payload scope before the usage cue. Every clause carries information.

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

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

For a one-parameter read tool with a full output schema and covered annotations, the description supplies what is needed: scope, contents preview and trigger. Minor gap is the absence of any note about what happens when the id is invalid.

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 id parameter is already documented as 'recipe id from a previous search'. The description's 'picks a recipe from a search' reinforces but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get one recipe in full') and enumerates exactly what the payload contains: ingredients, instructions, times, yield, nutrition, source link. The phrase 'one recipe' separates it from the collection-oriented siblings like search_recipes 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?

Gives a clear trigger: the user picked a recipe from a search or asked how to make it. That distinguishes it from search_recipes well enough, but it names no explicit alternative or exclusion (e.g. 'do not use this to browse, use list_saved').

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 fully covered without the description. The description adds no behavioral detail beyond that—no ordering, recency semantics, or result limits—although the presence of an output schema reduces the need to describe returns.

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

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

A single sentence, front-loaded with the action and resource, with the disambiguating trigger phrases appended compactly. Nothing redundant.

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

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

With zero parameters, a complete annotation set, and an output schema to describe the return shape, the description carries almost the entire remaining burden and covers it. The only unaddressed element is ordering/recency behavior, which the annotations do not supply.

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; the baseline for a parameterless tool 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?

Clear verb+resource ('List the user's saved recipes') with the scope narrowed to the saved collection rather than all recipes. It does not explicitly name a sibling such as search_recipes or find_by_ingredients, so differentiation is implicit 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?

The quoted user phrasings ('my recipes', 'what did I save', 'the one I kept last week') act as concrete invocation triggers and map intent to the tool well. There is no explicit when-not guidance or named alternative, so it stops short of full routing instructions.

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=false, destructiveHint=false, and idempotentHint=true. The line 'Saving the same recipe twice has no further effect' restates idempotentHint in prose rather than revealing anything new; the only added signal is that the target is scoped to the 'user's collection'. No auth, error, or failure-mode behavior is described.

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

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

Two short sentences with the action front-loaded and the idempotency caveat second. The inline example phrases are slightly bulky but earn their place by anchoring natural-language intent.

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 save with an output schema and full annotation coverage, the description is nearly sufficient — return values are covered elsewhere. It stops short of resolving the upload_recipe overlap or what happens with an unknown id.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the schema already carries the semantics; the description adds no format, range, or sourcing guidance for the id. 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 ('Save a recipe to the user's collection') and the example utterances ('save that one', 'add it to my recipes') make the intent unmistakable. It does not explicitly name a sibling, but the destination phrase distinguishes it from read-oriented siblings like list_saved 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?

The quoted user phrasings implicitly tell an agent when to reach for this tool, which is more than nothing. However, it never addresses the ambiguous sibling boundary — nothing says whether 'add it to my recipes' means save_recipe or upload_recipe, and no exclusions or prerequisites are given.

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

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

Annotations already declare it a safe, idempotent read, and the description still adds material behavior: results link to their source, recipes lacking nutrition are excluded when a nutrition filter is set, and there is a default rating/review floor with documented escape hatches (-1 disables). Those exclusion and default rules change whether an agent finds results and are not in the annotations.

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

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

Five sentences, front-loaded with the purpose and use cases, then filter behavior and defaults. The parenthetical nutrition list is nearly a schema restatement, but overall there is little waste and the important exclusion/default rules are easy to find.

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?

Thirteen parameters at 100% schema coverage plus an output schema mean the description need not explain return values, and it does not. It still covers the decision-critical unknowns: default thresholds, how to disable them, and the nutrition-filter exclusion behavior. Nothing an agent needs 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?

Schema coverage is 100%, so 3 is the baseline, but the description adds semantics the schema lacks: which filters exist in prose, that nutrition values are per-serving as reported by the source, and that min_rating/min_reviews have non-obvious defaults plus the -1 disable mechanism. That is genuine meaning beyond the schema 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 (search) plus resource (recipes) and adds scope that differentiates it: bounded by what-to-cook questions, human-rated, with source linking. Sibling names like find_by_ingredients and get_recipe make the differentiation concrete once the description anchors to query-based discovery rather than ingredient matching or retrieval by id.

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?

Enumerates concrete use cases (dinner tonight, cooking for guests, quick weeknight meal, protein/calorie targets), which effectively tells the agent when this tool applies. It does not explicitly contrast against sibling find_by_ingredients or get_recipe, so the alternative-selection guidance is implicit rather than stated.

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

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

Annotations already flag this as a non-read-only, non-idempotent, non-destructive write, and the description adds meaningful behavior beyond them: the returned share.ask.recipes URL opens without an account, is unlisted/unindexed, and credits the original source. It does not clarify what happens on repeat calls (relevant given idempotentHint=false), which keeps it from a 5.

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

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

Front-loaded with the action and resource, followed by intent examples, output behavior, and the eligibility constraint. Every sentence carries information, though the quoted example phrases add a little length without much extra signal.

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

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

For a single-parameter tool with full schema coverage, an output schema, and clear annotations, the description covers the remaining gaps: eligibility limits, fallback behavior, and what the returned URL is. An agent has everything needed 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% and the single id parameter is already documented as 'id of a recipe the user uploaded'. The description reinforces the same constraint but adds no new syntax, format, or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (create a share link for a recipe) and immediately scopes it to recipes the user uploaded. It also distinguishes itself from the general case by stating that for other recipes the source link is what to share, letting an agent differentiate this from get_recipe or search_recipes 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 trigger intents ("send this to my wife", "share it with Tom", "give me a link") and an explicit when-not rule (only uploaded recipes; otherwise share the source link). It stops short of naming a sibling tool as the alternative, so it is clear context rather than fully explicit routing.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=false, yet the description adds two things they cannot: every call creates a NEW recipe (reinforcing non-idempotency) and the result is private to this user in searches and saves. It also discloses that the server performs extraction server-side rather than the agent. No contradiction with the declared hints.

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

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

Three sentences, each doing distinct work: input modalities first, the markup/source_url mechanics second, the privacy consequence last. No repetition of the schema or the annotations, and no filler.

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

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

An output schema exists, so return values need not be described, and the description covers privacy, extraction behavior, and the two viable input paths. With 8 parameters at 63% schema coverage, a few fields (yield, description, total_minutes) rely entirely on their names, leaving a small completeness gap for what is otherwise a rich, well-scoped definition.

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

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

Schema coverage is a middling 63% with 8 parameters, but the description adds real meaning beyond the schema: it explains that markup (raw HTML or just the JSON-LD block) plus source_url triggers server-side extraction, and explicitly says the other fields 'can stay empty' in that path. Undocumented parameters like yield and total_minutes get no narrative help, keeping this below 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 ('Add a recipe the user supplies themselves') and scopes the input modalities: pasted, dictated, family recipe, or a pointed-at web page. Together with the title 'Upload a private recipe' and the closing 'creates a new private recipe, visible only to this user', an agent can separate this from save_recipe and share_recipe 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?

Enumerates the situations that select this tool (user-supplied text, dictation, family recipe, web page) and gives concrete direction for the web-page case: pass raw HTML or the JSON-LD as markup with source_url. It stops short of naming alternatives or stating when NOT to use it versus save_recipe, so it is clear context without explicit exclusions.

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