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

With no annotations provided, the description carries the full behavioral burden and succeeds. It discloses query re-verification, server-side count resolution, 'raise rather than guess' behavior, server-computed totals, caveat-relay requirements, null-vs-zero macro semantics, and the rule against inventing numbers. No contradiction.

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 long but front-loaded with the core contract and organized by topic. Nearly every sentence carries safety-critical instruction, though some repetition around server-side computation and the 'never invent' rule could be tightened. Length is mostly justified.

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, yet the description pre-defines the response shape (summary, report_path, totals), caveat handling, and failure modes (unresolvable counts, null macros, unverifiable queries, source caveats). It leaves no ambiguity about how to interpret results or handle edge cases.

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 0%, but the description compensates thoroughly. It explains fdc_id provenance, amount unit syntax and count phrases, label verbatim requirements, query verification, source values, and target usage. Every relevant input is given meaningful guidance beyond the bare 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?

The first sentence states the exact operation: 'Get verified macros (kcal, protein, carbs, fat) for one ingredient at one quantity.' The singular 'one ingredient at one quantity' clearly distinguishes this from the batch sibling. It names the resource and the specific data returned.

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 explicitly says fdc_id must come from a prior search_foods call and never be guessed. It provides source-specific handling for 'off', a fallback policy when search_foods finds nothing, and clear conditions around count-phrase quantities. This gives explicit when-to-use and when-not-to-use guidance.

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?

With no annotations, the description fully discloses key behaviors: partial batch failures are returned alongside successful items, missing macros come back null with caveats and affect totals, and totals are always computed server-side so the agent must not sum itself. It also warns about the specific misuse of burying flagged items. These are significant behavioral traits beyond what any schema would convey.

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 long but every sentence earns its place for a tool with complex failure and computation semantics. It is front-loaded with the core purpose and then systematically covers failure handling, summary reading, missing data, and totals. The structure is logical and the prose is dense without wasted words.

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?

The description covers the most critical aspects: failure handling, null handling, server-side totals, and target behavior. However, it does not specify the full response structure (e.g., exact fields of summary and totals beyond those mentioned) or any limits like pagination. Given there is no output schema, a bit more completeness would be ideal, but the core pitfalls are well covered.

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 0%, so the description must compensate. It does explain the target parameter: passing it gives totals.outcomes, otherwise every macro reads 'no target'. However, it does not describe the structure of reqs beyond implying it is a list of ingredients, nor the fields within each NutritionRequest. The compensation is partial: target semantics are clarified, but reqs semantics are left to the schema's type definitions.

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 explicitly states this is the batch version of get_nutrition for multiple ingredients, and distinguishes it from the single-item sibling by advising to use it instead of a loop. The verb-resource pair (get nutrition for multiple ingredients) is specific and unambiguous, and it clearly separates from siblings like search_foods.

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 provides explicit when-to-use guidance: 'use this instead of calling get_nutrition in a loop' and explains the performance benefit. It also gives detailed operational instructions on reading the summary to avoid missing flagged items, and how to pass the target once for the whole plate to get outcomes, including the consequence of not passing it. This is abundant usage direction.

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?

With no annotations, the description carries the behavioral burden. It discloses that macros are freshly computed and never cached, and clarifies that discrepancies should be resolved by trusting this call. This is valuable transparency about freshness and potential inconsistency, though it doesn't mention side effects (it's clearly a read) or error cases.

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 with no superfluous words. The key instructions (purpose and version default) are front-loaded, and the freshness note is a necessary caveat. Efficient and well-structured.

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 read-only fetch tool with two parameters, the description is complete. It explains the version behavior and the freshness contract. It lacks explicit mention of not-found handling or return format, but the absence of an output schema keeps the burden lower. Given the simplicity, this is solid.

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 description explains that omitting version returns the latest, which adds meaning beyond the schema's 'default: null'. It clarifies version's role as a selector for a specific version, and name is self-explanatory from the context. This goes beyond the schema's bare field definitions.

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 clear verb and resource: 'Fetch a saved recipe.' This distinguishes it from siblings like list_recipes (which lists all) and get_recipe_history (which retrieves past versions). The action is unambiguous.

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 gives version guidance but does not explicitly compare to alternatives. It implies use when you have a specific recipe name, but it never says 'use list_recipes to browse all recipes' or 'use get_recipe_history to see version history.' Missing explicit routing.

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?

No annotations provided, so description carries full burden. It discloses that it fetches versions 'in order' and that each version's notes explain changes, which is useful behavioral info. However, it doesn't explicitly state read-only status, error behavior, or any side effects. For a fetch operation, this is reasonable but not exhaustive. Given no annotations, a score of 3 reflects adequate but not outstanding transparency.

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 concise sentences. The first states the action and purpose, the second gives usage guidance. No fluff, clearly front-loaded with the core function.

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?

Given the simplicity (one parameter, no nested objects), the description covers the essential behavior. It mentions the order and the notes field, and the output schema likely details the return structure. It doesn't address edge cases like a missing recipe, but for a simple fetch tool, that is minor. A score of 4 is appropriate.

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 has 0% coverage (no description for 'name'). The tool description does not explicitly describe what 'name' refers to, though the context implies it's the recipe name. The description provides no additional guidance on the parameter's format, meaning, or constraints. With no schema description, this is a significant 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?

The description clearly states the action ('Fetch every saved version of a recipe'), the resource (recipe history), and the order ('in order' to see evolution). It explicitly distinguishes from get_recipe (which presumably returns the current state) by highlighting the historical perspective. The verb 'Fetch' is specific and the resource is unambiguous.

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 gives a clear context: 'Use this before assuming a recipe's current numbers are the only numbers it ever had.' This implies when to use it (when you need to see evolution) and when not to (when you only need current numbers). It doesn't explicitly mention alternatives, but the context implies get_recipe for current state. Slight deduction for not explicitly naming the alternative tool.

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?

