fitatu-api

by Jezue

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Log a food

add_food

Log a catalog food or recipe in a meal, with quantity and measure, and get a row ID for the entry.

Instructions

Log a catalog food in a meal; returns its row_id. food_id and food_type come from a search_food, search_recipes, find_by_barcode, get_recent_foods, get_favorite_foods or get_my_foods hit, create_food's food_id (PRODUCT) or create_recipe's recipe_id (RECIPE). For a PRODUCT give either unit 'g' or 'ml' with quantity in grams or millilitres, or measure_id (from the hit or get_food_measures) with quantity = how many of that measure. A RECIPE is logged in portions unless measure_id names another of its measures; unit is for products only. A premium recipe needs Fitatu Premium: without it a forbidden error. A measure_id the food does not have is refused before anything is written (that check reads the food once), and the error lists its measures. Each call adds a row unless row_id is reused. The row is not read back: data.ok says the sync accepted it, so read get_day to check what was logged. The result names the measure the row was stored in (measure_id, measure_name, measure_quantity): grams of a food without a gram measure are stored as a count of another one (70 g as 2 portions of 35 g), and update_item's quantity counts that measure.

Input Schema

TableJSON Schema

Name	Required	Description
`date`	Yes	Day as YYYY-MM-DD; when the user says today, yesterday, this week or a weekday, call get_today and count from its date.
`meal`	Yes	Meal slot. The keys are fixed, but users rename their meals in the app: match the user's words against get_day's meal_name and pass that meal's meal_key. Only the meals get_day lists exist.
`unit`	No	Products only: quantity is in g or ml.
`eaten`	No	true when the user ate or drank it or just asks to log it; false (the default) only when they plan ahead.
`row_id`	No	Optional UUID version 1 for the new row; omit it to get a new id. Repeating the add with the same row_id and values does not log a second row: when a failed add's error has a retry_row_id, repeat it with that row_id. Never a row_id from get_day: update_item changes a logged row's quantity and eaten; to change anything else, remove the row and add it again.
`food_id`	Yes	food_id of a search_food, search_recipes, find_by_barcode, get_recent_foods, get_favorite_foods or get_my_foods hit, create_food's food_id (PRODUCT), create_recipe's recipe_id (RECIPE), or a get_day row's product_id (PRODUCT) or recipe_id (RECIPE).
`quantity`	Yes	Grams or ml with unit, else how many of the measure.
`food_type`	Yes	type of that search hit, or the get_day row's food_type.
`measure_id`	No	measure_id of this food, from its search hit or get_food_measures.

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.9/5.0

Behavior5/5

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

Annotations only give the generic safety profile; the description supplies the non-obvious behaviors: premium recipes fail with a forbidden error, an unknown measure_id is refused before anything is written, each call adds a row unless row_id is reused, and the write is not read back (data.ok only means the sync accepted it). It also explains that grams may be stored as a count of another measure, a real data-model quirk.

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?

Every sentence carries load for a 9-parameter tool with tricky branching, and the return value leads. It is delivered as one dense block, however, with sourcing rules, product/recipe rules and verification steps interleaved, which makes it slower to scan than it needs to be.

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?

Despite an output schema existing, the description covers the gating (premium), the validation failure path, the retry path, and the post-write verification workflow. An agent has everything needed to call this correctly on the first try.

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

Parameters5/5

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

Schema coverage is 100%, so baseline is 3, but the description goes well beyond it: it explains the PRODUCT-vs-RECIPE branch for unit/measure_id/quantity, where food_id and food_type originate, and the retry_row_id/idempotency-key behavior of row_id. That is substantive semantic value the schema cannot express.

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+resource+effect: logs a catalog food into a meal and returns its row_id. It also implicitly distinguishes itself from add_custom_item (catalog food only) and from update_item (which changes a logged row). An agent can tell what it does 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.

Usage Guidelines5/5

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

Explicitly names the sibling tools that produce food_id/food_type (search_food, search_recipes, find_by_barcode, get_recent_foods, get_favorite_foods, get_my_foods, create_food, create_recipe) and get_food_measures for measure_id. It also routes the agent away from the tool when changing an existing row (use update_item; otherwise remove and re-add) and tells it to verify with get_day.

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