Saves recipes from videos and websites, plans meals and builds grocery lists.
Scored across 21 tools
Tools map to distinct resource+action pairs across recipes, cookbooks, meal plan, grocery list, and account. The trickiest trio (save_recipe, import_recipe_from_url, show_recipe) is explicitly delimited in descriptions with cross-references, and get vs remove vs check on grocery/meal-plan items are clearly separated.
All 21 names follow a consistent snake_case verb_noun pattern (add_to_meal_plan, remove_grocery_items, search_recipes, etc.). No camelCase or style drift, and verbs accurately reflect each operation's effect.
21 tools is on the higher side but is justified by four coherent sub-domains: recipe library, cookbooks, meal planning, and grocery list, plus import and offline preview. Each tool covers a real operation rather than duplicating another, though the surface could be trimmed slightly (e.g. preview_meal_plan is a special case).
Recipe lifecycle is covered end to end (save, import, get, search, update, delete, restore), and meal plan/grocery list each have add, read, modify, and remove operations. Minor gaps remain: no standalone create/rename/delete cookbook, and no way to update account preferences or clear whole days from the meal plan.
Use this when the user wants to file a saved recipe in a cookbook. Adds the recipe to a cookbook the user owns, or creates a new cookbook with the given name first. A recipe can be in several cookbooks.
| Name | Required | Description | Default |
|---|---|---|---|
| recipeId | Yes | Id of the recipe to add. | |
| cookbookId | No | Id of an existing cookbook (from list_cookbooks). Pass this or newCookbookName, not both. | |
| newCookbookName | No | Name for a new cookbook to create and add the recipe to. An existing cookbook with the same name is reused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, destructive=false, idempotent=true and openWorld=false, so the safety profile is covered. The description adds real context beyond that: the tool may create a cookbook as a side effect, and membership is non-exclusive so adding does not displace other cookbooks. It does not say what is returned or what happens on a duplicate add, which the idempotent hint only weakly implies.
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 usage trigger, then the operation, then the key constraint about multiple memberships. Nothing is padded and no sentence duplicates another.
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 mutation with full schema coverage, complete annotations, and no output schema, the description covers trigger, branching behavior, and multiplicity. The remaining gap is the result of the call (e.g. whether the cookbook id is echoed back), which is minor given no 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% and each parameter already documents its role, including 'Pass this or newCookbookName, not both' and the reuse rule. The description's 'creates a new cookbook with the given name first' merely restates the newCookbookName semantics, 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 pairs a specific verb ('file', 'adds') with a specific resource ('a saved recipe in a cookbook') and clarifies the many-to-many nature ('A recipe can be in several cookbooks'). It is immediately distinguishable from remove_recipe_from_cookbook, though it never names that or any other sibling.
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?
'Use this when the user wants to file a saved recipe in a cookbook' gives a clear triggering condition, and the second sentence explains the create-or-reuse branching. It stops short of stating exclusions or pointing at the counterpart tool for unfiling, and the list_cookbooks pointer lives only in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants things on their shopping list. Adds individual items and/or all ingredients of saved recipes to the user's Recipe One grocery list, merging with items already there.
| Name | Required | Description | Default |
|---|---|---|---|
| items | No | Individual items to add. | |
| recipes | No | Saved recipes whose ingredients should all be added. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish this is a safe, non-destructive, closed-world write. The description adds genuinely useful behavior beyond them: the result merges with existing list contents rather than replacing them, and recipe ingredients are expanded wholesale. It does not say what happens on duplicate items (whether amounts are summed or entries deduplicated), which is the main remaining ambiguity.
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 with no waste: the usage trigger is front-loaded and the action plus merge semantics follow immediately. Nothing could be removed without losing 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 write tool with no output schema, the definition covers the trigger, both input modes, and the merge outcome, which is what an agent needs to invoke it correctly. Duplicate-handling and any confirmation of the resulting list state are the only real gaps.
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 item name/unit/amount and recipeId/servings are already documented, and the baseline is 3. The description contributes only the "and/or" framing, i.e. that both parameters may be supplied together, which is a marginal addition over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: it adds individual items and/or all ingredients of saved recipes to the user's Recipe One grocery list, and it states the merge behavior. That is enough to tell it apart from remove_grocery_items or check_grocery_items in practice, but the description never explicitly contrasts itself with those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use this when the user wants things on their shopping list" gives a clear trigger condition, and the two supported modes (loose items vs. recipe ingredients) are spelled out. It stops short of stating when NOT to use it or naming an alternative tool, so it falls under the 5 benchmark.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to plan saved recipes for specific days. Adds one or more of the user's recipes to their Recipe One meal plan; several meals on the same day are allowed.
| Name | Required | Description | Default |
|---|---|---|---|
| meals | Yes | Meals to add. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the safe-append profile is known. The description adds the behavioral rule that duplicate same-day meals are permitted, but says nothing about what happens when the same recipe is added twice, whether existing plan entries are affected, or any limits — gaps that matter for an append 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?
Two tight sentences, with the usage trigger front-loaded before the effect statement. No filler, no repetition of schema field names.
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 and annotations, this covers the essentials: what it does, when to call it, and the same-day multiplicity rule. It omits what the call returns or whether an updated plan comes back, which would matter since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so date, mealType, recipeId, and servings semantics are already documented in the schema; baseline 3 applies. The description adds only the multiplicity note ('several meals on the same day'), which is largely a restatement of the array-of-meals shape.
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 ('Adds one or more of the user's recipes to their Recipe One meal plan') and clarifies scope with 'several meals on the same day are allowed.' It implicitly distinguishes itself from remove_from_meal_plan and replace_meal_plan_entry via the additive verb, but never names a sibling to sharpen the boundary as a 5 would require.
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?
'Use this when the user wants to plan saved recipes for specific days' gives a clear, actionable trigger condition, and the saved-recipes qualifier excludes unsaved/imported dishes. There is no explicit when-not guidance or pointer to replace_meal_plan_entry for modifying an existing entry, 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.
Use this when the user says they bought (or still need) items. Marks items on the user's Recipe One grocery list as checked or unchecked.
| Name | Required | Description | Default |
|---|---|---|---|
| checked | No | true to check off (bought), false to uncheck. | |
| itemIds | Yes | Items to mark. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the mutation and safety profile is covered. The description adds modest context by confirming this only flips a checked flag on the user's own list rather than mutating list contents, but it says nothing about error behavior for unknown ids or partial failures across a batch of up to 100 items.
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, zero waste, with the usage trigger front-loaded ahead of the behavioral statement. Nothing is 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 two-parameter toggle with full annotation coverage and a complete schema, the definition is close to sufficient. The only missing piece is guidance on sourcing itemIds (the schema points to get_grocery_list) and what happens when some ids are invalid in a batch.
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%, including 'true to check off (bought), false to uncheck' and 'Grocery item id from get_grocery_list', so the baseline is 3. The description's 'bought (or still need)' phrasing reinforces the intent mapping but adds no format, limit, or provenance detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('Marks') and resource ('items on the user's Recipe One grocery list') plus the two-state outcome (checked or unchecked). The action is distinguishable from siblings like add_to_grocery_list or remove_grocery_items, though it never names them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this when the user says they bought (or still need) items' gives a concrete trigger condition tied to user intent, covering both directions of the toggle. It stops short of stating when not to use it or pointing to remove_grocery_items for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this only when the user clearly asks to delete a saved recipe. Removes it from the user's Recipe One library and keeps it in a trash for 30 days, during which restore_recipe can bring it back.
| Name | Required | Description | Default |
|---|---|---|---|
| recipeId | Yes | Id of the recipe to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds the key behavior the annotations cannot express: this is a soft delete with a 30-day trash retention and a recovery route. It does not state permission requirements or what happens if the recipe is already gone, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler; the usage restriction is front-loaded before the behavioral detail. Every sentence carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool, the description covers the essentials: when to call it, that it is reversible for 30 days, and how to reverse it. What remains unstated is edge-case behavior such as deleting an already-trashed or nonexistent recipe, which is minor but not nothing.
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 recipeId parameter is already documented with type, pattern, and max length in the schema. The description adds no format or sourcing detail (e.g., where to obtain the id) beyond what the schema provides, 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 ('delete a saved recipe'), names the affected library, and distinguishes the operation from its recovery counterpart restore_recipe. An agent can differentiate it from siblings like save_recipe or remove_recipe_from_cookbook without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly gates invocation on 'the user clearly asks to delete a saved recipe', which is a real exclusion criterion for a destructive action. It also names the alternative path (restore_recipe) and the window in which it applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when you need to know whose Recipe One account is connected or what it can do. Returns the user's name, plan, remaining import credits, recipe count, week start and unit preferences.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description contributes beyond that by disclosing the actual payload of the call — name, plan, remaining import credits, recipe count, week start and unit preferences — which is meaningful behavioral context rather than restated 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?
Two sentences, both earning their place: the first sets the usage condition, the second delivers the return payload. The when-to-use clause is front-loaded and there is no filler or marketing language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameters, the description carries the full burden of explaining what comes back, and it does so exhaustively for the account settings surface. An agent has everything it needs to decide to call this and to interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The schema is an empty object with full coverage, and the description correctly adds no parameter prose that would be redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource (the Recipe One account) and answers two concrete questions: whose account is connected and what the account can do. It also enumerates the returned fields, so an agent can distinguish it immediately from the recipe- and grocery-oriented siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use this when you need to know whose Recipe One account is connected or what it can do" gives clear selection guidance for a zero-parameter account lookup that no sibling duplicates. It stops short of naming an alternative or an explicit when-not-to-use condition, but the sibling split is obvious enough that the omission costs little.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks what is on their shopping list. Returns the items on the user's Recipe One grocery list with summed quantities.
| Name | Required | Description | Default |
|---|---|---|---|
| includeChecked | No | Set false to leave out items already checked off. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. Beyond that, the description adds a non-obvious behavioral fact: duplicate entries are combined and quantities summed, which an agent cannot infer from the schema. It stops short of describing ordering or item-level shape, but with annotations in place that is a minor 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?
Two sentences: the usage trigger is front-loaded and the return behavior follows. There is no filler, hedging, or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-optional-parameter read tool with rich annotations and no output schema, the description covers when to call it and what comes back, including the quantity aggregation. Only minor details such as ordering or how checked items appear by default are unstated, and the parameter default handles the latter.
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 single includeChecked parameter is already well documented with its default and semantics. The description adds only the implicit notion that the list returned is the user's full list, adding no new meaning about the parameter beyond the schema, which fits the 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?
The description states a specific verb and resource: it returns the items on the user's Recipe One grocery list, with the added detail that quantities are summed. This clearly separates it from mutation siblings like add_to_grocery_list and check_grocery_items, though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening clause gives a concrete trigger: 'Use this when the user asks what is on their shopping list.' That covers the primary usage context well, but there are no exclusions or explicit pointers to alternatives for edge cases such as inspecting only checked-off items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks what is planned for a day or week. Returns the meals in the user's Recipe One meal plan for a date range, each with its mealType (dinner unless planned as another meal).
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days to return, starting at startDate. | |
| startDate | No | First day to return, YYYY-MM-DD. Defaults to today (UTC). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful return-shape context (each meal carries a mealType, defaulting to dinner), which matters because no output schema exists. It still says nothing about ordering, empty plans, or missing dates.
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, both earning their place: the first is front-loaded usage guidance, the second defines the return content. No filler or restatement of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool with full schema coverage, strong annotations and no output schema, the definition supplies what an agent needs: when to call it and what comes back. Only the relationship to preview_meal_plan is left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (days, startDate) are already fully documented including defaults, format and the 1-28 range. The description only restates the date-range concept and the 'day or week' framing, adding no semantics beyond the schema. 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: returns the meals in the user's Recipe One meal plan for a date range. An agent can distinguish this read operation from write siblings like add_to_meal_plan or replace_meal_plan_entry. It does not, however, distinguish itself from the sibling preview_meal_plan, which is a plausible source of confusion.
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?
"Use this when the user asks what is planned for a day or week" gives a clear triggering context tied to a concrete user utterance. The gap is the absence of any exclusion or alternative — notably preview_meal_plan, which sounds like an overlapping read tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when you need the full ingredients and steps of one of the user's saved recipes, optionally scaled to a number of servings. Scaling is only for this answer and is not saved.
| Name | Required | Description | Default |
|---|---|---|---|
| recipeId | Yes | Recipe id from search_recipes or another tool result. | |
| servings | No | Scale ingredient quantities to this many servings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: scaling applies only to this answer and is not persisted, which prevents the agent from assuming a write occurred. It stops short of saying what happens if the recipe id is unknown or whether a summary versus full detail is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the 'Use this when' trigger, followed by the one non-obvious caveat. Nothing is redundant with the title or the schema, and no sentence could be dropped without losing 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 two-parameter, fully annotated read tool with 100% schema description coverage and no output schema, the description supplies the trigger, the shape of the result (ingredients and steps), and the persistence caveat. Nothing an agent needs in order to call it correctly is missing, aside from minor error-behavior detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by framing servings as an ephemeral scaling of ingredient quantities that does not alter the saved recipe, which is semantic meaning the schema does not encode. The recipeId parameter's provenance is left to the schema's own 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 states a specific verb and resource: fetch the full ingredients and steps of a saved recipe, with optional serving scaling. That is clear enough to distinguish a detail-fetch from write siblings like save_recipe or update_recipe. It does not, however, distinguish itself from the near-identical sibling show_recipe, which leaves a real ambiguity unresolved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is an explicit trigger condition ('when you need the full ingredients and steps of one of the user's saved recipes'), which is more than implied usage. But no when-not guidance or named alternatives are given, and the schema mentions search_recipes only in passing for the recipeId parameter. The existence of show_recipe makes the missing differentiation a meaningful gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user gives a link to a recipe and wants it in their Recipe One library. Imports the link with the app's own importer (recipe websites, Instagram, TikTok, YouTube, Facebook, Pinterest) and uses one of the account's import credits. Do not use it only to read or summarize a page; for recipe text pasted in the chat use save_recipe. How it works:
Waits up to about 40 seconds. A finished import returns status "completed" with the saved recipe (id, title, servings, time, tags).
Videos can take longer. Then it returns status "processing" with the recipeId: call get_recipe with that id a minute later (without a recipeId, look for it with search_recipes). The recipe also appears in the Recipe One app.
Errors say why: no import credits left (more imports need a Recipe One subscription, managed in the app), a link that cannot be imported, or an import that failed.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The http(s) link exactly as the user gave it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations by disclosing that the call consumes an import credit from the account, waits ~40 seconds, may return status 'processing' for videos, and names the failure modes (no credits, unsupported link, failed import). This is exactly the mutation/side-effect context an agent needs for a non-read-only, open-world tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the trigger condition and exclusion, then a clean bulleted 'How it works' section covering timing, return statuses, and errors. Slightly long, and 'The recipe also appears in the Recipe One app' is marginal, but no sentence is truly wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates fully by describing both return shapes ('completed' with id/title/servings/time/tags vs 'processing' with recipeId) and the correct follow-up action for each. Nothing an agent needs in order to call it and handle the 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 the single url parameter is already documented there, so the baseline is 3. The description adds real meaning by enumerating supported link sources (recipe websites, Instagram, TikTok, YouTube, Facebook, Pinterest), which helps the agent judge whether a given URL is even eligible.
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 ('Imports the link with the app's own importer') and immediately scopes it to a user-supplied recipe link landing in their Recipe One library. It is clearly distinguishable from save_recipe (pasted text) and get_recipe/search_recipes (retrieval).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it ('user gives a link to a recipe and wants it in their library') and when not to ('Do not use it only to read or summarize a page; for recipe text pasted in the chat use save_recipe'). It also routes follow-up behavior to get_recipe and search_recipes for async video imports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks about their cookbooks (recipe collections) or you need a cookbook id. Lists the cookbooks the user owns or is a member of, with recipe counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile needs no restating. The description adds genuine behavioral context beyond that: the result set is scoped to ownership or membership, and each entry includes a recipe count. Pagination and ordering behavior remain undisclosed, which keeps it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short clauses, front-loaded with the usage trigger followed by what the call returns. Every phrase carries information; nothing is 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 parameterless read-only list tool with full annotation coverage, this is nearly sufficient: the agent knows the trigger, the scope, and the payload shape. Only minor gaps remain (no mention of empty results or ordering), and no output schema exists to cover those.
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 the baseline is 4; there is nothing for the description to disambiguate. The description correctly implies a simple no-argument call rather than hinting at filters that do not exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ("Lists the cookbooks") and clarifies the domain term with a parenthetical ("recipe collections"). It also defines the scope precisely as "the cookbooks the user owns or is a member of," which no sibling tool covers.
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 trigger is explicit: use it when the user asks about cookbooks or when a cookbook id is needed as a prerequisite for another tool. It stops short of naming alternatives (e.g. search_recipes for finding recipes rather than collections) or stating when-not to call it, so it does not reach a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a meal plan created in this conversation as an interactive calendar and combine its ingredients into a shopping list. Works without sign-in. Draft recipes and meals are not saved to Recipe One. Dietary preferences and nutrition are supplied by the assistant, not calculated by this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| meals | Yes | Planned meals, spanning at most 28 days. | |
| recipes | Yes | Full draft recipes, each with a unique recipeKey. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's contribution is the extra context it supplies: no authentication required, nothing is written back to Recipe One, and dietary/nutrition values are caller-supplied rather than computed. Those are real behavioral facts not present 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?
Three short sentences, front-loaded with the core action, each carrying distinct information (what it renders, auth/persistence stance, calculation scope). No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with a fully documented schema and no output schema, the description covers what an agent must know: the two outputs produced (calendar and shopping list), that nothing is persisted, and that nutrition is not derived. Nothing necessary for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the recipes/meals structure, enum units, date patterns and array limits are fully documented by the schema. The description adds no parameter-level meaning beyond noting that nutrition and dietary data are supplied by the assistant, which only loosely constrains what goes in the recipes payload.
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 pair and resource set: render a meal plan as an interactive calendar and combine its ingredients into a shopping list. It implicitly separates itself from save_recipe and add_to_meal_plan via 'Draft recipes and meals are not saved to Recipe One', though no sibling is named outright.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It establishes the usage context clearly: this is an ephemeral, no-sign-in preview path for data already created in the conversation, not a persistence path. It never explicitly names an alternative tool or an exclusion (e.g. 'to save, use save_recipe'), 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.
Use this when the user wants to unplan a meal. Removes entries from the user's Recipe One meal plan by the entryId that get_meal_plan returned; the recipe itself is kept.
| Name | Required | Description | Default |
|---|---|---|---|
| meals | Yes | Planned meals to remove. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the risk profile is covered. The description adds genuinely new behavior: only the plan entry is removed and the underlying recipe survives, which is exactly the fact an agent needs before a destructive 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?
Two sentences, zero filler, with the when-to-use condition front-loaded and the safety-relevant caveat second. Nothing redundant relative to the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool with no output schema, the description covers trigger, identifier source, and non-destruction of the recipe. The only real omission is that a call removes a batch of meals each keyed by its own date, which an agent must learn from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the schema already documents date and entryId. The description reinforces the entryId provenance from get_meal_plan but says nothing about the batch shape, the per-item date requirement, or the 21-item cap.
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 ('Removes entries from the user's Recipe One meal plan') and pins the identifier to entryId from get_meal_plan. The clarifier 'the recipe itself is kept' distinguishes it from delete_recipe and from add_to_meal_plan 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?
'Use this when the user wants to unplan a meal' gives a clear triggering condition and points at get_meal_plan as the source of the entryId. It stops short of naming the boundary against replace_meal_plan_entry or explaining what to do if the entryId is stale, so the exclusion set is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants items taken off their shopping list, or the checked-off items cleared. Deletes the given items, or every checked item, from the user's Recipe One grocery list.
| Name | Required | Description | Default |
|---|---|---|---|
| itemIds | No | Items to delete. Pass this or allChecked, not both. | |
| allChecked | No | true to delete every item that is checked off. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the key addition here is scoping what gets destroyed: only the supplied items, or all checked items. It does not mention irreversibility, confirmation needs, or behavior for unknown/invalid ids, which keeps it below 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?
A single sentence that front-loads the when-to-use trigger and then states the effect; no redundant phrasing or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter destructive mutation with full schema coverage, no output schema, and explicit annotations, the description covers purpose, trigger, and destruction scope. Minor gap: no note on whether deletions are reversible or what happens when an id is not found.
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 itself documents both itemIds and allChecked, including the 'pass this or allChecked, not both' exclusion. The description's phrase 'the given items, or every checked item' restates that mapping without adding format or edge-case guidance, 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?
The description states a specific verb ('Deletes') and resource ('grocery list'), and disambiguates the two operating modes: named items vs. every checked item. Against siblings like add_to_grocery_list and check_grocery_items, the scope is unmistakable.
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 conditions: the user wants items taken off the list, or checked-off items cleared. It does not name a sibling alternative or spell out when not to use it, but the two usage modes are clearly framed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants a recipe taken out of one of their cookbooks. The recipe stays in the library and in any other cookbooks.
| Name | Required | Description | Default |
|---|---|---|---|
| recipeId | Yes | Id of the recipe to take out of the cookbook. | |
| cookbookId | Yes | Id of the cookbook (from list_cookbooks). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the recipe is only unlinked from one cookbook and remains in the library and other cookbooks. It does not say whether the link can be restored or what error occurs if the recipe is not in that cookbook.
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: the trigger first, the scope clarification second. No filler, and the most decision-relevant information 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?
For a two-parameter, non-open-world tool with full schema coverage and rich annotations, only the semantic effect of the removal needed explaining, and that is done. Missing only edge-case behavior such as no-op when the recipe is not in the cookbook.
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%, with both recipeId and cookbookId documented in the schema (including the hint to get cookbookId from list_cookbooks). The description adds no constraint or format detail beyond that, so 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 ('a recipe taken out of one of their cookbooks') and immediately scopes it against the destructive alternative by noting 'The recipe stays in the library and in any other cookbooks.' This lets an agent separate it from delete_recipe without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger condition ('Use this when the user wants a recipe taken out of one of their cookbooks'), so the when-to-use case is unambiguous. It falls short of naming the sibling to use instead for permanent deletion, but the scope sentence implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace one existing meal with another saved recipe in a single transaction. Preserves its entryId and meal label. Use the date and entryId returned by get_meal_plan.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date of the existing meal, YYYY-MM-DD. | |
| entryId | Yes | entryId returned by get_meal_plan. | |
| recipeId | Yes | Replacement recipe from the user's saved library. | |
| servings | No | Servings for the replacement; defaults to the existing meal servings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description goes beyond that by disclosing atomicity ("in a single transaction") and that the entryId and meal label survive the swap, which tells the agent the entry's identity and position are stable. It does not state what happens to the previous recipe assignment or how failures roll back, leaving some destructive semantics implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the operation and its atomicity, then the preservation guarantee, then the input-provenance pointer. Nothing is redundant and no sentence could be dropped without losing 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?
With four flat parameters, full schema coverage, and annotations covering the destructive/safety profile, the definition supplies what an agent needs: provenance of identifiers, atomicity, and identity preservation. Only error/edge behavior (invalid or stale entryId) is unaddressed, a minor gap for a tool of this complexity.
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 date, entryId, recipeId, and the servings default are already documented in the schema, and the description's provenance note for date/entryId largely restates the schema wording. Baseline 3 is appropriate since the schema carries the parameter 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?
"Replace one existing meal with another saved recipe" gives a specific verb (replace) and resource (a single planned meal entry), which is clearly distinguishable from add_to_meal_plan and remove_from_meal_plan by implication. It stops short of naming those siblings explicitly, so an agent must infer the boundary rather than read it.
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?
"Use the date and entryId returned by get_meal_plan" gives concrete pre-call guidance and routes the agent to the sibling that produces the required identifiers. There is no explicit when-not (e.g., use add_to_meal_plan when no entry exists yet), so the exclusion case is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants a recipe back that was deleted through an assistant in the last 30 days. Without recipeId it lists the restorable recipes; with recipeId it restores that recipe to the library.
| Name | Required | Description | Default |
|---|---|---|---|
| recipeId | No | Id of the deleted recipe to restore. Leave out to list what can be restored. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-read-only, non-destructive, closed-world operation, so the description's job is to add context. It adds the 30-day recoverability window and the list-vs-restore dual behavior, which an agent could not infer from the annotations. It does not say whether a restored recipe returns to its original cookbook or meal plan, so a small gap remains.
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, zero waste. The usage trigger is front-loaded and the mode distinction follows immediately, so the agent gets the condition and the calling convention in one pass.
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-optional-parameter tool with no output schema and annotations that carry the safety profile, the description covers everything needed to call it correctly: the time window, both modes, and the effect of the parameter. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is already documented, so the baseline would be 3. The description still adds meaning by framing recipeId as a mode switch (present = restore, absent = list) rather than just an identifier, which helps the agent decide whether to call with or without it.
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 (restore) and resource (recipe) and immediately scopes it: deleted through an assistant within the last 30 days. It also explains the two operating modes, which separates it cleanly from siblings like delete_recipe and 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?
It gives an explicit trigger condition ('when the user wants a recipe back that was deleted through an assistant in the last 30 days') and explains that omitting recipeId lists candidates while supplying it performs the restore. There is no explicit exclusion naming an alternative sibling, 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.
Save a recipe to the user's Recipe One library. Use this for a recipe written or adapted in this chat, or for pasted recipe text. For a link, use import_recipe_from_url instead.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Up to 8 tags that clearly apply. | |
| notes | No | Optional notes: tips, substitutions, where the recipe came from. | |
| steps | Yes | Instructions in order, one step per item, without step numbers. | |
| title | Yes | Recipe title. | |
| servings | Yes | Number of servings the quantities make. | |
| cookbookId | No | Also add the recipe to this cookbook (id from list_cookbooks). Must be a cookbook the user owns and has not shared. | |
| ingredients | Yes | All ingredients, each with a numeric quantity and a unit. | |
| prepMinutes | Yes | Total time in minutes, preparation and cooking together. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a contained write with no external side effects. The description adds useful scoping about what content qualifies, but says nothing about duplicate titles, whether an existing recipe is overwritten, or what identifies the newly saved recipe. With the safety profile already carried by annotations, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and resource, then the qualifying input types, then the redirect to the sibling. Nothing is repeated or wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-destructive write with a fully documented 8-parameter schema and no output schema, the description covers what an agent needs to choose and invoke it correctly. The only gap is post-save behavior — duplicate handling and the identity of the created recipe — which would be nice but is not blocking given the annotation profile.
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 every parameter including cookbookId, tags, and the ingredient unit semantics is already documented in structured data. The description adds no parameter-level guidance beyond what the schema provides, which is the baseline-3 case for full coverage.
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 — 'Save a recipe to the user's Recipe One library' — and immediately delimits the accepted input forms (written/adapted in chat, pasted text). It explicitly distinguishes itself from the closest sibling by pointing links at import_recipe_from_url, so an agent can pick correctly without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives both sides of the routing decision: use this for chat-authored or pasted recipe text, and use import_recipe_from_url for a link. That is an explicit when-to-use plus a when-to-use-something-else, with no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks about their own saved recipes (what they have, ideas from their library, a recipe by name or ingredient). Searches the user's Recipe One library by words, tag, cookbook or time; with no filters it lists the newest recipes.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Only recipes with this tag. | |
| limit | No | Maximum recipes to return. | |
| query | No | Words that must all appear in the title, ingredients, tags or notes. Leave out to browse newest first. | |
| offset | No | Number of results to skip; use nextOffset from the previous call. | |
| cookbookId | No | Only recipes in this cookbook (id from list_cookbooks). | |
| maxPrepMinutes | No | Only recipes whose total time is at most this many minutes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description adds only that an unfiltered call returns newest-first, which the schema's 'query' parameter already states. No additional context on result size, pagination practice, or what a match looks like.
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, with the selection trigger front-loaded and the capability summary second. There is no filler and nothing redundant enough to remove.
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 read-only six-parameter search with full schema coverage, rich annotations and no output schema, the description covers selection and scope adequately. A brief note on pagination flow (using nextOffset to continue) or pointing to get_recipe for full recipe bodies would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter including limit, offset and maxPrepMinutes is already documented at the field level. The description restates the filterable dimensions but adds no semantics 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 — searching the user's own Recipe One library — and enumerates the searchable dimensions (words, tag, cookbook, time). The phrase 'their own saved recipes' cleanly separates it from import_recipe_from_url and get_recipe, so an agent can identify it without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening clause gives explicit when-to-use triggers with three concrete user intents (what they have, ideas from the library, a recipe by name or ingredient). It stops short of naming follow-up alternatives such as get_recipe for full detail or add_recipe_to_cookbook, but the context is clear enough to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a recipe created or pasted in this conversation as an interactive recipe card, optionally scale its ingredients. Works without an account; does not access a library, fetch a link, or save anything. Use save_recipe only when the user wants to save it.
| Name | Required | Description | Default |
|---|---|---|---|
| recipe | Yes | The full recipe created or pasted in this conversation. | |
| servings | No | Optional serving count to scale the card to. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that the tool works without an account (auth requirement), that it is non-persistent ('does not save anything'), that it performs no network or library access (matching openWorldHint=false), and that output is a rendered interactive card. The annotations only declare read-only/idempotent/non-destructive safety, so these are genuine additions rather than restatements.
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 what the tool does, then its constraints, then the sibling hand-off. Every clause earns its place — no restatement of the name or title 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?
For a two-parameter tool with a fully documented nested schema and no output schema, the description covers purpose, constraints and persistence behavior adequately. The only remaining ambiguity is what the rendered card actually surfaces, but with no output schema and a complete input contract this is a minor 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 description coverage is 100% and the nested recipe schema already documents every field in detail, so the baseline is 3. The description adds only 'optionally scale its ingredients', slightly clarifying the effect of the top-level servings parameter beyond the schema's 'Optional serving count to scale the card to'; the recipe parameter carries no extra guidance in prose.
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 ('Show a recipe created or pasted in this conversation'), names the output form ('interactive recipe card') and the optional modifier ('scale its ingredients'). It also rules out the adjacent capabilities (library access, link fetch, saving) in the same breath, so an agent can distinguish it from get_recipe, import_recipe_from_url and save_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?
Explicit when-not clauses ('does not access a library, fetch a link, or save anything') and a named alternative with its selecting condition ('Use save_recipe only when the user wants to save it'). Implicitly routes URL imports to import_recipe_from_url and library reads to get_recipe, giving the agent complete routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks to change one of their saved recipes (fix an ingredient, rewrite steps, rate it, mark it cooked). Only the fields you pass are changed; passing ingredients, steps or tags replaces that whole list.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | The complete new tag list; it replaces the current one. | |
| notes | No | New notes; an empty string clears them. | |
| steps | No | The complete new list of steps in order; it replaces the current steps (and merges multiple sections into one). | |
| title | No | New title. | |
| cooked | No | Whether the user has cooked this recipe. | |
| rating | No | The user's rating from 1 to 5; 0 clears it. | |
| recipeId | Yes | Id of the recipe to change. | |
| servings | No | New number of servings. This does not rescale the ingredients. | |
| ingredients | No | The complete new ingredient list; it replaces the current one. | |
| prepMinutes | No | New total time in minutes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the mutation and repeat-safety profile is known. The description adds genuinely new semantics: patch-style partial updates ('Only the fields you pass are changed') plus the important exception that ingredients, steps and tags are wholesale replacements. It does not cover ownership/permission requirements 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 sentences, front-loaded with the trigger condition, then the update-semantics rule. No filler, no restatement of the tool name or title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter mutation tool with no output schema, the description covers the two things an agent most needs: when to call it and how field merging works. It leaves unstated whether the updated recipe is returned in the response or must be re-fetched with get_recipe/show_recipe, and says nothing about ownership or failure modes for an invalid recipeId.
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%, including per-field notes like 'it replaces the current one' and the interesting 'servings does not rescale the ingredients' caveat, so the schema already does most of the work. The description's contribution is the aggregated partial-vs-replacement rule stated once for all list params, which is helpful framing but largely restates individual field 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?
The description uses a specific verb and resource ('change one of their saved recipes') and enumerates concrete change types (fix an ingredient, rewrite steps, rate it, mark cooked) that map onto the schema fields. It implicitly separates itself from add/save/delete siblings, but never names a sibling explicitly (e.g. save_recipe vs. update_recipe), so the differentiation is inferential 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?
'Use this when the user asks to change...' gives a clear triggering condition and the parenthetical examples make the scope concrete. There are no explicit exclusions or named alternatives, which matters here because a sibling named save_recipe could plausibly also touch existing recipes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_recipe_to_cookbookadd_to_grocery_listadd_to_meal_plancheck_grocery_itemsdelete_recipeget_accountget_grocery_listget_meal_planget_recipeimport_recipe_from_urllist_cookbookspreview_meal_planremove_from_meal_planremove_grocery_itemsremove_recipe_from_cookbookreplace_meal_plan_entryrestore_recipesave_recipesearch_recipesshow_recipeupdate_recipe
Add one secure layer between your agents and this server.