fitatu-api

Overview Schema Source Related Servers Discussions Admin

Search recipe ideas

search_recipes

Read-onlyIdempotent

Find Fitatu recipes by phrase, diet, meal, calories, protein and cooking time. Filter by per-portion limits to plan meals that match your daily targets.

Instructions

Search the Fitatu recipe catalog for meal ideas, e.g. phrase 'kurczak' with max_energy_kcal 500 for a chicken dinner of at most 500 kcal, or diets ['vegan'], meal 'breakfast' and max_cooking_time 10 for a quick vegan breakfast. The filters are per portion and all apply together; all but max_energy_kcal need Fitatu Premium (without it a forbidden error: tell the user, search by phrase and max_energy_kcal instead). Each hit is shaped like a search_food hit of type RECIPE (food_id, name, energy_kcal and measure of one portion) plus cooking_time and preparation_time as the catalog gives them, rating, and premium: whether the app keeps the recipe for Fitatu Premium (get_recipe and get_food_measures read it only with Premium). get_recipe gives a hit's ingredients and steps. Log one with add_food: food_type RECIPE, quantity the portions.

Input Schema

TableJSON Schema

Name	Required	Description
`meal`	No	Only recipes the catalog suggests for this meal type (dinner is obiad, supper kolacja).
`diets`	No	Diets every hit must fit, e.g. ['vegan', 'gluten_free'].
`limit`	No	Maximum number of hits.
`phrase`	No	Words to look for, e.g. 'kurczak' or 'sałatka'; omit it to browse.
`min_protein_g`	No	Only recipes with at least this many g of protein per portion.
`max_energy_kcal`	No	Only recipes of at most this many kcal per portion.
`max_cooking_time`	No	Only recipes with a cooking_time of at most 10 or 30 minutes, the catalog's two time filters.
`max_carbohydrate_g`	No	Only recipes with at most this many g of carbohydrate per portion.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes
`data`	No
`error`	No	describe_error() of what went wrong; docs/AGENTS.md, Results and errors.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 16, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantive behavior beyond them: Premium-only filters with a 'forbidden' error path, per-portion semantics, the exact hit payload, and the meaning of the `premium` flag including which tools it gates.

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?

A single dense paragraph that front-loads examples before constraints, and nearly every clause carries information. It is on the heavy side with multiple cross-tool references packed together, but not padded.

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 an 8-parameter optional-filter search with full schema coverage and an output schema, the description supplies everything else an agent needs: gating, error handling, filter interaction semantics, and follow-up tools.

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 100% so the baseline is 3, but the description adds real meaning: worked examples ('kurczak' with max_energy_kcal 500, diets ['vegan'] with meal 'breakfast'), the AND-together and per-portion semantics of the filters, and the note that max_cooking_time uses the catalog's two fixed time filters.

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 (search the Fitatu recipe catalog) and immediately scopes it with concrete examples using actual filter values. It distinguishes itself from the food-search sibling by framing hits as 'a search_food hit of type RECIPE', so an agent can separate the two without opening schemas.

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

Usage Guidelines4/5

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

Gives rich context: filters are per portion and AND together, Premium gating with a prescribed fallback ('tell the user, search by phrase and max_energy_kcal instead'), and routes to get_recipe for details and add_food for logging. It stops short of explicitly saying when to prefer search_food over this tool, so it isn't fully explicit on alternatives.

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