Sum an ingredient list into per-serving nutrition

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

With no annotations, the description carries full responsibility for behavioral transparency. It clearly discloses the outputs: summed totals divided by servings, %DV, and per-ingredient contribution breakdown. It also explains how to handle off-database ingredients via manual_items. It does not cover failure modes or error handling for missing foods, but the main behaviors are well described.

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 description is two sentences—front-loaded with the main action, then a concise caveat about off-database items. Every phrase adds value, covering input, output, and special-case handling without unnecessary words. It is a model of efficient specification.

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 no output schema, the description adequately communicates the return values (totals, %DV, per-ingredient breakdown) and the main input pattern. It addresses the special case of manual items. It does miss potential edge cases like what happens if a query matches no FDC entry and no manual_items is provided, but overall the description is complete enough for typical use.

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 schema already documents servings and manual_items with descriptions, and the description adds semantic context for the items structure: {query or fdc_id, grams}. It clarifies the mutually exclusive lookup identifier choice and explains manual_items as ingredients with known nutrients. This enriches the 67% schema coverage, making the parameters clearer than the schema alone.

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 uses a specific verb ('Sum') and identifies the resource ('ingredient list'), clearly stating the core action: return per-serving nutrition. It distinguishes itself from siblings by emphasizing the recipe-level aggregation and per-ingredient breakdown, which contrasts with the likely single-item or lookup nature of get_food, search_foods, and food_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?

The description makes the primary usage context explicit: supply an ingredient list with grams, get summed nutrition. It also provides guidance for a sub-case (ingredients not in FDC) by pointing to manual_items. While it does not explicitly name alternatives or exclusion criteria, the title and phrasing clearly separate it from the sibling tools, so the guidance is strong.

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