Skip to main content
Glama
jaronskijakub

fatsecret-mcp

by jaronskijakub
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

draft_entries

Read-only

Create a reviewable draft of new food entries or edits and removals to logged entries without writing to the Food Diary, so users can confirm changes first.

Instructions

Propose new Food Entries, and changes to logged ones, without writing to the Food Diary.

Show the Draft to the User.

A Food item uses Food and Serving ids from search_foods. number_of_units is the FatSecret unit count, not necessarily grams: scale it from the Serving's number_of_units. Name it with food_entry_name the way the User said it, in their language, followed by a short note in the same language that it was matched in the US catalog, e.g. "Kajzerka (katalog USA)" or "Kaiser roll (US catalog)". The Draft shows the catalog's name beside it. A Serving of known weight, such as "1 roll (57 g)", is logged as that weight in the Food's Serving in grams or ml when it has one, so the Draft may show that Serving instead.

A Nutrition Label item logs a branded product missing from the catalog as a Stand-in: the closest catalog Food for search_phrase, in the amount whose kcal match the label, under the product's name. Ask for a photo of the Nutrition Label unless the User already gave its values. For a product logged before as a Stand-in, reuse its label from this conversation or your memory, and ask again otherwise. Estimate the label, with estimated=true, only when the User has no packaging. Show the label values, the logged values and the difference. If the User dislikes the Stand-in, draft again with a different search_phrase.

A Diary Entry item logs a Food Entry from the Food Diary again, under its own name, with its Food, Serving and nutrition, so no catalog search is needed. For "the same as yesterday's breakfast", read that Diary Day with get_diary_day, list its Food Entries with their amounts to the User and ask whether everything was the same, or what to leave out or eat more or less of. Then draft the chosen entries by diary_day and food_entry_id, with metric_amount for a changed amount in grams or ml.

A change item changes or removes a Food Entry already in the Food Diary, by diary_day and food_entry_id: change="remove", or change="edit" with a new metric_amount in grams or ml, a meal on the same Diary Day or a food_entry_name. For "undo that" after a confirm_draft, remove the food_entry_ids it returned; undoing a change is a change back. For any other change, read the Diary Day with get_diary_day first, name the entries to change, and ask when it's unclear which one is meant. The Food or Diary Day of an entry can't change: for "chicken thigh, not breast", remove the entry and add a Food item; for "that was yesterday", remove it and add a Diary Entry item with the same food_entry_id, in one Draft whose diary_day is yesterday. Show each change before and after, and the removal_note when there is one.

A Draft holds at most 20 items: split a larger meal into several Drafts.

Include assumptions about estimated amounts. When the Draft has new items, always ask the User whether the suggested Meal is correct. If previous_day_suggested is true, ask whether to use Snacks on the previous Diary Day instead. meal and diary_day are for new items only. A correction needs a new Draft with the explicit Meal or Diary Day. Nothing is written by this tool; a Draft expires after thirty minutes.

Input Schema

NameRequiredDescriptionDefault
mealNo
itemsYesAt most 20 items. Split a larger meal into several Drafts.
diary_dayNoThe Diary Day, as YYYY-MM-DD. Omit for today in the User's timezone.

Output Schema

NameRequiredDescriptionDefault
mealYesThe Meal of the new items; null when the Draft only has changes.
itemsYesNew Food Entries.
totalsYesThe new items added up.
changesYesChanges to Food Entries, each before and after.
draft_idYes
day_afterYesThe new items' Diary Day after the whole Draft; null when the Draft only has changes.
diary_dayYesThe Diary Day of the new items; null when the Draft only has changes.
expires_atYes
attributionNoPowered by fatsecret Platform API
removal_noteYesSet when the Draft removes a Food Entry; tell the User.
meal_suggestedYes
other_days_afterYesEach other Diary Day the changes are on, after the whole Draft.
previous_day_suggestedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.0

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the readOnlyHint annotation, the description discloses key behavior: no Food Diary writes occur, drafts expire after thirty minutes, each Draft holds at most 20 items, meal confirmation is required for new items, and assumptions must be included. It also explains nuanced handling for Stand-ins, label reuse, estimation, immutable Food/Diary Day fields, and undo behavior.

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?

The description is front-loaded, grouped by item type, and dense with necessary workflow rules for a complex drafting tool. It is long and repeats the 20-item limit already stated in the schema, but most sentences carry operational value rather than filler.

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?

Given the nested oneOf item schema, 67% schema description coverage, and an output schema, the description supplies the missing procedural and behavioral context an agent needs: source of ids, label handling, stand-in matching, change/undo rules, meal confirmation, assumptions, and draft expiry. Nothing critical appears omitted.

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?

The description adds substantial meaning beyond the 67%-covered schema: number_of_units is a FatSecret unit count rather than grams, food_entry_name must follow the User's language plus a catalog-matched note, diary_day and food_entry_id come from get_diary_day or confirm_draft, metric_amount is grams or ml, and change remove/edit have specific consequences. It also clarifies that meal and diary_day apply only to new items and that estimated=true is used only when packaging is unavailable.

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?

The opening sentence gives a specific verb and resource: 'Propose new Food Entries, and changes to logged ones, without writing to the Food Diary.' It distinguishes the tool from siblings by stating that ids come from search_foods, diary reads use get_diary_day, and confirm_draft is the later commit step.

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?

The description explicitly routes each item type: Food items use search_foods ids, Diary Entry items use get_diary_day results, and change items require reading the Diary Day first unless undoing a confirm_draft. It also states when to ask the User for clarification, a Nutrition Label photo, or a corrected Draft.

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

Deploy Server

Other Tools