The five-star chef calorie tracker: meals that fill you up, logged in one sentence.
Scored across 14 tools
Most tools have clearly distinct purposes: day_summary vs period_summary are separated by single-day vs multi-day scope, get_meal vs day_summary by storage-level vs drawn report, and undo_last_change vs restore_last_change are explicit inverses. The only mild friction is the onboarding cluster (get_connected_account, get_setup_step, get_profile) and the many boundary rules the descriptions must spell out to prevent misselection.
The set predominantly follows a consistent verb_noun pattern (get_meal, update_meal, delete_meal, log_meal, find_recipes, get_recipe, restore_last_change, undo_last_change, update_profile). The only deviations are the noun-first day_summary and period_summary, which are still readable and thematically paired.
At 14 tools the surface is well-scoped for a nutrition-logging, recipe and profile domain, with each tool mapping to a distinct lifecycle action or read. No obviously redundant tools pad the set.
Full lifecycle is covered: log_meal (create), get_meal/day_summary/period_summary (read), update_meal (update), delete_meal (delete), plus undo/restore and profile/onboarding management and recipe discovery. Minor gaps exist, such as no way to browse target history or review archived/deleted meals that are kept in private history.
Returns the daily summary: everything recorded for one date — each meal with its items (quantity, calories, macros, source per item), the day's totals, the target in force that day, and the signed difference (target − total) per nutrient. Use it for any single day — today's summary, yesterday's, one date: when the customer asks for their daily summary, their day, their balance for the day, what they ate, where they stand, or how much is left. Omit date for today; otherwise pass their word (yesterday, 3 days ago, Tuesday) or YYYY-MM-DD only when they said the full date — never compute one yourself. Reads one day only. For several days or a period ('last four weeks', 'this month', 'day by day'), use period_summary. Totals are computed from recorded meals. Each meal says whether its values came from a label, the customer, or an estimate; only llm_estimate is estimated. Relay over and under neutrally. When interactive reports are enabled for the account, the result is accompanied by a complete IZeat day component containing totals, macros, every meal and its items. Text-only clients receive the same typed nutrition data. A narrow question does not require the complete report unless the customer requests it. Returns a typed public day report without storage identifiers. Example: day_summary { "date": "2026-09-03" }. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Omit for today. Otherwise the customer's own word — yesterday, 3 days ago, a weekday — or YYYY-MM-DD only when they said the full date |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish a safe read (readOnlyHint true, destructiveHint false, openWorldHint false), and the description adds real behavioral context on top: totals are computed from recorded meals, per-item source attribution where only llm_estimate is estimated, a neutrality instruction for over/under, and the interactive-component vs text-only rendering difference. No contradictions with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded and mostly information-dense (purpose, date handling, alternative, behavior), but the closing paragraph about 'statement' being the customer-facing IZeat message — including write-operation behavior — is generic boilerplate unrelated to this read-only, one-param tool and does not earn its place. The surrounding verbosity is tolerable but not tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, yet the description still signals the report is typed and free of storage identifiers. Combined with full annotation coverage and complete parameter documentation, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single date param is already documented there. The description reinforces the accepted formats and adds a rule not in the schema — 'never compute one yourself' — telling the agent to pass the customer's own wording rather than derive a date, which materially reduces malformed calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource — 'Returns the daily summary: everything recorded for one date' — and then enumerates the exact payload (meals+items with macros/source, day totals, target in force, signed per-nutrient difference). It explicitly differentiates itself from the period_summary sibling for multi-day requests, so the agent can pick it without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit trigger phrases ('daily summary', 'their day', 'how much is left'), the today-case (omit date), and the named alternative for multi-day/period requests ('use period_summary'). It also adds a conditional rule — 'A narrow question does not require the complete report unless the customer requests it' — which is genuine when/how guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes one specific recorded meal, identified by the customer's local date and meal type, even when it was not the latest change. Always use two steps. First call without confirm to review the exact meal, changing nothing. After the customer explicitly confirms, call again with confirm true within ten minutes. Nothing else is needed: IZeat remembers what it showed. There is no age limit. The meal remains in IZeat's private history but no longer counts in the active day. Use undo_last_change instead when the customer simply asks to undo the latest action. Example: "Delete yesterday's dinner" → review that dated dinner, ask for confirmation, then delete it. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | The customer's day as they said it — today, yesterday, 3 days ago, a weekday — or YYYY-MM-DD of the meal | |
| confirm | No | true only after the customer confirmed the reviewed meal | |
| meal_type | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With destructiveHint=true and idempotentHint=true already declared, the description adds substantive context beyond annotations: a required review-then-confirm two-step flow, the 10-minute confirm window, server-side state retention ('IZeat remembers what it showed'), and the post-condition that the meal stays in private history but stops counting in the active day.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core procedure is front-loaded and tight, but the second paragraph drifts into output/statement handling that the output schema already covers, and it trails into unrelated context ('Account: Sam (review@izeat.app)'). Several sentences do not earn their place in a deletion tool definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, stateful mutation with a required confirmation loop, the description covers prerequisites, the exact call sequence, timing constraints, and side effects on the day's data. An output schema exists, so the description is not obligated to explain return values, and its remaining coverage gaps are nil.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, and the description strengthens the weakest parameter by defining confirm's exact role ('call again with confirm true within ten minutes') and how date is interpreted (customer's local day, relative or YYYY-MM-DD). The meal_type enum values are left entirely to the schema, but their semantics are self-evident.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('deletes one specific recorded meal'), the identifying keys (local date and meal type), and explicitly distinguishes scope from the sibling undo_last_change ('even when it was not the latest change'). An agent can select this over undo_last_change without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use-this and when-to-use-the-alternative rule ('Use undo_last_change instead when the customer simply asks to undo the latest action'), plus the mandatory two-step procedure and the ten-minute confirmation window. Nothing about invocation timing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns up to three recipes per time band from the IZeat catalogue that fit what is left of the customer's day, each served at the customer's usual plate for that meal. Use it only when the customer asks what they could eat or cook, or wants a recipe idea for a meal. Never call it to tell them what they should eat. Each new request for ideas is a new call, even later in the same conversation: what is left changes as the day goes on, and the card is where the customer chooses. meal_type is required: breakfast, morning_snack, lunch, afternoon_snack, dinner or evening; ask if it is unclear. The plate is the customer's usual weight for that meal, which IZeat reads from their last weighed meals of the same type. With too few, pass sex if the customer already said it in this conversation (never ask only for this, never guess it) and IZeat uses a provisional default for breakfast, lunch and dinner; otherwise it asks you for plate_g: ask the customer roughly how much they usually eat at that meal and convert it to grams. A plate that would hold more than what is left is made smaller and says so. kcal_for_meal only when the customer gave their own figure for this meal ('I have 600 kcal for dinner'); otherwise what is left of the day is the limit. query only with the customer's own words: an ingredient, 'vegetarian'. ready_within only when the customer said how long they have until they eat ('I have 20 minutes'). Omit date for today, as on day_summary. The recipes come by total time, until the plate is served: up to three ready in 20 minutes, three in 40, three that take longer; each also says its active time, the minutes with hands in the recipe. For lunch and dinner, up to three desserts come too, at one serving each, and each dish says its smaller plate beside each dessert, so dish and dessert together make the usual plate. The choice weighs what is left in protein, carbohydrate and fat: far from the protein target, the protein-rich dishes come first; close to it, lighter ones. Equal fits are ordered by the IZeat score (0 to 100, how well a dish keeps hunger away for two to three hours, per calorie). Each recipe comes with its plate in grams and its figures, its times, the ingredients scaled to that plate, its creator and its page. These are options, never a prescription: relay them neutrally and never comment on how much. Records a view for every proposed recipe, at most once per account, recipe and UTC day; a proposal is not a recipe use and does not earn creator royalties. When interactive cards are enabled for the account, the recipes also appear as an IZeat card with their photos, figures and ingredients; text-only clients receive the same data. When the customer chooses one to cook, call get_recipe with its reference and plate for the whole method. If the customer cooks one, log what they actually cooked and ate with log_meal, with their own quantities and changes, and pass its reference in log_meal recipes. Saying they will cook a recipe is not a meal: log nothing until they say what they ate. Example: find_recipes { "meal_type": "dinner" }. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
| sex | No | Only when the customer already said it in this conversation; never asked for this, never stored | |
| date | No | Omit for today. Otherwise the customer's own word, or YYYY-MM-DD only when they said the full date | |
| query | No | Only the customer's own words: an ingredient, a diet | |
| plate_g | No | Only when IZeat asks for it: the customer's usual weight for this meal, in grams | |
| meal_type | Yes | ||
| ready_within | No | Only when the customer said it: the minutes they have until they eat | |
| kcal_for_meal | No | Only the customer's own calorie figure for this meal |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations say readOnlyHint=false and the description explains exactly why: a view is recorded for every proposed recipe, at most once per account/recipe/UTC day, and proposals do not earn royalties. It also discloses provisional plate defaults, plate shrinking when over budget, card vs text-only delivery, and ordering rules — behavioral context well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded and well ordered, but the volume is very high for a single tool definition — ordering heuristics, dessert pairing, plate-shrinking, royalty semantics and an example all compete for attention. The trailing paragraph about 'statement' being a customer-facing IZeat message is generic server-wide boilerplate that does not earn its place in this tool's definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter, non-idempotent tool with an output schema, the description covers everything an agent needs: required meal_type, conditional plate resolution, filtering constraints, return composition, and the follow-up tool chain. Return structure is delegated to the output schema, which is correct.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 86%, so the schema already documents most parameters; the description still adds meaningful semantics: plate_g is only passed when IZeat asks for it (otherwise ask the customer and convert to grams), sex may never be prompted, kcal_for_meal only applies when the customer gave their own figure, query must be the customer's own words, and date is omitted for today. The only gap is that meal_type's enum values are restated rather than enriched with per-meal behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource with scope: 'Returns up to three recipes per time band from the IZeat catalogue that fit what is left of the customer's day.' It also differentiates from siblings by name, routing cooking to get_recipe and logging to log_meal, so an agent can distinguish this from get_recipe/get_meal without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use ('only when the customer asks what they could eat or cook'), explicit when-not ('Never call it to tell them what they should eat'), and explicit alternatives with conditions (get_recipe with reference and plate when they choose to cook; log_meal only once they say what they ate). It even clarifies that saying they will cook is not a meal and that repeated idea requests are new calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verifies the IZeat account connected to this conversation and reports its onboarding state. Call it once before the first IZeat operation in a conversation, not before every meal. It never changes the account. Briefly reassure the customer which account is connected on that first IZeat reply. If onboarding is incomplete, use get_setup_step to determine the next step. The reply names today's date in the account's time zone: use it, never your own sense of the date. If no time zone is known, ask the customer which city they live in and store it with update_profile timezone before recording anything for 'today'. Example: get_connected_account {} → "IZeat is connected to Sam Lee (sam@example.com)." statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world scope, and the description reinforces that with 'It never changes the account'. Beyond that it adds non-annotation behavior: it returns the account's time zone and today's date, which the agent is told to trust over its own date sense, and it drives the 'IZeat ·' prefixed customer-facing statement. The trailing 'statement is the customer-facing IZeat message...' fragment is vague, but the time-zone/date directive is genuinely useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the call-frequency rule are front-loaded, which is good, but the block then piles on response-formatting, time-zone, and profile-update instructions, and the trailing sentences ('statement is the customer-facing IZeat message...' and 'Account: Sam (review@izeat.app)') read as misplaced template/state text that obscures rather than informs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be restated, and annotations cover the safety profile; the description adds the usage cadence, the sibling hand-off, and the time-zone caveat that an agent needs to use the result correctly. The only shortfall is the garbled closing fragment, which leaves the response 'statement' contract less clear than it should be.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the baseline an empty description of inputs is expected and the schema has nothing to enumerate. The description correctly implies a no-argument call, shown by the example 'get_connected_account {}'; there is no parameter meaning to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Verifies the IZeat account connected to this conversation and reports its onboarding state.' It also differentiates itself from the nearby inspection tool by routing incomplete-onboarding cases to get_setup_step, so an agent can place it against get_profile and get_setup_step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger ('once before the first IZeat operation in a conversation'), an explicit anti-trigger ('not before every meal'), and named alternatives ('use get_setup_step to determine the next step', 'store it with update_profile timezone'). This is close to a complete decision procedure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one recorded meal exactly as it is stored: its rows in order (position, description, quantity, calories, macros, source), the meal's totals, and whether it was already corrected. Use it before update_meal action 'revise', to copy the untouched rows exactly, and whenever the customer asks what one meal contains. It draws nothing: for the whole day with its card, use day_summary instead. Identify the meal by its meal type and day — omit date for today, otherwise pass the customer's word (yesterday, 3 days ago, Tuesday) or YYYY-MM-DD only when they said the full date; never compute one yourself. When no meal of that type is recorded that day, the reply says so and names the meal types that day does have, so ask the customer which one they mean rather than reading the day again. Returns typed public meal facts without storage identifiers. Example: get_meal { "meal_type": "lunch" } for today's lunch; get_meal { "date": "yesterday", "meal_type": "dinner" }. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Omit for today. Otherwise the customer's own word — yesterday, 3 days ago, a weekday — or YYYY-MM-DD only when they said the full date | |
| meal_type | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld=false/destructive=false, and the description adds substantial context on top: the exact stored representation returned, the correction flag, that storage identifiers are stripped, and the specific degraded behavior when no meal of that type exists (reply names the meal types that day does have). This goes well beyond the safety profile the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core is front-loaded: identity, returned contents, the day_summary alternative, and the date idiom all land in the first half. The trailing 'statement is the customer-facing IZeat message... For write operations' paragraph is generic boilerplate that does no work for a read-only tool whose output schema already exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return structure need not be re-explained, and the description still covers the pieces an agent needs: failure mode when no meal matches, date-input semantics, the alternative for whole-day reads, and the copy-before-revise workflow. Nothing required to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% — date is documented in the schema but meal_type carries only an enum. The description compensates by teaching the intended date idiom (omit for today; pass the customer's own word; YYYY-MM-DD only for a fully stated date; never compute one yourself), which is meaningfully richer than the schema text. It says little about what distinguishes the six meal_type values, but that is a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (returns one recorded meal) and enumerates exactly what comes back — ordered rows with named fields, meal totals, and the already-corrected flag. It explicitly contrasts itself with the sibling day_summary, so an agent can separate the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use triggers (before update_meal action 'revise' to copy untouched rows; whenever the customer asks what one meal contains) and an explicit when-not (use day_summary for the whole day). It even prescribes next-step handling when no matching meal is recorded, telling the agent to ask the customer rather than re-read the day.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the customer's name and the target in force on a date (the latest target set on or before it). Use it when the customer asks directly about their profile or target. day_summary already includes the target for a day, so do not call both for a day comparison. Pass date (The customer's day as they said it — today, yesterday, 3 days ago, a weekday — or YYYY-MM-DD) to get that day's target; omit it for the latest one. Returns { first_name, last_name, target: { valid_from, kcal, protein_g, carb_g, fat_g } | null, target_history_count }. Example: get_profile { "date": "2026-09-03" } → target 2000 kcal since 2026-09-01 → tell them in one line. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | The customer's day as they said it — today, yesterday, 3 days ago, a weekday — or YYYY-MM-DD. Omit for the latest target. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful context: the exact return shape, the possibility of target being null, the date-default semantics, and a worked example of the call and response. The trailing paragraph about the customer-facing 'statement' field is somewhat ambiguous and doesn't map to any parameter, slightly muddying the disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core guidance is well front-loaded and efficient, but the tail contains an off-topic paragraph describing a 'statement' message format that corresponds to no parameter, plus an 'Account: Sam (review@izeat.app)' line. Those lines dilute an otherwise tight definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only tool with an output schema, the description supplies what an agent needs: purpose, when to use, when not to, default behavior, and an invocation example. It is close to complete, held back only by the confusing statement paragraph.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a single parameter at 100% schema description coverage, the schema already documents the date format and the 'omit for latest' default. The description restates this and adds an example, but contributes no new meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource and precisely states the scope: it returns the customer's name and the target in force on a given date (latest target set on or before it). It also distinguishes itself from sibling day_summary, so an agent can tell them apart 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states explicit when-to-use ('when the customer asks directly about their profile or target') and when-not ('day_summary already includes the target for a day, so do not call both for a day comparison'), naming the alternative sibling. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one IZeat catalogue recipe in full, to cook it with the customer: the ingredients scaled to their plate, the seasonings and the whole method. The ingredients are scaled to the customer's plate, but steps are the original method for the whole recipe: quantities written inside them are not scaled. Make this distinction clear; use the scaled ingredient list for plate quantities and do not present whole-recipe quantities as plate quantities. Use it when the customer chooses a recipe from find_recipes to cook, or asks for the method of an IZeat recipe. recipe is the reference find_recipes gave; plate_g the plate it showed, unless the customer wants another size. Call it for each new explicit request for a complete recipe, even if that recipe appeared earlier in the conversation. Show it with your own recipe view when your app has one (the ingredients, then the steps, with its step-by-step cooking mode), one serving being this plate and every quantity the one IZeat gives; otherwise list the ingredients and guide them through the method one step at a time, waiting for them before the next step. Answer their questions about the dish. Log nothing while they cook. A successful request for the complete method records one recipe use, at most once per account, recipe and UTC day. Eligible uses determine creator royalties; a later meal log does not count another use. Requesting the method does not prove that the customer cooked or ate it. When they have eaten, ask what they actually ate and how much, then log it with log_meal, with their own quantities and changes, and pass this recipe's reference in log_meal recipes. Example: get_recipe { "recipe": "mac-beef", "plate_g": 550 }. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
| recipe | Yes | The recipe reference find_recipes gave | |
| plate_g | Yes | The plate find_recipes showed, in grams, or the size the customer asked for |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only flag readOnlyHint=false and idempotentHint=false; the description explains why and what that means: a successful call 'records one recipe use, at most once per account, recipe and UTC day', royalties derive from eligible uses, and requesting the method does not prove cooking. It also discloses the scaling asymmetry (ingredients scaled, in-step quantities not) and the 'log nothing while they cook' constraint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in sentence one, but the text runs long and mixes tool semantics with agent workflow instructions (recipe view vs step-at-a-time guidance, when to log, what to tell the customer) and spends several sentences explaining the 'statement' output field despite an output schema existing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with side effects and an output schema, the description supplies everything else an agent needs: scaling semantics, the display/step-by-step protocol, the use-recording rule with its royalty and once-per-day implications, and a concrete call example.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description's 'recipe is the reference find_recipes gave; plate_g the plate it showed, unless the customer wants another size' largely restates the schema text, adding only the alternate-size nuance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence gives a specific verb and resource ('Returns one IZeat catalogue recipe in full, to cook it') and immediately enumerates the payload (scaled ingredients, seasonings, method). It is clearly distinguishable from find_recipes (selection) and log_meal (consumption) named in the siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit trigger conditions are given: 'Use it when the customer chooses a recipe from find_recipes to cook, or asks for the method of an IZeat recipe', plus the repeat-call rule ('Call it for each new explicit request... even if that recipe appeared earlier'). It also routes downstream behavior to log_meal, so when and when-not are fully covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the connected account and tells you the next onboarding step. It never records or changes anything. Use it after get_connected_account when onboarding is not complete, or when the customer asks to resume setup. Follow the welcome and exact progression in the returned statement, one step per message. Ask only for the fields named in next_step, in the customer's language; do not calculate nutrition targets. After the customer answers, store their answer and the appropriate onboarding_status with update_profile, then call get_setup_step again. If the customer wants to continue later, store onboarding_status 'skipped' with update_profile. When setup is complete, briefly present the full range in starter_requests. Distinguish a nutrition-label photo plus the amount eaten from a plate photo for which you guide the customer through portions and preparation before estimating. Include corrections, day and period reviews, and finding IZeat catalogue recipes that fit the remaining targets, with guidance through their preparation. Do not reduce this to one example and never mention tool names. Example: get_setup_step {} with a missing target → ask for the daily calorie and macro targets the customer already uses. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'It never records or changes anything' largely restates that. It does add the return-format detail (statement begins with 'IZeat ·'), but then mixes in write-operation behavior ('store their answer ... with update_profile') that belongs to another tool, muddying the safety picture rather than clarifying it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded, but the body is a wall of tangential orchestration instructions covering topics owned by other tools (find_recipes, period_summary, meal corrections). Much of this does not earn its place in a 0-parameter read tool's description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, yet the description spends its length on unrelated workflow steps and even names sibling tools despite instructing 'never mention tool names.' For a simple zero-argument read step, the definition is over-stuffed with off-topic content while its own scope is diluted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the schema is empty at 100% coverage, so the baseline is 4. The description correctly presents the call as argument-free ('get_setup_step {}'), adding no misleading parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource: 'Reads the connected account and tells you the next onboarding step,' which is distinguishable from get_connected_account and get_profile. However, the description then sprawls into unrelated processes (day/period reviews, recipe finding, corrections) that blur what this specific tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear trigger and a named alternative: 'Use it after get_connected_account when onboarding is not complete, or when the customer asks to resume setup.' The re-invocation loop after update_profile is also spelled out. The surrounding process instructions are noisy but the core routing guidance is explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Records one meal — the whole meal in one call — as the list of what was eaten, one item per food with its quantity, calories, macros and source. Use it when the customer says what they ate. Ask before calling if the day or the meal type is unclear: never assume either. When quantities or a homemade or restaurant dish are too vague for a useful estimate, ask one concise bundled follow-up for the missing portions and any known label, recipe, batch or calorie values before recording. For a plate photo, guide the customer to one easy portion cue suited to the food: weight; otherwise spoonfuls or ladles, a fraction of the plate or batch, or a known container size. Offer only one likely alternative at a time. If no cue is available, ask for top and side photos with a ruler, a utensil of roughly known length, or their hand beside the food. Never infer a container's capacity or exact weight from appearance alone. If the customer accepts an estimate, give a range and record its stated midpoint as llm_estimate. Never silently use normal portions. Omit date for today's meal — the usual case. Name a day only when the customer did: pass their word (yesterday, 3 days ago, Tuesday) and IZeat resolves it in their time zone; pass YYYY-MM-DD only when they said the full date. Never compute a date yourself. meal_type is one of breakfast, morning_snack, lunch, afternoon_snack, dinner, evening — pick the nearest and say so if none fits. One meal of each type per day: when that day's dinner is already recorded, a second one is refused — use update_meal for additions or corrections, and another meal type for something eaten at another time. items: one entry per food, in the order the customer said them. Quantities are grams or millilitres, nothing else: convert what they said — cups, ounces, spoons, 'a banana' — with your own knowledge of that food, keep their words in as_said, and say in your reply that you converted. Figures may carry decimals; IZeat rounds once. Each item has its own source: 'label' when read from packaging or a nutrition label (photo or text); 'user' when the customer gave the numbers themselves; 'reference' for a plain, unmixed food — a vegetable, a fruit, rice, a chicken breast — whose weight the customer gave and whose values you quote from a standard composition table; 'llm_estimate' when you deduced anything: a mixed or homemade dish, or a portion you had to guess. A weighed steak next to an estimated sauce keeps its source; only the sauce is an estimate. Ask only what would change a figure by more than a third, in one short bundled question, and only when the customer's words leave it open: the fat something was cooked or dressed in; raw or cooked weight for what absorbs water — pasta, rice, grains, pulses, oats — where cooked weighs two to three times more; which variant when a family spans a factor of two (whole or skimmed milk, plain or sweetened yoghurt, which cheese, tuna in oil or in water). Everything else, take the likely reading and say it in your reply so the customer can correct it in a word: meat and fish weighed cooked, fruit without peel or stone, a medium egg, a 30 g handful of nuts, a 33 cl beer, a 12 cl glass of wine, 15 g of jam. Never ask how a vegetable was cooked when no fat was involved. setting only when the customer said where they ate (home, restaurant, friends, takeaway); never ask for it. idempotency_key: a random string you generate per meal, reused only if you retry this same call; the same key never creates a second meal. recipes: only when the customer cooked a dish from an IZeat catalogue recipe (find_recipes gives its reference). Record what they actually cooked and ate, with their own quantities and changes; recipes only says which rows are that dish: { "recipe": "aubergine-lasagne", "items": [1] } when the dish is one row, [1, 2, 3] when you listed its ingredients. Never add it for a dish that did not come from the catalogue. This link preserves journal facts; it does not count another recipe use for creator royalties. Returns only the customer-facing meal facts — every item with both measures — and the day so far against that day's target; internal IDs and timestamps are never returned. The returned meal facts include the complete recorded foods and quantities, totals, provenance or assumptions, and day balance. Never comment on how much it is. Example: log_meal { "meal_type": "lunch", "items": [ { "description": "grilled chicken breast", "amount": 180, "unit": "g", "kcal": 297, "protein_g": 56, "carb_g": 0, "fat_g": 6.5, "source": "reference" }, { "description": "steamed sweet potato", "amount": 80, "unit": "g", "kcal": 68, "protein_g": 1.3, "carb_g": 16, "fat_g": 0.1, "source": "reference" }, { "description": "homemade sauce", "amount": 40, "unit": "g", "kcal": 90, "protein_g": 1, "carb_g": 4, "fat_g": 8, "source": "llm_estimate" } ], "idempotency_key": "a3f9c1" }. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Omit for today. Otherwise the customer's own word — yesterday, 3 days ago, a weekday — or YYYY-MM-DD only when they said the full date | |
| items | Yes | What was eaten, one entry per food, in the order the customer said them | |
| recipes | No | Only when the customer cooked a dish from an IZeat recipe: which recipe, and which rows of items are that dish | |
| setting | No | Only when the customer said where they ate; it explains an estimate | |
| meal_type | Yes | ||
| idempotency_key | Yes | Random per call; reuse only when retrying this exact call |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=true, and the description adds substantial context beyond them: the duplicate-meal-type refusal, the fact that a repeated idempotency_key can never create a second meal, what the return contains and what it deliberately omits (internal IDs and timestamps), and that the reply must not comment on portion size. That is genuine behavioral disclosure, not restatement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded and the content is dense with real rules rather than filler, which suits a high-stakes capture tool. It is nonetheless a very long block with some redundancy (the ask-only-what-changes-a-figure rule is restated, and the trailing paragraph about the customer-facing "statement" is output-format material already covered by the output schema), pushing past what the caller strictly needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-destructive but irreversible-feeling write with six parameters, nested items, and an output schema, the description covers triggers, clarification policy, unit conversion, provenance, idempotency, duplicate handling and refusal cases. Nothing an agent needs to call it correctly on the first attempt is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 83%, yet the description still adds meaning the schema lacks: meal_type has no schema description at all and is explained here (pick the nearest, say so if none fits); date has an explicit 'never compute a date yourself' rule; source gets a decision procedure with a worked edge case (a weighed steak next to an estimated sauce keeps its source, only the sauce is an estimate); and recipes gets its linking semantics and royalty caveat.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource ("Records one meal — the whole meal in one call") and enumerates exactly what is recorded: one item per food with its quantity, calories, macros and source. It also routes corrections to the named sibling update_meal, so an agent can distinguish it from the other write tools in the set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger ("Use it when the customer says what they ate"), explicit pre-call conditions (ask if the day or meal type is unclear, never assume), and an explicit blocking case (one meal of each type per day; use update_meal for additions or corrections, another meal type for something eaten at another time). It further states what to ask versus what to assume, which is rare and directly actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns what was recorded between two dates, inclusive: coverage, totals, the average per recorded day, the target timeline, and public day, week, month or meal rows. Use it when the customer asks about more than one day: a week, a month, 'the last four weeks', 'day by day', 'what did I eat last week'. from and to are their local dates (YYYY-MM-DD). Never for a single day: if from would equal to — today, yesterday, one date — call day_summary instead. It returns each meal and its items, which this tool does not, and this tool refuses the call. granularity: 'total' for an overall answer; 'days' (default) for daily values through 31 days; 'meals' for every meal through 31 days. Longer visual ranges use weekly averages through one year and monthly averages after that. Every aggregate is per recorded day. Missing days have null values, never zero. At most the latest two years are returned in one answer; requested_range and effective_range make that limit explicit. history_available_from is the first available IZeat history, not necessarily the account creation date. When interactive reports are enabled for the account, the result is accompanied by a complete IZeat period component containing coverage, averages and the appropriate time series. Text-only clients receive the same typed nutrition data. Do not rank days unless the customer asks. Returns a typed public period report without storage identifiers. Example: period_summary { "from": "2026-08-08", "to": "2026-09-04" }. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | The customer's day as they said it — today, yesterday, 3 days ago, a weekday — or YYYY-MM-DD, last day included; must differ from from — one day is day_summary | |
| from | Yes | The customer's day as they said it — today, yesterday, 3 days ago, a weekday — or YYYY-MM-DD, first day included; must differ from to — one day is day_summary | |
| granularity | No | total: averages only · days (default): one line per recorded day · meals: every meal |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/openWorldHint=false/destructiveHint=false, and the description adds substantial behavior beyond that: missing days are null not zero, a hard two-year cap surfaced via requested_range/effective_range, history_available_from semantics, default granularity, 'do not rank days unless asked', and even that the tool refuses a single-day call. This is unusually rich disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core answer and the sibling exclusion, and most sentences earn their place. However, it runs long and the closing 'statement is the customer-facing IZeat message' paragraph explains a return field despite an output schema existing, which is tangential to tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter read tool with an output schema, the description covers the routing decision, range limits, null-vs-zero semantics, granularity degradation, and report components. Nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 genuinely new semantics: local-date format for from/to, inclusive bounds, and the range-length thresholds that silently change granularity behavior (31 days, one year). It stops short of restating enum semantics, leaving that to the schema, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Returns what was recorded between two dates') and enumerates the returned content: coverage, totals, per-recorded-day average, target timeline, and day/week/month/meal rows. It explicitly names the sibling it is not (day_summary) and the condition that separates them, so an agent can route without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use triggers in customer phrasing ('a week', 'the last four weeks', 'day by day', 'what did I eat last week'), an explicit exclusion ('Never for a single day... call day_summary instead'), and granularity-selection guidance tied to range length (days/meals through 31 days, weekly averages through a year, monthly after). Alternatives and conditions are fully spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restores the latest meal change undone with undo_last_change when the customer says the undo was a mistake. Always use two steps: first call without confirm to review what would return, changing nothing; after the customer confirms, call again with confirm true within ten minutes. Nothing else is needed: IZeat remembers what it showed. Only something undone in the last 48 hours can be restored. Returns the restored customer-facing meal and the recomputed day. Example: "That undo was a mistake" → review the latest undone change, ask for confirmation, then restore it. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | true only on the second call, after the customer agreed |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (destructiveHint=true, idempotentHint=true): it discloses the mandatory two-step review-then-confirm pattern, that the first call changes nothing, that state is retained between calls so no extra data is needed, and the 10-minute/48-hour time constraints. It also describes what is returned (restored meal plus recomputed day).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the action, then the workflow, constraints, return value, and an example, in a logical order. Every sentence carries information, though the trailing 'statement is the customer-facing IZeat message' paragraph reads as reused boilerplate and slightly dilutes focus.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still usefully names the returned fields, and it covers the confirmation protocol, time limits, and account context. Nothing needed to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With one parameter at 100% schema coverage, baseline is 3, but the description adds real meaning: confirm must be true only on the second call after the customer agrees, and the first call must omit it. It does not restate the schema mechanically but contextualizes the flag within the workflow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (restore) and a precisely scoped resource: the latest meal change undone via undo_last_change. It explicitly ties itself to the sibling it reverses, so an agent can distinguish it from undo_last_change without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('when the customer says the undo was a mistake'), the required two-step flow, the 10-minute confirmation window, and the 48-hour eligibility limit. Alternatives and preconditions are fully spelled out rather than implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Undoes only the latest meal write when the customer immediately asks to take back that write itself. That write may be a newly recorded meal or an update to a meal. Never use this tool to reach a corrected final meal by unwinding intermediate history, and never chain several undos before recreating meals. Use update_meal revise directly for that correction. Always use two steps: first call without confirm to review the exact change, changing nothing; after the customer confirms, call again with confirm true within ten minutes. Nothing else is needed: IZeat remembers what it showed. Only a change made in the last 48 hours can be undone. A meal update returns the meal to its previous rows — only what that update added or replaced; a newly recorded meal is removed from the active day; a deletion puts the meal back. Use update_meal for a targeted correction instead of undoing unrelated later work. Example: "Undo what you just logged" → review the latest change, ask for confirmation, then undo only that change. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | true only on the second call, after the customer agreed |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare the destructive/idempotent profile, and the description adds substantial context beyond them: the mandatory review-then-confirm flow, the ten-minute confirm window, the 48-hour undo limit, and exactly what each undo type does (update returns prior rows, new meal removed, deletion restored). This is rich behavioral disclosure the annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the key constraint are front-loaded and most sentences earn their place by covering distinct behaviors (alternatives, protocol, limits, undo semantics). It runs long, and the trailing boilerplate about the 'statement' field and account is only loosely tied to invoking this tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an undo/confirm-flow tool with an output schema already defined, the description covers the decision criteria, the multi-step protocol, time limits, and per-case undo behavior. Nothing an agent needs to invoke it correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single confirm param, so the schema carries baseline meaning. The description still adds real semantics: confirm is true only on the second call, must occur after customer agreement and within ten minutes, and the first call must review without changing anything.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource+scope: undoes only the latest meal write, which may be a newly recorded meal or an update. It explicitly distinguishes itself from update_meal and warns against chaining undos, so an agent can separate it from siblings 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('customer immediately asks to take back that write itself'), when-not-to-use ('never unwind intermediate history', 'never chain several undos'), and the correct alternative ('Use update_meal revise directly'). It also spells out the required two-step confirm protocol and the 48-hour/ten-minute windows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes one meal that is already recorded, identified by its meal type and day — omit date for today, otherwise pass the customer's word (yesterday, 3 days ago, Tuesday) or YYYY-MM-DD only when they said the full date; never compute one yourself. It never creates a missing meal. Choose action 'add' when the customer only adds something they also ate with that meal: send only the added foods as items, one per food; IZeat appends them and recomputes the meal. Choose action 'revise' when the customer corrects, replaces, removes or combines several changes. Read the meal first with get_meal (it returns the rows exactly as stored, and draws nothing), then send the complete list of items as the meal should now be — copy every untouched row exactly as read, change only what the customer changed, leave out what they removed — plus a short list of the changes. Each change description must repeat the concrete customer fact, including old and new quantities or supplied calorie values when known. One revise call stores all those changes together. Never recompute totals yourself: IZeat sums the rows. Items follow the same rules as log_meal: grams or millilitres only, the customer's own measure kept in as_said, figures with decimals allowed, one source per item. Only the rows that differ are touched: a replaced row is kept in IZeat's history and points at its replacement; untouched rows stay as they are. A repeated identical request does not apply the update twice. Returns only the previous and current customer-facing meal facts with their rows, their nutrition difference, and the day so far. The returned receipt includes the concrete foods, quantities or supplied values that were changed before the new totals. Never mention internal identifiers, storage versions or retry keys to the customer. Example add: update_meal { "action": "add", "date": "2026-09-03", "meal_type": "lunch", "items": [ { "description": "plain yoghurt", "amount": 125, "unit": "g", "as_said": "one pot", "kcal": 90, "protein_g": 8, "carb_g": 7, "fat_g": 3, "source": "label" } ], "idempotency_key": "add-yoghurt-a3f9c1" }. Example revise: the customer says the steak was 180 g rather than 200 g and they also ate a yoghurt → send every row as read, the steak row with amount 180 and its figures for 180 g, plus the yoghurt row, and changes ["Steak corrected from 200 g to 180 g", "Added a plain yoghurt"]. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint/idempotentHint, but the description adds substantial context beyond them: replaced rows are retained in IZeat history and point at their replacement, untouched rows are left alone, a repeated identical request is not applied twice, and totals are computed server-side rather than by the agent. It also discloses the return payload and receipt ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose and mode-selection rule are front-loaded, and although the text is long, the density is justified by the oneOf schema and the destructive write path. Sentences are directive and each carries an actionable rule.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-branch, destructive, idempotent mutation with a rich nested item schema, the description covers mode selection, prerequisites, field rules, change description format, return values, and even customer-facing messaging conventions. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet the description still adds critical semantics the schema cannot express: the date must be the customer's own word and never computed by the agent, 'items' means only added foods for action=add but the complete post-change meal for action=revise, and each change string must repeat old and new quantities. This meaningfully exceeds the schema's field-level docs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opening sentence states a specific verb and resource with scope: 'Changes one meal that is already recorded, identified by its meal type and day.' It explicitly differentiates from siblings by stating 'It never creates a missing meal' (vs log_meal) and directing the agent to read first with get_meal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit decision rule between the two modes: choose 'add' when the customer only adds food to that meal, choose 'revise' when they correct, replace, remove or combine changes. It also mandates prerequisites ('Read the meal first with get_meal') and states the alternative tool by name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stores the customer's name, a new daily target, the time zone their days are counted in, and/or onboarding progress. The only way anything about the profile or onboarding state changes. Marked destructive because a new name or time zone replaces the previous one; targets are never overwritten, a new one starts from the day given. Profile fields are optional; only what is passed changes. A target is never overwritten: passing one adds a new target valid from today in the account's time zone when target.valid_from is omitted, otherwise from the day given (the customer's word, or YYYY-MM-DD only when they said the full date), and earlier days keep the target they had. At least one of kcal, protein_g, carb_g, fat_g is required in a target; each is an integer, grams for macros. Set only what the customer actually chose: never fill in a nutrient they did not mention and never calculate a target for them. onboarding_status is in_progress while setup continues, skipped when the customer chooses later, and completed only after first name, last name and a target exist. timezone is an IANA name such as Europe/Paris or Africa/Johannesburg, derived from the city the customer names; pass it when get_connected_account reports no time zone or when they say they moved. idempotency_key is generated once for this profile change and reused only if that exact call must be retried. Returns the profile and the target now in force. Example: update_profile { "first_name": "Seb", "target": { "valid_from": "2026-09-03", "kcal": 2000, "protein_g": 150 }, "idempotency_key": "profile-a3f9c1" } → relay the receipt: name stored, target 2000 kcal · P 150g from 2026-09-03. statement is the customer-facing IZeat message. It begins with "IZeat ·" so customers can distinguish information returned by IZeat from the assistant's own response. For write operations, it also states whether the requested change was recorded in their IZeat account. Account: Sam (review@izeat.app)
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| timezone | No | IANA time zone the customer's days are counted in, e.g. Europe/Paris | |
| last_name | No | ||
| first_name | No | ||
| idempotency_key | Yes | Random per profile change; reuse only when retrying this exact call | |
| onboarding_status | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| data | Yes | |
| statement | Yes | Customer-visible IZeat receipt. Its value begins with "IZeat ·". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive/idempotent, and the description goes well beyond them: what is destroyed ('a new name or time zone replaces the previous one'), the additive target model ('targets are never overwritten, a new one starts from the day given'), and onboarding lifecycle rules. It also explains idempotency_key generation and reuse, which annotations only hint at.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the destructive/additive distinction are front-loaded, then constraints follow in a logical order, and a concrete example anchors it. It is dense and long, and the closing 'statement is the customer-facing IZeat message' paragraph is somewhat tangential given an output schema already exists, but each block still carries real instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter mutation with a nested target object and one enum, the description covers mutation semantics, idempotency, enum state transitions, formatting rules and an example. With an output schema present it need not re-explain return values, and it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, so the description carries the load and does: it specifies the target nutrient constraint (at least one of kcal/protein_g/carb_g/fat_g required, integers, grams), the omit-for-today vs YYYY-MM-DD semantics of valid_from, and the IANA format for timezone. It also warns against inventing values ('never fill in a nutrient they did not mention').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Stores the customer's name, a new daily target, the time zone... and/or onboarding progress') and then draws a hard boundary against siblings: 'The only way anything about the profile or onboarding state changes.' An agent can tell this apart from get_profile without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete trigger conditions, e.g. pass timezone 'when get_connected_account reports no time zone or when they say they moved', and enumerates when each onboarding_status value applies. It names a sibling as a trigger but never states the read-side alternative (get_profile) for inspecting state, so routing is clear but not fully closed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Food logging, nutrition summaries, and meal photo calorie and macro estimates.
A calorie MCP that looks up calories and macros from a 4M+ food catalog, not model guesses.
Calories and nutrition for any food, chain meal or barcode, and meal ideas for a goal and diet.
Free AI calorie & macro tracker: tell your AI what you ate and it logs it to your private food diary
Add one secure layer between your agents and this server.
