ask.recipes

Find recipes by ingredients on hand

find_by_ingredients

Read-onlyIdempotent

Find recipes that use ingredients the user already has: leftovers, a full fridge, an ingredient about to turn. Ranks by how many of those ingredients a recipe uses and how few extra ones it needs. The user's pantry counts as on hand too, so a recipe that only needs pantry staples on top of what was passed ranks as nearly complete; with no ingredients passed it cooks from the pantry alone, for "what can I make with what I have"; when the pantry is empty too, ask_user carries the question to put to the user. Takes the same diet, nutrition and exclude_ingredients filters as search_recipes. Each result links to its source. The user's profile, once saved with update_profile, excludes allergens and dislikes, keeps its diets on and supplies the default time budget; pass max_total_minutes=-1 to lift it. who names the people eating, by name or role, when not everyone is. check, present when the profile has allergens, says to read a recipe's ingredients with get_recipe before recommending it, because a product name can hide an excluded ingredient.

Input Schema

Name	Required	Description
`who`	No	who is eating, by the names or roles saved as people on the profile, e.g. ['Dad','Ana'] or ['adults'] when the kids are out, ['kids'] when only they eat; only those people's allergens and dislikes apply on top of the household's; leave empty for everyone
`limit`	No
`query`	No	optional free-text to narrow results, e.g. 'breakfast pancakes'
`vegan`	No	only vegan recipes: vegetarian and no eggs, dairy or honey
`feeding`	No	how many people are eating, e.g. 10 for a dinner party; from six up, dishes cooked in one vessel (stews, braises, tray bakes, casseroles, soups, roasts) rank ahead of dishes cooked per portion (steaks, burgers, pancakes, stir-fries); nothing is excluded
`nut_free`	No	only recipes without tree nuts or peanuts; coconut counts as nut-free
`max_fat_g`	No	maximum grams of fat per serving
`dairy_free`	No	only recipes without milk, butter, cheese, cream or yogurt
`min_rating`	No	only recipes rated at least this many stars, source ratings and ask.recipes stars averaged together; recipes nobody has rated yet and private uploads stay in; off unless passed
`vegetarian`	No	only vegetarian recipes: no meat, poultry, fish, seafood or gelatin in the ingredients
`gluten_free`	No	only recipes without wheat, barley, rye, oats or products made from them
`ingredients`	No	ingredients to cook with, e.g. ['oats','milk','eggs','skyr','berries']; leave empty to cook from the pantry alone
`max_carbs_g`	No	maximum grams of carbohydrates per serving
`max_sugar_g`	No	maximum grams of sugar per serving
`min_fiber_g`	No	minimum grams of fiber per serving
`min_reviews`	No	only recipes with at least this many ratings, source and ask.recipes together; recipes with no rating at all and private uploads stay in; off unless passed
`main_protein`	No	only recipes whose main protein is one of these: chicken, turkey, duck, goose, quail, pheasant, guinea_fowl, beef (with veal), pork (with ham, bacon and sausage), lamb (with mutton), goat, venison, bison, rabbit, fish, shrimp (with prawns), seafood (other shellfish, squid, octopus), egg, legume (beans, lentils, chickpeas, tofu), none; e.g. ['beef','pork','lamb'] for red meat or ['fish','shrimp','seafood']; judged from the ingredients, so chicken stock alone does not make a chicken dish
`max_calories`	No	only recipes with at most this many calories per serving, e.g. 300
`min_calories`	No	only recipes with at least this many calories per serving
`ignore_pantry`	No	true to match only the ingredients passed and not count the pantry, for 'using just these'
`min_protein_g`	No	minimum grams of protein per serving, e.g. 10
`batch_friendly`	No	true to leave out dishes cooked per portion, for a crowd; recipes not yet classified stay in
`max_total_minutes`	No
`exclude_ingredients`	No	ingredients to leave out for this search, whole-word match on the ingredient list, e.g. ['chicken','brussels sprouts'] to avoid repeating what the week already has; nuts, gluten and dairy as a word apply the matching diet filter; the profile's allergens and dislikes stay excluded on top

Output Schema

Name	Required	Description	Default
`check`	No
`matches`	Yes
`ask_user`	No
`from_pantry`	No
`ingredients`	Yes
`pantry_ingredients`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 2, 2026

