Recipe Nutrition Calculator

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: it discloses the conversion methodology (USDA household measure weights per food), the full return payload (per-line grams and matches, totals, per-serving, FDA-rounded with %DV), and crucially the failure behavior — unmatched lines are listed, never guessed. That failure-mode disclosure is exactly the kind of context annotations cannot carry.

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 capability statement is front-loaded and the return-value inventory follows; no filler sentences. The first sentence is very long and packs parsing, conversion, and summation into one clause chain, which costs a little readability.

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?

There is no output schema, and the description compensates fully by enumerating the return fields and the FDA rounding basis. Combined with 100% schema coverage on inputs, an agent has everything needed to call this correctly and interpret results.

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; the description adds real meaning by explaining how 'lines' are interpreted (amount first, household units converted to grams via USDA weights) and that 'servings' drives the per-serving outputs. It stops short of stating unit/edge-case rules for the lines array beyond the examples the schema already gives.

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?

Specific verb chain (parses, converts, sums) with a concrete resource (recipe nutrition) and worked examples of the input format, so the agent knows exactly what it does. It never names the sibling tools it overlaps with (lookup_ingredient_nutrition for single items, round_nutrition_label for FDA rounding, scale_recipe_nutrition for rescaling), so differentiation is left to inference.

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?

Usage is implied by the scope statement (whole recipe, totals plus per-serving), but there is no explicit 'use this when' or 'use X instead' guidance. The mention of FDA rounding hints at overlap with round_nutrition_label without resolving it.

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

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds real operational context: 406 ingredients, SR Legacy and Foundation Foods source, embedded data with no API key. What is missing is failure behavior — whether lookups are fuzzy, and what happens for an ingredient outside the 406.

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?

Two sentences, front-loaded with the return payload before the usage directive. The nutrient enumeration in the first sentence is somewhat long but earns its place by removing guessing about which fields come back.

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?

There is no output schema, and the description fully compensates by enumerating returned fields (per-100 g macros, FDC id, household measure weights, optional amount-scaled nutrients) as well as data provenance and coverage size. An agent has enough to call it and interpret the response.

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 every parameter is already documented, making 3 the baseline. The description adds only modest value by showing amount and unit used together ('1.5 cup or 3 large') and noting that household measures are returned in grams, but no new syntax or constraints beyond the schema.

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: returns USDA FoodData Central nutrient values per 100 g for a single recipe ingredient, plus FDC id and household measures. The per-ingredient/per-100 g scoping implicitly separates it from recipe-level siblings, but no sibling is named, so an agent must infer the boundary from the name alone.

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 one useful directive — 'Use it instead of estimating nutrition from memory' — which sets a positive trigger. There is no explicit when-not (e.g., whole-recipe calculations vs. single ingredient, what to do for ingredients outside the 406) and no named alternative such as calculate_recipe_nutrition.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description still adds real substance: the exact rounding tiers per nutrient, the added-sugars/fiber 'less than 1g' handling, and the specific DRV values used for percent Daily Value — all beyond what 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?

A single dense paragraph that front-loads the governing regulation and then enumerates rule groups efficiently; nothing is filler. The nested parentheticals make it slightly harder to scan, keeping it just below a 5.

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 pure computation tool with no output schema, the description should hint at the return shape; it names what is produced (rounded values plus percent Daily Value) and implies some outputs may be strings via the 'less than 1g' rule, but never enumerates output fields. That is a minor gap, not a blocking one.

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 every parameter already carries a description with units and bounds, so the baseline is 3. The description adds meaning by mapping nutrients to their specific rounding treatment (e.g., sodium rounds to 5 mg up to 140 mg, then 10), which is useful but partially redundant with the schema's unit labels.

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 — applies FDA Nutrition Facts rounding rules from 21 CFR 101.9(c) — to explicitly scoped inputs (unrounded per-serving values). This is clearly distinct from the sibling tools that calculate, look up, or scale nutrition; nothing overlaps.

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?

The phrase 'to unrounded per-serving values' tells the agent the required input state, which implicitly positions this tool as the step after calculate_recipe_nutrition. It does not, however, explicitly name a sibling or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral detail beyond those annotations: parsing mixed numbers and fraction characters, using USDA FoodData Central values, and applying FDA label rounding.

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?

A single dense sentence with the core action front-loaded. The parenthetical parsing detail and nutrition sourcing/rounding are relevant and no sentence is wasted.

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?

There is no output schema, so the description appropriately states that total and per-serving nutrition are recomputed. It does not specify the exact response fields or error behavior, but it is complete enough for an agent to understand and invoke the tool.

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 parameter meanings are already well documented. The description still adds value by clarifying that factor and original-to-target-servings are alternative scaling modes and by noting mixed-number and fraction-character parsing.

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: scales ingredient lines and recomputes nutrition. It clearly conveys the scaling-plus-nutrition purpose, though it does not explicitly differentiate itself from sibling tools such as calculate_recipe_nutrition.

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?

Explains the two supported scaling modes: by a factor, or from original to target servings. This gives clear usage context, but it does not state when to prefer this tool over the related nutrition-calculation or rounding siblings.

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