fitatu-api

Overview Schema Source Related Servers Discussions Admin

Log several foods

add_foods

Log multiple catalog foods in one meal with a single write, e.g. a whole breakfast. Validates every item before saving, so if one is wrong nothing is logged.

Instructions

Log several catalog foods in one meal with one write, e.g. a whole breakfast. Each item takes food_id, food_type, quantity and measure_id or unit as add_food does, and is checked the same way before anything is written (one read per item with measure_id or unit): when one is wrong, nothing is logged and the error names it as items[index]. Returns the rows (row_id, food_id, measure_id, measure_name, measure_quantity) in the order of items; they are not read back, data.ok says the sync accepted them. Each call adds rows unless row_id is reused.

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.
`eaten`	No	Sets every row: true (the default) when the user ate them or just asks to log them; false only when they plan ahead.
`items`	Yes	The foods, each as add_food takes it.
`row_id`	No	Optional UUID version 1 the rows' row_ids are derived from; omit it to get a new one. Repeating the add with the same row_id and arguments writes the same rows again instead of new ones: when a failed add's error has a retry_row_id, repeat it with that row_id. Never a row_id from get_day.

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 only carry the safety/idempotency flags; the description adds substantial behavior beyond them: all-or-nothing validation ('when one is wrong, nothing is logged'), one read per item, error naming as items[index], the exact return fields and ordering, that rows are not read back and data.ok is the success signal, and that repeats append unless row_id is reused. This is unusually rich disclosure for a write tool.

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?

Single dense paragraph, front-loaded with purpose before mechanics, and every clause carries information (atomicity, error format, return, idempotency). The parenthetical about 'one read per item' is slightly cluttered but not wasteful enough to drop the score.

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?

With an output schema present, annotations covering safety, and 100% schema coverage, the description still supplies what the structured fields cannot: atomicity, error indexing, sync semantics, and idempotency via row_id. Nothing needed to call this correctly is missing.

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 value by declaring the item shape must match add_food, explaining that items validate atomically and report errors by items[index], and clarifying row_id as a reuse/idempotency key. It reinforces rather than merely restates the schema.

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?

Specific verb (Log), specific resource (catalog foods), and explicit scope: several items in one meal with one write. It distinguishes itself from the sibling add_food by framing itself as the batch form ('as add_food does'), so an agent can route without reading both 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?

The example ('a whole breakfast') and the repeated 'as add_food does' framing make it clear this is for multi-item logging, with add_food implied for singles. It stops short of an explicit rule like 'use add_food instead when logging one item,' so it is clear context but not a full when/when-not statement.

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