changedInput schema / properties / main_protein / description

Previous value: -"only recipes whose main protein is one of these: chicken, turkey, duck, goose, quail, pheasant, guinea_fowl, beef (with veal), pork (with ham, bacon and sausage), lamb (with mutton), goat, venison, bison, rabbit, fish, seafood (shellfish, squid, octopus), egg, legume (beans, lentils, chickpeas, tofu), none; e.g. ['beef','pork','lamb'] for red meat or ['fish','seafood']; judged from the ingredients, so chicken stock alone does not make a chicken dish"New value: +"only recipes whose main protein is one of these: chicken, turkey, duck, goose, quail, pheasant, guinea_fowl, beef (with veal), pork (with ham, bacon and sausage), lamb (with mutton), goat, venison, bison, rabbit, fish, shrimp (with prawns), seafood (other shellfish, squid, octopus), egg, legume (beans, lentils, chickpeas, tofu), none; e.g. ['beef','pork','lamb'] for red meat or ['fish','shrimp','seafood']; judged from the ingredients, so chicken stock alone does not make a chicken dish"

Changed2 schema fields changedOct 31, 2026

changedInput schema / properties / min_rating / description

Previous value: -"only recipes rated at least this many stars, source ratings and ask.recipes stars averaged together; off unless passed"New value: +"only recipes rated at least this many stars, source ratings and ask.recipes stars averaged together; recipes nobody has rated yet and private uploads stay in; off unless passed"

changedInput schema / properties / min_reviews / description

Previous value: -"only recipes with at least this many ratings, source and ask.recipes together; off unless passed"New value: +"only recipes with at least this many ratings, source and ask.recipes together; recipes with no rating at all and private uploads stay in; off unless passed"

Changed1 schema field changedOct 31, 2026
- addedOutput schema / properties / check
```
Added value: +{
+  "type": "string"
+}
```

Changed1 schema field changedOct 29, 2026

addedInput schema / properties / who