With no annotations provided, the description carries the behavioral disclosure burden. It goes beyond a simple list by revealing that filters are computed against each recipe's current plate and are fresh on read, which is meaningful behavioral context. It does not disclose sorting or pagination, but those are not essential for a list tool with an output schema.

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, no filler, and the primary operation is front-loaded. The second sentence earns its place by clarifying freshness semantics that are not visible from the schema.

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?

The tool is simple, and an output schema exists, so return-value details are not required. The description covers the operation, filter semantics, optionality, and freshness. It stops short of perfect completeness by not stating whether multiple filters combine with AND, but this is a minor gap for a listing 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?

The input schema has no parameter descriptions, so the description must compensate. It does, by mapping 'protein range', 'calorie range', and 'fdc_id appears as an ingredient' to the schema's min_protein_g, max_kcal, and contains_fdc_id. This adds functional meaning beyond bare parameter names.

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 states a specific action ('List saved recipes') and a clear resource, with optional filtering dimensions. It is distinguishable from siblings like get_recipe (single recipe) and search_foods (food database search) without needing to inspect 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?

The description makes the intended use clear: retrieving saved recipes with optional filters. It does not explicitly name alternatives or exclusions, but the context of siblings and the 'saved recipes' phrasing provides enough guidance for an agent to select it over single-recipe or food-search tools.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that the correction is permanent, that every future lookup short-circuits to it, that it is user-scoped, that the server fetches the real USDA description, and that the note is the only record of the correction's rationale. This is strong transparency about side effects and persistence.

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 dense but well-structured: core action and trigger first, then parameter rules, then persistence behavior. Each sentence adds necessary information with no filler, and the most important usage guidance is front-loaded.

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?

Despite having no annotations and no output schema, the description covers the tool's purpose, when to use it, what each parameter means, required constraints, and the lasting side effects. An agent has enough information to select and invoke the tool correctly without needing additional context.

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 0%, so the description must explain parameters, and it does thoroughly: fdc_id fixes food resolution, grams fixes count mass, phrase must be the exact amount-style phrase used with get_nutrition, and note is the rationale. It even explains why the phrase exactness matters, which is critical for correct invocation.

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 states a specific action ('permanently correct'), a clear resource ('what a phrase means or what a count weighs'), and a scope ('for this user'). It also gives the triggering condition ('lookup's summary flags something as wrong or low-confidence'), which distinguishes it from siblings like get_nutrition, search_foods, and save_recipe.

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 explicitly says when to use the tool: when a lookup summary flags something wrong or low-confidence and the user provides the correct answer. It also gives important constraints, such as not supplying your own description and using the exact count phrase for grams. It does not explicitly contrast with alternative sibling tools, but the intended usage context is unmistakable.

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?

With no annotations, the description carries full responsibility for behavioral disclosure. It explicitly reveals append-only semantics ('always creates a new version, never overwrites'), notes as the only record of changes, and the requirement that fdc_id be real. This is far beyond what the schema provides and gives the agent essential non-obvious behavior.

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 front-loaded with the core purpose and then systematically explains each parameter with examples. It is dense with useful guidance and contains minimal filler, though the phrase 'the most useful field in the whole store' is somewhat editorial. Overall it is well-structured and appropriately sized.

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 nested objects and no output schema, the description covers all input semantics, the append-only behavior, and the notes requirement, which is enough to invoke it correctly. It does not describe the return value or error handling, but those are less critical for a save operation. The guardrail about fdc_id is a sufficient warning.

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 0%, so the description must compensate. It thoroughly explains plate (absolute grams per ingredient, not household total), shares (fractions of user's plate, leave empty for solo cooking), and notes (required, should describe changes). It also clarifies fdc_id must come from a real lookup. Only 'name' is left implicit, but its meaning is 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?

The description opens with 'Save a new version of a recipe', a specific verb and resource. It further distinguishes itself from overwriting by stating 'it never overwrites one', which clarifies its role relative to siblings like save_override. The purpose is unmistakable.

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 gives clear context on how to use the tool correctly: plate must be the user's own portion, shares is for others and should be empty when cooking alone, and fdc_id must come from a real lookup. It states 'Saves are append-only: this always creates a new version, it never overwrites one', which is an explicit when-not scenario, but it does not name an alternative tool for overwriting.

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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses ranking order, exception behavior, potential fetch failures, source trustworthiness, Open Food Facts caveats, and the always-tried USDA fallback, leaving little ambiguity about tool behavior.

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 well-organized and front-loaded with purpose and usage, but it is somewhat verbose and repeats fallback and trust caveats in multiple places. It remains valuable and focused, though trimming redundant sentences would improve conciseness.

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?

Given the tool's moderate complexity and the lack of parameter descriptions in the schema, the description covers all essential operational aspects: matching, ranking, error behavior, source selection, failure retry guidance, and fallback logic. The mention of the output schema means return-value explanation is unnecessary, and the description still clarifies key response characteristics.

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?

Even though the schema provides only names and defaults, the description richly explains all three parameters: query should be the exact string passed through, limit reserves slices for candidates, and expect_branded has nuanced semantics for when to enable Open Food Facts. This far exceeds what the bare schema provides.

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 clearly identifies the tool as a USDA FoodData Central search for candidate foods matching a plain-language query, with a specific verb and resource. It also distinguishes this search tool from nutrition lookup and recipe siblings by stating it returns ranked candidates and raises only when nothing matches.

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 explicitly states this is the only way to obtain a valid fdc_id and instructs the agent to call it before any nutrition lookup. It also gives detailed when-to/when-not-to guidance for the expect_branded flag, including fallback behavior when USDA returns nothing.

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