fitatu-api

Overview Schema Source Related Servers Discussions Admin

Log a custom food

add_custom_item

Log a food missing from the catalog by name and nutrition for the whole amount eaten; returns its row_id. Estimate protein, fat and carbs when only kcal is given.

Instructions

Log a food that is not in the catalog, by name and the nutrition of the whole amount eaten; returns its row_id. Each call adds a row unless row_id is reused. When the user gives only kcal, estimate protein_g, fat_g and carbohydrate_g for that food and tell the user they are estimates; an omitted one counts as 0 g.

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.
`name`	Yes	What it was, e.g. 'Kanapka z serem'.
`eaten`	No	true when the user ate or drank it or just asks to log it; false (the default) only when they plan ahead.
`fat_g`	No	Fat in grams.
`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.
`protein_g`	No	Protein in grams.
`energy_kcal`	Yes	Energy in kcal.
`carbohydrate_g`	No	Carbohydrate in grams.

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

Behavior4/5

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

Annotations cover the safety profile (write, non-destructive, not idempotent), and the description adds the row-append behavior plus the keyed-retry nuance ('Each call adds a row unless row_id is reused') and the estimation duty that no structured field conveys. Return values are also handled by the output schema, so this is solid added context rather than duplication.

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

Conciseness5/5

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

Three tight sentences, front-loaded with purpose, then the append/idempotency rule, then the estimation edge case. No filler, and each clause carries actionable information.

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

Completeness4/5

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

For a 9-parameter write tool with full schema documentation, annotations and an output schema, the description covers purpose, the row_id idempotency rule and the estimation fallback adequately. Only peripheral details (e.g., what occurs if row_id collides with another row) are unaddressed.

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 semantic meaning: the nutrition figures are for 'the whole amount eaten' rather than per unit, and an omitted macro explicitly counts as 0 g. That resolves an ambiguity the schema's 'Fat in grams' wording leaves open.

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 ('Log a food that is not in the catalog') and immediately scopes it against the catalog-based add_food/add_foods siblings. It also names the return value ('returns its row_id'), so an agent knows both what it does and what it gets back.

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 trigger condition is explicit — use this when the food is not in the catalog — which implicitly routes catalog foods to add_food, and it gives concrete guidance for the kcal-only case. It stops short of naming the alternative tools outright.

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