Added value: +{
+  "description": "who is eating, by the names or roles saved as people on the profile, e.g. ['Dad','Ana'] or ['adults'] when the kids are out, ['kids'] when only they eat; only those people's allergens and dislikes apply on top of the household's; leave empty for everyone",
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

Changed4 schema fields changedOct 29, 2026

changedInput schema / properties / min_rating / description

Previous value: -"only recipes the source rates at least this many stars; off unless passed"New value: +"only recipes rated at least this many stars, source ratings and ask.recipes stars averaged together; off unless passed"

changedInput schema / properties / min_reviews / description

Previous value: -"only recipes with at least this many source ratings; off unless passed"New value: +"only recipes with at least this many ratings, source and ask.recipes together; off unless passed"

addedOutput schema / properties / matches / items / properties / askrecipes_ratings
```
Added value: +{
+  "type": "integer"
+}
```

addedOutput schema / properties / matches / items / properties / my_rating

Added value: +{
+  "properties": {
+    "note": {
+      "type": "string"
+    },
+    "stars": {
+      "type": "integer"
+    }
+  },
+  "required": [
+    "stars"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

Changed2 schema fields changedOct 25, 2026

addedInput schema / properties / main_protein

Added value: +{
+  "description": "only recipes whose main protein is one of these: chicken, turkey, duck, goose, quail, pheasant, guinea_fowl, beef (with veal), pork (with ham, bacon and sausage), lamb (with mutton), goat, venison, bison, rabbit, fish, seafood (shellfish, squid, octopus), egg, legume (beans, lentils, chickpeas, tofu), none; e.g. ['beef','pork','lamb'] for red meat or ['fish','seafood']; judged from the ingredients, so chicken stock alone does not make a chicken dish",
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / matches / items / properties / main_protein
```
Added value: +{
+  "type": "string"
+}
```

Changed1 schema field changedOct 25, 2026
- addedOutput schema / properties / ask_user
```
Added value: +{
+  "type": "string"
+}
```
Changed2 schema fields changedOct 25, 2026
- removedOutput schema / additionalProperties
```
Removed value: -false
```
- removedOutput schema / properties / matches / items / additionalProperties
```
Removed value: -false
```

Changed3 schema fields changedOct 24, 2026

addedInput schema / properties / batch_friendly

Added value: +{
+  "description": "true to leave out dishes cooked per portion, for a crowd; recipes not yet classified stay in",
+  "type": "boolean"
+}

addedInput schema / properties / feeding

Added value: +{
+  "description": "how many people are eating, e.g. 10 for a dinner party; from six up, dishes cooked in one vessel (stews, braises, tray bakes, casseroles, soups, roasts) rank ahead of dishes cooked per portion (steaks, burgers, pancakes, stir-fries); nothing is excluded",
+  "type": "integer"
+}

addedOutput schema / properties / matches / items / properties / scale_class
```
Added value: +{
+  "type": "string"
+}
```

Changed9 schema fields changedOct 20, 2026

addedInput schema / properties / exclude_ingredients

Added value: +{
+  "description": "ingredients to leave out for this search, whole-word match on the ingredient list, e.g. ['chicken','brussels sprouts'] to avoid repeating what the week already has; nuts, gluten and dairy as a word apply the matching diet filter; the profile's allergens and dislikes stay excluded on top",
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedInput schema / properties / ignore_pantry

Added value: +{
+  "description": "true to match only the ingredients passed and not count the pantry, for 'using just these'",
+  "type": "boolean"
+}

changedInput schema / properties / ingredients / description

Previous value: -"ingredients on hand, e.g. ['oats','milk','eggs','skyr','berries']"New value: +"ingredients to cook with, e.g. ['oats','milk','eggs','skyr','berries']; leave empty to cook from the pantry alone"

removedInput schema / required
```
Removed value: -[
-  "ingredients"
-]
```
addedOutput schema / properties / from_pantry
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / ingredients

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / matches / items / properties / matched_requested
```
Added value: +{
+  "type": "integer"
+}
```

addedOutput schema / properties / pantry_ingredients

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "matches"
-]New value: +[
+  "matches",
+  "ingredients"
+]

Changed8 schema fields changedOct 19, 2026

addedInput schema / properties / dairy_free

Added value: +{
+  "description": "only recipes without milk, butter, cheese, cream or yogurt",
+  "type": "boolean"
+}

addedInput schema / properties / gluten_free

Added value: +{
+  "description": "only recipes without wheat, barley, rye, oats or products made from them",
+  "type": "boolean"
+}

changedInput schema / properties / min_rating / description

Previous value: -"minimum source star rating, default 4.2"New value: +"only recipes the source rates at least this many stars; off unless passed"

changedInput schema / properties / min_reviews / description

Previous value: -"minimum number of source ratings, default 25"New value: +"only recipes with at least this many source ratings; off unless passed"

addedInput schema / properties / nut_free

Added value: +{
+  "description": "only recipes without tree nuts or peanuts; coconut counts as nut-free",
+  "type": "boolean"
+}

addedInput schema / properties / vegan

Added value: +{
+  "description": "only vegan recipes: vegetarian and no eggs, dairy or honey",
+  "type": "boolean"
+}

addedInput schema / properties / vegetarian

Added value: +{
+  "description": "only vegetarian recipes: no meat, poultry, fish, seafood or gelatin in the ingredients",
+  "type": "boolean"
+}

addedOutput schema / properties / matches / items / properties / diets

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

Changed2 schema fields changedOct 18, 2026
- addedOutput schema / properties / matches / items / properties / nutrition_for
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / matches / items / properties / servings
```
Added value: +{
+  "type": [
+    "null",
+    "integer"
+  ]
+}
```
First observedOct 15, 2026

TDQS

A4.8/5.0

Behavior5/5

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

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

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

Conciseness4/5

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

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

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

Completeness5/5

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

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

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

Parameters4/5

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

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

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

Purpose5/5

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

States a specific verb and resource ('Find recipes that use ingredients the user already has') and immediately explains the ranking logic, which is what makes this tool distinct from search_recipes. An agent can tell this apart from search_recipes and from get_pantry without opening any schema.

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

Usage Guidelines5/5

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

Explicitly covers the scenarios that select this tool: leftovers/full fridge/about-to-turn ingredient, pantry-only cooking with no ingredients passed, and the degraded case where the pantry is also empty and ask_user should carry the question. It also names the sibling it shares filters with ('takes the same diet, nutrition and exclude_ingredients filters as search_recipes') and the downstream verification step (get_recipe).

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

All ask.recipes tools Inspect

Try in Browser

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Find recipes by ingredients on hand

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources