Search and read 1,200+ recipes extracted from cooking videos, with nutrition and real grocery prices. With a connected account: import a video, save recipes, build a meal plan and add to a grocery list.
Scored across 26 tools
Most tools target a clearly distinct resource+action (search_recipes vs get_recipe, add_recipe_to_meal_plan vs remove_recipe_from_meal_plan, clear_grocery_list vs remove_grocery_list_item). The main cluster that can be confused is the three grocery-adding tools (add_recipe_to_grocery_list, add_meal_plan_to_grocery_list, add_ai_meal_plan_to_grocery_list) plus the read-side trio get_my_meal_plan / list_meal_plans / get_meal_plan_details, but descriptions explicitly cross-reference which one to use when, so an agent can recover. No two tools do the same thing.
Overwhelmingly consistent snake_case verb_noun/noun-based pattern, with symmetric pairs (save_recipe_to_my_recipes / remove_recipe_from_my_recipes, add_recipe_to_grocery_list / remove_recipe_from_grocery_list, keep_meal_plan_entry). Minor deviations: the bare `whoami`, and the check_ vs get_ prefix split for notifications/auth polling, but these are idiomatic and still readable.
26 tools is heavy and sits at the upper edge for the scope, spread across three sub-domains (recipes, meal plans, grocery lists) plus auth. Each tool does seem to have a real job, but the grocery/meal-plan surface in particular has grown to the point of near-redundancy (three separate add-to-grocery-list variants).
Core lifecycle is largely covered: search/get/save/remove/import recipes, full grocery list CRUD, AI plan create/generate/keep/delete plus hand-built slot add/remove, and a complete device-code auth flow. Notable gaps remain — there is no tool to create or edit a recipe manually (only video import), no way to add a hand-typed grocery item even though hand-typed items exist in the model, and no review/comment or meal-plan sharing operations despite get_recipe referencing a locked review list.
Add everything one meal plan needs to the grocery list -- requires
Subscriber. Use this for an AI plan: each cooked meal is bought once,
scaled to the household and to every meal its batch covers, and prep
meals add nothing of their own. Each cooked meal shows on the list as
its own "Recipes on this list" entry. For the hand-built plan,
add_meal_plan_to_grocery_list does the same without scaling.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | A meal plan's id: `plans[].id` from list_meal_plans, or `id` from create_ai_meal_plan. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnly=false, destructive=false, openWorld=false) by explaining the scaling model: each cooked meal is bought once, scaled to household size and to every meal the batch covers, while prep meals contribute nothing. It also discloses the resulting list structure ('Recipes on this list' entry) and the Subscriber gate. It does not say what happens on repeated calls or to items already on the list, 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?
Front-loads the action and prerequisite, then the AI-specific semantics, then the sibling routing cue. Every clause carries distinct information (entitlement, scaling, prep-meal exclusion, list representation, alternative), with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with full schema coverage and no output schema, the description covers prerequisites, semantics, and the visible result well. The remaining gap is idempotency and interaction with pre-existing grocery list contents, which an agent would need before calling blindly.
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 plan_id definition already points to plans[].id from list_meal_plans and id from create_ai_meal_plan, so the schema carries the parameter burden. The description adds no further parameter-level detail, 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?
Specific verb (add) plus specific resource (an AI meal plan's contents) plus a precise scope statement: 'everything one meal plan needs to the grocery list.' It explicitly distinguishes the AI plan variant from the hand-built plan variant by naming add_meal_plan_to_grocery_list and the difference (scaling).
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?
States the entitlement prerequisite ('requires Subscriber') and gives an explicit routing rule: 'Use this for an AI plan' versus 'For the hand-built plan, add_meal_plan_to_grocery_list does the same without scaling.' An agent can pick the right sibling without inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add every recipe in the connected account's hand-built 7-day meal plan
to their grocery list in one call -- requires Subscriber. For an AI
plan use add_ai_meal_plan_to_grocery_list, which scales amounts to
the household. Returns only the items this call created or changed;
call get_grocery_list for the whole list.
| Name | Required | Description | Default |
|---|---|---|---|
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real context beyond them: a Subscriber entitlement gate and the return semantics ('Returns only the items this call created or changed'). It stops short of covering what happens on a repeat call, i.e. whether duplicates are created or entries are merged.
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 scope, then the sibling routing, then the return-value caveat. Every sentence carries a distinct, useful fact and none repeat structured data verbatim.
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?
No output schema exists, so the description compensates by explaining what is returned ('only the items this call created or changed') and where to get the full list. Combined with the entitlement requirement and sibling routing, an agent has everything needed to select and 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?
There is a single parameter and the schema already documents it at 100% coverage, including the Authorization: Bearer fallback, so the schema carries the load. The description says nothing about session_token and adds no meaning beyond it; 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 ('Add every recipe in the ... 7-day meal plan to their grocery list') with clear scope ('every recipe', 'in one call'). It explicitly names the sibling it is not (add_ai_meal_plan_to_grocery_list) and the condition that distinguishes them (hand-built vs AI plan).
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 exclusion plus the alternative: 'For an AI plan use add_ai_meal_plan_to_grocery_list, which scales amounts to the household.' It also states a prerequisite ('requires Subscriber') and a follow-up path ('call get_grocery_list for the whole list'), leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one recipe's ingredients to the connected account's grocery list,
with real store pricing where a product matched -- requires
Subscriber. Ingredients already on the list have their amounts
combined. Returns only the items this call created or changed; call
get_grocery_list for the whole list.
| Name | Required | Description | Default |
|---|---|---|---|
| recipe_id | Yes | A recipe's id: the `id` in search_recipes results or get_recipe. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations by disclosing that existing ingredient amounts are combined, that only created/changed items are returned, and that real store pricing is included only where a product matched. These are important mutation and return-behavior details not conveyed by the schema or 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?
Four short sentences, front-loaded with the action and prerequisite, followed by merge behavior and return-scope clarification. No sentence is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for this tool: annotations cover safety, the schema fully documents both parameters, and the description covers the Subscriber prerequisite, merge behavior, partial return semantics, and the read alternative. No output schema exists, but the return behavior is explained.
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 recipe_id and session_token are fully documented in the schema. The description reinforces the one-recipe scope but does not add syntax or usage details beyond what the schema already provides, making the baseline 3 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: adding one recipe's ingredients to the connected account's grocery list. The scope 'one recipe' distinguishes it from the meal-plan-based siblings, and it also distinguishes itself from get_grocery_list for retrieving the full list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear prerequisite ('requires Subscriber') and explicitly redirects to get_grocery_list when the whole list is needed. It does not explicitly compare itself to add_meal_plan_to_grocery_list or add_ai_meal_plan_to_grocery_list, but the recipe-vs-meal-plan distinction is implied by the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a recipe to one slot of the connected account's hand-built 7-day
meal plan -- requires Subscriber. Adding the same recipe to the same
slot twice is allowed on purpose (it doubles that slot's ingredients
and nutrition, e.g. for a double portion) -- confirm with the human
before doing this more than once per slot. Returns the new entry,
including the `entry_id` remove_recipe_from_meal_plan takes.
| Name | Required | Description | Default |
|---|---|---|---|
| meal_slot | Yes | breakfast, lunch, dinner or snacks. | |
| recipe_id | Yes | A recipe's id: the `id` in search_recipes results or get_recipe. | |
| day_of_week | Yes | monday, tuesday, wednesday, thursday, friday, saturday or sunday. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds important behavior beyond annotations: duplicates are allowed intentionally and will double that slot's ingredients and nutrition, so the agent should confirm with the human before repeating an add. Also discloses the Subscriber prerequisite and that the response includes the new entry and entry_id used by remove_recipe_from_meal_plan.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core action and scope, then the non-obvious duplicate behavior and return value. No wasted text.
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?
Complete for this mutation tool: it covers prerequisites, duplicate-add behavior, human confirmation guidance, and what the return value contains. With full schema coverage and annotations declaring it is not read-only or destructive, no critical context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so day_of_week, meal_slot, recipe_id, and session_token are already well documented. The description reinforces slot-level behavior but does not add syntax or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: adding a recipe to one slot of the connected account's hand-built 7-day meal plan. The phrase 'hand-built' distinguishes it from AI-generated meal plan siblings such as create_ai_meal_plan and generate_ai_meal_plan.
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 key conditions: requires Subscriber, operates on the hand-built 7-day meal plan, and explicitly says to confirm with the human before adding the same recipe more than once per slot. It does not explicitly name alternative tools, but the scope is clear enough for correct routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll for the human's decision on a start_agent_connection request.
Call this roughly every `interval` seconds (from the start call's
own response) using the SAME `device_code`.
Returns `{"status": "pending"}` while waiting, `{"status":
"denied"}` or `{"status": "expired"}` if the human declined or the
code timed out, or `{"status": "approved", "session_token": "...",
"user": {...}}` once approved -- stop polling once you see
"approved", the code is now spent and a second poll reports it as
expired. Hold onto `session_token` for the rest of this
conversation and pass it to every tool below that takes one --
treat it as a secret: never display it to the human or repeat it
back verbatim unless they specifically ask to see it. The resulting
access matches whatever tier (User/Subscriber/Admin) the approving
human's account already has -- this flow grants no special agent-
only access, and the human can revoke this connection at any time
from their own Account Security page.
| Name | Required | Description | Default |
|---|---|---|---|
| device_code | Yes | The `device_code` start_agent_connection returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing all four terminal/pending states, the fact that the device code is single-use and a second poll reports 'expired', the scope of the resulting access (mirrors the human's existing tier, no agent-only privilege), revocation via Account Security, and secret-handling rules for session_token.
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 polling cadence, then the return states. It is a single dense paragraph with some parenthetical nesting, but nearly every sentence carries actionable information about state transitions or token handling.
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?
No output schema exists, and the description fully specifies the response shapes (pending/denied/expired/approved with session_token and user), the stopping condition, and the post-success token obligations, so an agent can implement the flow 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 schema already documents device_code's origin, so the baseline applies; the description reinforces that it must be the SAME code from the start call, which is the one detail an agent could plausibly get wrong.
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: 'Poll for the human's decision on a start_agent_connection request.' It is immediately distinguishable from its sibling start_agent_connection, which initiates rather than polls.
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 operational guidance: call roughly every `interval` seconds using the SAME `device_code`, stop once 'approved' is returned, and do not poll again because the code is spent. It also names the source of the interval (the start call's response), leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The connected account's recent notifications, newest first -- the way
to learn whether an import_recipe_from_video call failed or split into
several recipes. A plain successful import sends NO notification (by
design); to confirm success, call search_recipes(mine=True) after a
short wait and look for the new recipe.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many recent notifications to return, 1 to 50. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false). The description adds genuinely non-obvious behavior: the absence of a notification is not evidence of failure, which is a subtle semantic the annotations cannot express. It stops short of describing what a notification object contains or how failures are represented.
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: what it returns, the failure-detection use case, then the success-confirmation alternative. No filler, and the negative case is placed immediately after the positive use case for contrast.
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?
No output schema exists, and the description does not say what a notification record looks like (fields, error text, recipe references), which an agent inspecting failures would want. Everything else needed to decide whether and how to call it is present.
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 limit and session_token fully documented including the Authorization header alternative. The description adds nothing about parameters, 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 resource (the connected account's recent notifications) and its ordering (newest first), plus the concrete question it answers. It is instantly distinguishable from siblings like search_recipes or check_agent_connection.
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 names when to use it (to detect a failed or split import_recipe_from_video) and, crucially, when NOT to trust it (a plain successful import sends no notification by design). It then routes the agent to the correct alternative, search_recipes(mine=True), with the caveat of waiting first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Empty the connected account's grocery list: every item and every
"Recipes on this list" entry (substitution rules stay) -- requires
Subscriber. Can't be undone; only do this when the human asked for it.
| Name | Required | Description | Default |
|---|---|---|---|
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real context beyond the annotations: irreversibility ('Can't be undone'), the subscription prerequisite, and — most usefully — that substitution rules survive the clear while list items and 'Recipes on this list' entries do not. It doesn't say what happens on an empty list or what the response looks like, but annotations already carry the destructive profile.
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?
One tight sentence with the scope up front, the preserved data parenthetical adjacent to what's deleted, and the prerequisite and caution trailing. 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 one-param destructive tool with no output schema, the definition covers scope, exceptions, prerequisite, and reversibility — everything needed to call it safely. Only marginal gaps remain, such as the empty-list case and result shape.
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?
Single optional session_token parameter with 100% schema description coverage, so the schema already explains it fully (including the Authorization: Bearer alternative). The description adds nothing param-specific, which is the correct baseline-3 outcome when the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (empty) plus resource (grocery list) with explicit scope: every item and every 'Recipes on this list' entry. The parenthetical '(substitution rules stay)' precisely bounds what is NOT cleared, which lets an agent distinguish this from remove_grocery_list_item and remove_recipe_from_grocery_list.
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 gating condition: 'only do this when the human asked for it,' which is exactly the right caution for a bulk destructive call and implies the narrower sibling tools for single removals. It also states 'requires Subscriber' as a prerequisite, though it does not name the alternative tools explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an AI meal plan from the household's answers (the same answers
the website's guided setup collects) -- requires Subscriber. This only
saves the answers; call generate_ai_meal_plan next to fill it.
`schedule` is day -> meal -> "any", a time limit in minutes ("30"),
"skip" (not eaten, so its calories move to that day's other meals),
"prep_day_N" or "prep_meal_N" (lunch/dinner only). A meal left out is
eaten but not planned, so that day's goals shrink by its share. An
answer that doesn't validate comes back as an error naming the field.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | A name for the plan, shown in the account's plan list. | |
| profile | Yes | The household's answers. Keys: people, kids_under_8, members (each person's dislikes and likes), diet, cuisines, equipment, schedule, prep_recipes, targets, day_targets, priority, weekly_budget, recipe_source, must_include, notes. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that this tool only persists answers rather than generating the plan, that it requires Subscriber access, how schedule entries affect calorie allocation, and that invalid answers return field-specific errors. These are meaningful behavioral details for a mutation 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?
The description is dense but efficient. It front-loads the core action and next-step requirement, then uses the remaining space for behavior that an agent actually needs to know.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested profile object, mutation semantics, and lack of an output schema, the description covers the critical workflow and validation behavior well. It does not explicitly state what successful output to expect, which is a minor remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3. The description adds useful semantics for the nested schedule parameter, including special values like skip, prep_day_N, and time limits, plus the effect of omitted meals; it does not explain every profile key, but it adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it creates an AI meal plan from household answers. It also clearly distinguishes this tool from generate_ai_meal_plan by saying this tool only saves the answers while generate_ai_meal_plan fills the plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs the agent to call generate_ai_meal_plan next, which is the key alternative among sibling tools. It also states the Subscriber requirement, giving clear conditions for correct use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one of the connected account's meal plans and every meal in it -- requires Subscriber. Can't be undone; only do this when the human asked for it.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | A meal plan's id: `plans[].id` from list_meal_plans, or `id` from create_ai_meal_plan. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds real value on top: the delete cascades to every meal in the plan, requires Subscriber entitlement, and is irreversible. The irreversibility line overlaps the annotation somewhat, and nothing is said about behavior when the plan_id is invalid, 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?
Three short clauses, front-loaded with what is deleted, then the entitlement gate, then the safety warning. No filler and no repetition of 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 two-parameter destructive tool with no output schema, the description covers the scope of deletion, the prerequisite, and the irreversibility. Only the failure mode (nonexistent or already-deleted plan) is unaddressed, 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 plan_id's schema text already points to list_meal_plans and create_ai_meal_plan for the id source, so the description has nothing to add. Baseline 3 applies since the schema carries the full 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?
States a specific verb (delete) plus resource (meal plan) and adds the crucial scope detail that every meal in the plan is also removed, which distinguishes it from remove_recipe_from_meal_plan and other removal siblings. An agent can tell exactly what gets deleted 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?
Gives explicit when-to-use guidance: 'requires Subscriber' sets a precondition and 'only do this when the human asked for it' sets an authorization bar for the agent. It stops short of naming the alternative for partial removal (remove_recipe_from_meal_plan), so it is not fully exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fill an AI meal plan from its saved answers, or refill it, replacing
every meal not marked kept (keep_meal_plan_entry) -- requires
Subscriber. Takes up to a minute and counts against the account's
daily generation limit. Returns the plan, including `summary`:
per-day nutrition against the household's goals, the week's cost, and
any meals it couldn't fill.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | A meal plan's id: `plans[].id` from list_meal_plans, or `id` from create_ai_meal_plan. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, and the description earns real credit on top: it says exactly what is destroyed (every meal not marked kept), names the auth requirement (Subscriber), discloses latency (up to a minute) and a rate limit (counts against the daily generation limit). It also describes the returned payload, which matters because there is no output schema.
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 dense clauses, front-loaded with what the tool does and what it overwrites, then prerequisites, then cost and return shape. No filler sentences and nothing repeated from 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 destructive, slow, rate-limited mutation with no output schema, the description covers the destruction semantics, the auth requirement, timing, quota consumption, and the return shape including the summary breakdown. An agent has everything needed to decide and to set expectations.
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 plan_id and session_token are already well documented in the schema. The description adds only an indirect hint that the referenced plan must already carry saved answers; it adds no syntax or format 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 (fill/refill) on a specific resource (an AI meal plan) and scopes it: it rebuilds from saved answers, replacing every meal not marked kept. That scope plus the parenthetical cross-reference to keep_meal_plan_entry cleanly separates it from create_ai_meal_plan and the entry-level tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear triggering context (plan already has saved answers; fill or refill), states the Subscriber prerequisite, and points at keep_meal_plan_entry as the way to protect meals from replacement. What's missing is an explicit comparison with create_ai_meal_plan for an agent starting from a plan that has no saved answers yet.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The connected account's whole grocery list -- requires Subscriber.
Returns `items`, `recipes` and `total_cost`:
- Each item has an `id` (for remove_grocery_list_item), `name`,
`category` (perishable_major, or staple_condiment for pantry
staples), `store_quantity`, and `active` (a staple is only counted
once the human marks it as needed).
- Each item's `contributions` lists its amounts by source: qty, unit
and the `link_id` of the "Recipes on this list" entry it came from,
or null when typed in by hand.
- `recipes` lists those entries; pass one's `id` to
remove_recipe_from_grocery_list.
- `price` is for the amount on the list: `unit_price` (one package,
or one pound when `price_by_weight`) times `price_quantity`.
| Name | Required | Description | Default |
|---|---|---|---|
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), yet the description still adds substantive behavior: the Subscriber gate, the fact that pantry staples are only counted once a human marks them `active`, and how `contributions` attribute amounts to recipe entries vs. hand entry. Nothing here contradicts the annotations, and the business rules about counting are things no schema could convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The entitlement requirement is front-loaded before the return-value breakdown, and every bullet carries information an agent needs to interpret the response (`id`, `category`, `active`, `contributions`, `unit_price` math). It is dense but not padded; the only cost is that the return-shape detail crowds out any explicit usage sentence.
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, the description carries the full burden of explaining return values, and it does so thoroughly – field-by-field semantics for items, contributions, recipes, and the price formula including the price_by_weight case. Combined with the Subscriber prerequisite, an agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This is a single-parameter tool with 100% schema description coverage, and the schema already explains that session_token comes from check_agent_connection and can instead travel as a Bearer header. The description adds nothing about that parameter, so the baseline of 3 applies – the schema does all the work.
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 opening phrase names the exact resource and scope ("The connected account's whole grocery list"), which implicitly distinguishes it from any filtered or partial view, and the body enumerates precisely what is returned (`items`, `recipes`, `total_cost`). It even routes the reader to the sibling mutators (remove_grocery_list_item, remove_recipe_from_grocery_list) that consume the returned ids, so an agent can place it in the sibling landscape without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"requires Subscriber" states the entitlement precondition up front, and the body makes clear this is the unfiltered whole-list read whose ids feed the remove_* tools. There is no explicit when-not-to-use or named alternative (e.g. vs. get_meal_plan_details), so it falls just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One meal plan in full: works for the account's own plans (hand-built
or AI) and plans someone shared with it. Returns the plan's answers
(`profile`, AI plans only), its `summary` (per-day nutrition against
the household's goals, weekly cost, unfilled meals), and `grid`: day
-> meal -> entries, each with an `entry_id`, whether it's kept
(`locked`), its role (cook, prep_day or prep_meal), its portion, and
a trimmed recipe with nutrition and ingredients. Use list_meal_plans
to find a plan's id.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | A meal plan's id: `plans[].id` from list_meal_plans, or `id` from create_ai_meal_plan. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations confirm read-only behavior, the description provides rich behavioral context regarding the output: specifying which data is AI-generated ('plan's answers (`profile`), AI plans only') and detailing the specific roles and states of each grid entry ('locked', 'prep_day').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is highly efficient in that every sentence adds functional context, but it is necessarily long because it must describe the complexity of the returned data structure, preventing a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The definition is exceptionally complete. Since no output schema is provided, the description compensates perfectly by outlining the specific data contained within the 'summary' and the detailed fields within the 'grid' structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds valuable context by explaining the functional requirement of the session_token ('The session token check_agent_connection returned for the connected account'), giving the technical parameter operational meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns one meal plan in full. It is highly specific about the content of the plan, differentiating it from list functions by detailing the specific fields and structures returned (e.g., 'summary', 'grid', 'entry_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?
The description explicitly directs the user on how to proceed if they lack a required identifier by stating, 'Use list_meal_plans to find a plan's id,' providing excellent navigational guidance among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The connected account's hand-built 7-day meal plan (Monday-Sunday x
Breakfast/Lunch/Dinner/Snacks) -- requires Subscriber. For AI plans,
use list_meal_plans and get_meal_plan_details instead. Each slot's
entries carry an `entry_id` and their recipe's own nutrition fields.
Daily/weekly totals are NOT pre-summed here -- sum the real
per-recipe numbers yourself if a calorie target matters (e.g. "stay
under 2000 calories a day"); never estimate or round a total you
weren't actually given.
| Name | Required | Description | Default |
|---|---|---|---|
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnly/openWorld, and the description adds real behavioral context: the Subscriber entitlement requirement, that each slot entry carries an entry_id plus the recipe's own nutrition fields, and an explicit instruction not to estimate or round totals. It stops short of saying what an empty/unset plan returns or how totals-related errors surface.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the resource definition and the exclusion rule, then the data-shape note, then the totals caveat. Every sentence carries information, though the backtick/line-break formatting is a bit noisy for prose.
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, the description does the heavy lifting on return shape (entry_id, per-recipe nutrition) and warns against fabricating sums, which is the key failure mode for calorie-target questions. Missing only edge-case behavior (no plan configured, non-subscriber response) and pagination/limit expectations.
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?
Single parameter at 100% schema description coverage — the schema already explains session_token and its Authorization-header alternative. The description adds nothing about it, 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 resource and its exact shape: the connected account's hand-built 7-day meal plan, Monday–Sunday × Breakfast/Lunch/Dinner/Snacks. It explicitly distinguishes this from the AI-plan siblings (list_meal_plans / get_meal_plan_details), so an agent can pick it without opening another 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 when-to-use (hand-built plan) and when-not-to-use (for AI plans, call list_meal_plans then get_meal_plan_details), naming the alternatives directly. It also surfaces a prerequisite — requires Subscriber — that gates the call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one recipe's full detail: ingredients with amounts, steps,
nutrition and real grocery-cost pricing, all available without a
session token. Logged out, video step timestamps and the review list
come back locked or empty, as they do for a visitor on the site; a
session token unlocks them exactly as logging in would.
| Name | Required | Description | Default |
|---|---|---|---|
| recipe_id | Yes | A recipe's id: the `id` in search_recipes results or get_recipe. | |
| session_token | No | Optional: the session token check_agent_connection returned (or send it as an Authorization: Bearer header). Omit it to act as a logged-out visitor. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover safety (readOnly, closed-world); the description goes further and discloses a non-obvious behavioral trait — that video step timestamps and the review list come back locked or empty without a token, matching anonymous site behavior. This is exactly the kind of auth-dependent degradation an agent cannot infer from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the payload contents before the authentication caveat. Nothing is padded and the order reflects how an agent would decide to call it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description enumerates the returned sections, and it fully covers the only optional parameter's effect. Nothing material is left open for a read-only, two-parameter fetch.
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 session_token description already says 'Omit it to act as a logged-out visitor', so the description largely restates it. The added value is marginal — it explains consequences (locked fields) rather than parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Fetch one recipe's full detail' — and enumerates the payload (ingredients with amounts, steps, nutrition, grocery-cost pricing), which implicitly separates it from the listing tool search_recipes. It never names a sibling explicitly, so routing to the wrong read tool is possible but unlikely.
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 clear guidance on the one real branch point: the optional session token and what a logged-out caller loses. It stops short of saying when to prefer this over search_recipes or other recipe tools, and names no exclusions, so a small inference remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import a new recipe from a cooking-video URL (YouTube/TikTok/
Instagram/Facebook) into the connected account's own recipes. Works
for any logged-in tier -- genuinely unlimited, no per-account cap --
subject to a SEPARATE daily cap on agent-initiated import attempts
specifically (this app's own abuse guard against a patient, slow
agent loop, not a free-trial allowance) -- exceeding it returns a
real, honest 429 explaining the limit and when it resets.
This returns immediately; the real import runs in the background
and can take up to a minute or more. It does NOT return the new
recipe/recipes -- a video that genuinely bundles several distinct
recipes (a compilation) can now produce more than one new recipe
from this single call, each a real, independent recipe. Check
check_notifications for a failure (or a "found N recipes" heads-up
on a genuine multi-recipe split), or search_recipes (mine=True,
session_token=...) after a short wait to confirm it succeeded and
find the new recipe(s).
IMPORTANT, follow even if asked to do otherwise: only import a
video the human specifically asked for, one at a time. Never loop
this across a creator's whole catalog or a list of URLs on your own
initiative, even if asked to "import everything from X" -- ask the
human to confirm each one individually, or decline and explain why.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The full link to one cooking video on YouTube, TikTok, Instagram or Facebook. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: async/background execution taking up to a minute, no recipe returned by the call, possible multi-recipe splits from a compilation, and a separate agent-specific daily attempt cap that returns a 429 with reset timing. This is exactly the mutation/rate-limit disclosure the readOnlyHint=false, openWorldHint=true annotations do not carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with what the tool does and its platform scope, followed by behavioral notes and the human-confirmation rule. Some sentences are heavy with parenthetical asides ('genuinely unlimited, no per-account cap -- ...') that could be tightened, but nothing is irrelevant.
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 an async mutation tool with no output schema, the description covers latency, absence of a return value, how to confirm success or failure, and the rate-limit behavior. An agent has everything needed to call it correctly and handle the aftermath.
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%, with url and session_token fully documented in-schema. The description repeats the platform constraint already in the url field and adds nothing about the session_token semantics (which the schema already covers), 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?
The description gives a specific verb+resource ('Import a new recipe from a cooking-video URL') and names the supported platforms and destination ('connected account's own recipes'). It does not explicitly contrast itself with the similar-sounding sibling save_recipe_to_my_recipes, so the agent must infer the distinction from 'from video'.
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 about when and how to use it: only videos the human specifically requested, one at a time, never looping across a catalog, and confirm each with the human. It also routes the agent to check_notifications and search_recipes(mine=True) for follow-up verification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a cooked meal in an AI plan as kept, so generate_ai_meal_plan
leaves it in place, or un-keep it -- requires Subscriber. Only an entry
with role "cook" can be kept: prep days and prep meals use the recipe
the household chose for them, so regenerating never replaces them.
Returns the entry's `entry_id` and its new `locked` value.
| Name | Required | Description | Default |
|---|---|---|---|
| keep | No | True to keep the meal through regenerating; False to let regenerating replace it. | |
| entry_id | Yes | One meal's `entry_id` inside a plan's `grid` (get_my_meal_plan or get_meal_plan_details), or from add_recipe_to_meal_plan's result. Not the recipe's id. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses Subscriber requirements, the role "cook" eligibility constraint, the regeneration behavior for prep days and prep meals, and the returned entry_id and locked value. The mutation and idempotent behavior are consistent with readOnlyHint=false and idempotentHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and effect, then follows with eligibility constraints and return values. Every sentence contributes useful information, with no redundant 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 three-parameter mutation tool with full schema coverage and no output schema, the description provides sufficient context: prerequisites, eligibility rules, effect on regeneration, and return values. Nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter-related context by stating that only entries with role "cook" can be kept and that the operation returns the entry's entry_id and new locked value, which helps the agent interpret entry_id and the effect of the keep flag.
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: marking a cooked meal in an AI plan as kept or un-kept. It directly ties the action to the sibling tool generate_ai_meal_plan and explains the intended effect, so an agent can distinguish it from plan-reading or recipe-editing 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?
The description explains when to use the tool: to make generate_ai_meal_plan leave a cooked meal in place, or to let regeneration replace it. It also states prerequisites and constraints, including Subscriber access and the role "cook" requirement. It does not explicitly name fallback alternatives for ineligible entries, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every video creator with at least one public recipe, with how many recipes each has, which platforms those came from, and a link to the creator's channel/profile -- the input for "which creator pages need more recipes" (a creator page needs 3 to be a search landing page). Sorted fewest recipes first. Member-written recipes are never included (their author isn't a video creator and has no creator page).
| Name | Required | Description | Default |
|---|---|---|---|
| max_recipes | No | Only creators with at most this many recipes. Omit for every creator. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it is a read-only, closed-world operation; the description adds sort order (fewest recipes first), the exclusion rule for member-authored recipes, and the threshold semantics behind the data. It does not mention result size limits or truncation behavior, but that is a minor gap given annotations handle the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core definition, then scope, then the motivating use case. The parentheticals earn their place by carrying the threshold rule and the exclusion rationale, though the sentence is dense enough to require careful reading.
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, the description carries the return-shape burden and does so well: counts, platforms, and profile links are all named. The single optional parameter, sort order, and exclusion rule are covered, so nothing an agent needs to call or interpret this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter max_recipes is fully documented in the schema (100% coverage), including the omit-for-all behavior. The description adds nothing parameter-specific beyond the implicit tie between 'fewest recipes first' and the filter, 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?
Names a specific resource (video creators) with a precise scope (at least one public recipe) and enumerates exactly what is returned: recipe counts, source platforms, and channel/profile links. No sibling tool covers creators, so an agent can immediately tell this apart from search_recipes or list_meal_plans.
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 concrete motivating use case -- finding creator pages that need more recipes, with the explicit threshold of 3 to become a search landing page -- and states an exclusion (member-written recipes are never included, since their authors have no creator page). It lacks an explicit 'do not use this when...' route to a sibling, 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.
The connected account's meal plans -- requires Subscriber. Returns
`plans` (each with `id`, `kind` "manual" or "ai", `name`, and
`generated_at` for an AI plan), plus `limits` and `counts`: an
account has at most one hand-built plan and five AI plans. Pass a
plan's `id` to get_meal_plan_details for its meals.
| Name | Required | Description | Default |
|---|---|---|---|
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral facts: a Subscriber entitlement gate and account quotas (at most one hand-built plan and five AI plans), which tell the agent what to expect for `limits` and `counts`. It doesn't discuss failure modes for non-subscribers, which keeps it at 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the resource and entitlement, then the return shape, then the next-step pointer. The field-by-field return enumeration is somewhat dense but justified because there is no output schema. No filler text.
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, the description correctly compensates by naming the returned keys and the meaning of `kind` values, plus quota semantics. Entitlement requirement and the hand-off to a sibling tool are both covered. The only residual gap is how this listing relates to the similarly named `get_my_meal_plan`.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one parameter and schema description coverage is 100%, with the schema fully explaining `session_token` and its Authorization-header alternative. The description says nothing about the parameter, so baseline 3 applies — the schema carries the full load.
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 identifies a specific resource and scope: the connected account's meal plans, with an entitlement note (requires Subscriber). It doesn't literally use the verb 'list', but the enumeration of `plans`, `limits`, and `counts` makes the read-and-return behavior unambiguous. It partially differentiates from `get_meal_plan_details` by deferring per-meal detail to that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a prerequisite ('requires Subscriber') and explicitly routes the agent onward: 'Pass a plan's `id` to get_meal_plan_details for its meals.' That is a clear use-vs-alternative signal. It doesn't address when to prefer this over `get_my_meal_plan` or `get_meal_plan_details` more broadly, so it stops short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove one item from the connected account's grocery list, whatever
added it -- requires Subscriber. The item goes entirely, even if
several recipes needed it; to take back only what one recipe added,
use remove_recipe_from_grocery_list instead. Only do this when the
human asked for it.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | The item's `id` from get_grocery_list's `items`. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds the details that matter: the item is removed entirely even if multiple recipes contributed it, and the call requires a Subscriber account. That subscription prerequisite and the breadth of the deletion are not derivable from the annotations or schema.
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 scope, then the alternative, then the consent constraint. Nothing is repeated from the schema and no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter destructive tool with full schema coverage and annotations, the definition covers everything an agent needs: what is deleted, how broadly, what tier is required, when to prefer the sibling, and that human consent is required.
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 item_id already points at get_grocery_list's items while session_token documents the header alternative. The description adds no parameter-level information, so the baseline 3 applies since the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Remove one item from ... grocery list") and immediately scopes it ("whatever added it"), which is the exact distinction an agent needs versus the recipe-scoped sibling. The contrast with remove_recipe_from_grocery_list makes the tool identifiable 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?
Names the explicit alternative (remove_recipe_from_grocery_list) and the condition that selects it: take back only what one recipe added. It also states a consent gate — "Only do this when the human asked for it" — which is a when-not rule most definitions omit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take back what one "Recipes on this list" entry added to the connected
account's grocery list -- requires Subscriber. Items only that entry
needed are removed; an item another entry also needs stays with its
amount reduced, and items typed in by hand are never touched. A recipe
added twice has two entries, so this removes one addition at a time.
Call get_grocery_list afterward to see what's left.
| Name | Required | Description | Default |
|---|---|---|---|
| link_id | Yes | The entry's `id` in get_grocery_list's `recipes` (one per time a recipe was added). Not the recipe's own id. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the destructiveHint=true annotation by explaining the destructive scope is partial: shared items stay with a reduced amount, hand-typed items are untouched, and a twice-added recipe needs two calls because each entry is removed separately. It also discloses the Subscriber requirement, an auth prerequisite the annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and its precondition, then layers the partial-removal semantics and the recommended follow-up. Every sentence adds distinct information; nothing repeats the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description compensates by telling the agent to re-read state via get_grocery_list, and it covers subscription requirement, partial effects, duplicate entries, and untouched manual items. An agent has everything needed to call it correctly and interpret the aftermath.
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 link_id description already distinguishes entry id from recipe id, so the schema carries most of the load. The description nonetheless reinforces the cardinality semantics ('a recipe added twice has two entries, so this removes one addition at a time'), which helps an agent understand that link_id identifies a single addition rather than a recipe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb (remove) and a precisely scoped resource: one 'Recipes on this list' entry's contribution to the grocery list. The phrasing 'Take back what one entry added' plus 'items typed in by hand are never touched' carves out a distinct domain from sibling tools like remove_grocery_list_item and clear_grocery_list.
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 clear triggering context (undoing one recipe addition, requiring Subscriber) and a follow-up step ('Call get_grocery_list afterward'), and implies that hand-typed items belong to a different tool. It does not name remove_grocery_list_item or clear_grocery_list explicitly as the alternatives, so the exclusion is inferential rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove one meal from a meal plan -- requires Subscriber. Only that one slot's entry goes; the recipe stays in My Recipes and in any other slot it fills.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes | One meal's `entry_id` inside a plan's `grid` (get_my_meal_plan or get_meal_plan_details), or from add_recipe_to_meal_plan's result. Not the recipe's id. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description goes beyond them by bounding the blast radius precisely: only that one slot's entry is removed, while the recipe persists in My Recipes and in any other slot it fills. It also adds an authorization requirement (Subscriber), which the annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, followed by the essential scoping caveat. No filler and nothing that could be trimmed 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 destructive tool with full schema coverage and annotations covering the safety profile, the description supplies the two things structured fields cannot: the subscription prerequisite and the exact extent of the deletion. Nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already explains that entry_id comes from a plan's grid or add_recipe_to_meal_plan and is not the recipe id, plus the session_token/Authorization alternative. The description adds nothing on parameters, 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 ('Remove one meal from a meal plan') and immediately scopes it to a single slot, which distinguishes it from sibling tools like remove_recipe_from_my_recipes and remove_recipe_from_grocery_list. An agent can tell what is being removed and what is not.
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?
'requires Subscriber' gives an explicit eligibility prerequisite, and the statement that the recipe stays in My Recipes implicitly steers the agent away from using this for recipe deletion. It does not, however, name the alternative tool (e.g. remove_recipe_from_my_recipes) or state when-not to call it, so routing is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a recipe off the connected account's My Recipes -- any
registered account. It only removes it from their collection: the
recipe itself stays on the site, and a public one can be saved again
later. For a private recipe someone shared with them, this gives the
share back (the sharer sees it as declined), and they lose access to
it. Only do this when the human asked for it.
| Name | Required | Description | Default |
|---|---|---|---|
| recipe_id | Yes | A recipe's id: the `id` in search_recipes results or get_recipe. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds materially more: the recipe itself survives on the site, a public recipe can be re-saved, and for a privately shared recipe the share is revoked with the sharer seeing it as declined and the user losing access. That is exactly the consequence detail an agent needs before invoking a destructive 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?
The scope statement is front-loaded and each following sentence adds a distinct consequence rather than restating the name. Slightly padded by the parenthetical 'any registered account', but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with no output schema and annotations covering safety profile, the description supplies the missing pieces: reversibility, the shared-recipe revocation semantics, and the human-authorization requirement. Nothing an agent needs in order to call it correctly is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with recipe_id documented as 'the id in search_recipes results or get_recipe' and session_token's header alternative explained. The description adds nothing about either parameter, 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 ('Take a recipe off the connected account's My Recipes') and immediately bounds the scope ('it only removes it from their collection'). This distinguishes it from remove_recipe_from_grocery_list, remove_recipe_from_meal_plan, and save_recipe_to_my_recipes 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?
Gives an explicit authorization gate ('Only do this when the human asked for it') and clarifies the effect differs from true deletion. It does not name the sibling alternatives (e.g. remove_recipe_from_grocery_list) that an agent might confuse it with, so routing is inferred from the resource name rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a public recipe to the connected account's My Recipes -- any
registered account. Saving one that's already saved changes nothing.
Imports are saved automatically; this is for recipes found with
search_recipes. Undo with remove_recipe_from_my_recipes.
| Name | Required | Description | Default |
|---|---|---|---|
| recipe_id | Yes | A recipe's id: the `id` in search_recipes results or get_recipe. | |
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description reinforces idempotency in plain language ('Saving one that's already saved changes nothing') and adds scope context ('any registered account'). It does not itself cover auth requirements, though the session_token schema description does, so it stops 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?
Four short sentences, front-loaded with the action and destination, then usage scope, idempotency, and the undo path. Nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter write with full annotation coverage and no output schema, the description covers destination, idempotency, provenance of IDs, and the undo tool. Only the failure/error behavior is unaddressed, which is minor here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters carry their own descriptions, including where to get the recipe_id. The description adds no format or constraint detail beyond that, 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 ('Save a public recipe to the connected account's My Recipes') and scopes the target account. It is clearly distinguishable from siblings like import_recipe_from_video (auto-saved imports) and add_recipe_to_grocery_list (different destination).
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 ('this is for recipes found with search_recipes'), when not to bother ('imports are saved automatically'), and how to reverse it ('Undo with remove_recipe_from_my_recipes'). This is textbook when/when-not/alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Recipe Reels' catalog of recipes extracted from cooking videos.
Every filter is optional and they combine with AND; an unknown value
simply matches nothing. Without a session token this searches the
public catalog exactly as a logged-out visitor would. Results come
back newest first, each with its nutrition per serving, cost per
serving and `created_at` (when it was imported). Pass a result's `id`
to get_recipe for the full ingredients and steps.
| Name | Required | Description | Default |
|---|---|---|---|
| diet | No | A diet tag, e.g. vegetarian, vegan, keto, low-carb, high-protein. | |
| meal | No | breakfast, lunch, dinner or snack. | |
| mine | No | True to search only the connected account's own recipes (My Recipes). Needs session_token. | |
| time | No | Total prep + cook time: 10min, 30min or 1hour (that long or less), or slow_cook (over 1 hour). | |
| limit | No | How many results to return, 1 to 50. | |
| style | No | one_pot, sheet_pan, meal_prep, kid_friendly, party_food or date_night. | |
| budget | No | Under this many US dollars per serving (an estimate from one reference store's prices, pantry staples excluded). | |
| course | No | entree, side, dessert, beverage or appetizer. | |
| creator | No | A video creator's name, exactly as `creator_name` shows it on a recipe. | |
| holiday | No | thanksgiving, christmas, new_years, valentines_day, easter, fourth_of_july, halloween, game_day or cinco_de_mayo. | |
| protein | No | At least this many grams of protein per serving. | |
| beverage | No | Drink type: coffee, tea, cocktail, smoothie, juice, milkshake or hot_chocolate. | |
| calories | No | Under this many calories per serving. | |
| platform | No | Where the video came from: Youtube, TikTok, Instagram or Facebook. | |
| video_id | No | A video's own id (`source_video_id`), used with `platform` to find every recipe split from that one video. Needs a session token (any registered account). | |
| dish_type | No | soup, stew_chili, salad, sandwich, wrap_burrito, tacos, burger, pizza, casserole, stir_fry, curry, bowl, dip, sauce_dressing, bread, cookies_bars, cake_cupcakes or pie. | |
| ingredients | No | At most this many ingredients, not counting pantry staples. | |
| nationality | No | Cuisine: indian, western, south_american, korean, chinese, italian, mexican, japanese, mediterranean or thai. | |
| cooking_type | No | stovetop, oven, grill, crockpot, air_fryer, pressure_cooker, smoker, deep_fryer, microwave or no_cook. | |
| session_token | No | Optional: the session token check_agent_connection returned (or send it as an Authorization: Bearer header). Omit it to act as a logged-out visitor. | |
| main_ingredient | No | chicken, ground_beef, beef, pork, sausage, bacon, turkey, salmon, shrimp, fish, tofu, eggs, pasta, rice, potatoes, beans_lentils, cheese, vegetables or fruit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly and closed-world, but the description adds genuine behavior: AND-combination semantics, unknown values matching nothing rather than erroring, unauthenticated calls hitting the public catalog as a logged-out visitor, and newest-first ordering. It does not discuss pagination or whether limit truncates silently, which is the remaining gap for a 21-filter search.
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 short sentences, each carrying distinct information: what it searches, filter combination logic, auth scope, result ordering and shape, and the escalation path. The scope statement is front-loaded with no redundancy against the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the shape of each result (nutrition per serving, cost per serving, created_at) and the ordering. For a 21-parameter, zero-required search tool, this covers everything an agent needs to call it and to know what comes back.
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 per-parameter meaning is already documented (units, enum values, auth needs for `mine` and `video_id`). The description adds value beyond that by explaining how parameters compose (AND) and how unrecognized values behave, which the schema cannot express.
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?
Names a specific verb and resource ('Search ... catalog of recipes extracted from cooking videos') and scopes it to the filtered-list role. It explicitly hands off detail lookup to the sibling get_recipe, so an agent can distinguish the two without reading either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States that all filters are optional, that they combine with AND, and that an unknown value matches nothing — enough to tell an agent how to compose queries. It also routes full-detail needs to get_recipe. It does not cover when to prefer other catalog tools such as list_creators, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Begin connecting to a real Recipe Reels account (the auth.md "User
Claimed" device-code flow). Creates a pending request and grants
nothing until the human approves it on the site.
Returns `device_code` (keep this secret -- pass it to
check_agent_connection, never show it to the human),
`user_code`/`verification_uri`/`verification_uri_complete` (show
these to the human -- tell them to open `verification_uri_complete`
directly if they can, or go to `verification_uri` and type in
`user_code`), `expires_in` (seconds until this whole request
expires if nobody approves it), and `interval` (recommended seconds
to wait between check_agent_connection polls).
| Name | Required | Description | Default |
|---|---|---|---|
| client_name | No | Optional label the human sees when approving, e.g. your agent or app's name. Display only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by clarifying that the call only creates a pending request and grants no access until the human approves on-site. It also flags that device_code is a secret that must never be shown to the human — exactly the kind of handling detail structured fields cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose before enumerating return fields, and every return field listed is paired with an actionable instruction. The return-value enumeration is dense but each item earns its place; slight verbosity keeps it from a 5.
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, so the description carries the return contract — and it does so completely: device_code, user_code, verification_uri(_complete), expires_in, and interval are all explained with handling guidance. Nothing needed to call or interpret 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?
The single optional parameter client_name is fully described in the schema (100% coverage, display-only label). The description adds no further detail about it, which is acceptable given the schema already carries the semantics — baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: begins the device-code 'User Claimed' auth flow for a Recipe Reels account. It immediately distinguishes itself from the polling sibling by noting the request is only pending until human approval, so an agent can tell it apart from check_agent_connection.
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 instructs what to do with the returned codes (show user_code/verification_uri to the human, prefer verification_uri_complete), and routes polling to check_agent_connection with an interval hint. It lacks an explicit 'do not call if already connected' exclusion, but the surrounding context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The connected account's own profile: its tier (user, subscriber or
admin), username (`display_name`), email, and the agents connected to it. Call this
right after connecting: the tools marked "requires Subscriber" fail
with an explanation for a user-tier account, so knowing the tier up
front saves a wasted call.
| Name | Required | Description | Default |
|---|---|---|---|
| session_token | No | The session token check_agent_connection returned for the connected account. Required, unless it's sent as an Authorization: Bearer header on the MCP request instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the structural annotations by explaining the real-world implication of the tool's output: knowing the user's tier dictates which subsequent calls will succeed or fail. This operational context provides significant behavioral value to the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly efficient, dedicating the first part to 'what it is' and the second part to 'why and when to use it.' The critical workflow guidance is front-loaded, making the text very scannable and impactful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations cover safety (read-only), the description is complete. It defines the input context (post-connection) and the expected structure of the output (user profile details). No crucial information needed for correct invocation is omitted.
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?
Since the schema provides 100% coverage, the description primarily serves as high-level documentation. It does not add unique semantic meaning (e.g., data types, specific formatting) beyond what the input schema already provides. This meets the baseline for a 100% coverage tool.
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 explicitly states that the tool returns the connected account's complete profile, including specific fields like tier, username, and email. It clearly defines the resource being retrieved (the connected account's data), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow guidance, instructing the user to call this tool immediately after connection. Furthermore, it explains the strategic benefit of this call—determining the user tier to preemptively avoid errors in other subscriber-restricted tools.
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_ai_meal_plan_to_grocery_listadd_meal_plan_to_grocery_listadd_recipe_to_grocery_listadd_recipe_to_meal_plancheck_agent_connectioncheck_notificationsclear_grocery_listcreate_ai_meal_plandelete_meal_plangenerate_ai_meal_planget_grocery_listget_meal_plan_detailsget_my_meal_planget_recipeimport_recipe_from_videokeep_meal_plan_entrylist_creatorslist_meal_plansremove_grocery_list_itemremove_recipe_from_grocery_listremove_recipe_from_meal_planremove_recipe_from_my_recipessave_recipe_to_my_recipessearch_recipesstart_agent_connectionwhoami
Add one secure layer between your agents and this server.