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

With no annotations, the description fully discloses the tool's behavior. It explains the deterministic solver approach ('treats the three foods as a 3x3 linear system'), the filtering of unrealistic portions ('portions are exact but unrealistic are discarded'), ranking logic, and tolerance semantics. It also discloses the behavior when no exact fit exists, including the return of the closest attempt and an explicit instruction not to misrepresent results. This is thorough and goes beyond typical annotation coverage.

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-structured with a one-line summary, an 'Args' section, a 'Returns' section, and a usage note. It is concise for the complexity involved, with every sentence contributing meaningful information. The front-loaded purpose sentence and clear headings make it easy to parse.

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 complexity (7 parameters, algorithm, edge cases), the description is exceptionally complete. It explains the solving approach, parameter behaviors, return schema, and handling of failures. The output schema exists, but the description still enriches it with guidance on reporting results verbatim and not modifying numbers. This is a comprehensive, self-contained description.

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%, making the description's parameter explanations essential. The description defines each parameter with practical detail: target macros, exclude_tags (with example), tolerance (with interpretation), include_vegetable (explaining its effect on calculation), and max_results. This adds meaning far beyond the schema's bare titles.

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 tool's purpose: 'Build meals of one protein, one carb and one fat that hit macro targets exactly.' It uses a specific verb ('build'), names the resource ('meals'), and specifies the unique constraint (exact macro targets). This distinguishes it from sibling tools like get_food or calculate_macros, which operate on individual foods or calculations.

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 provides strong usage context: it explains when the tool is appropriate (building meals to exact macro targets), references a sibling tool for valid values ('Call list_available_tags for valid values'), and instructs the agent on how to handle unsuccessful fits ('Report that shortfall to the user -- do NOT present it as a successful fit or adjust the numbers to look closer'). This gives explicit guidance on when and how to use the 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 full burden of behavioral disclosure. It thoroughly explains internal behavior: arithmetic in Python, unit conversion rules and refusals (cross-family, countable units), calorie derivation formula, and exact error outputs (food_not_found, unit_mismatch, invalid_amount). The negative-amount behavior is also disclosed. This is exemplary 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 long but tightly structured with Args and Returns sections. Every sentence earns its place: the arithmetic warning, parameter details, conversion rules, return structure, and error handling are all necessary for correct use. No fluff or redundancy. Front-loaded with the core purpose.

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 calculation tool with three parameters and no annotations, the description is fully complete. It covers all inputs, outputs (including sample response), edge cases (unknown food, impossible conversion, negative amounts), and the internal calorie formula. Even without an output schema shown, the example return structure provides clarity.

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 fully compensate. It does: name is defined as resolved like get_food, amount is described as a number with examples, and unit is extensively explained including case-insensitivity, plural tolerance, and conversion rules. Every parameter gets detailed semantics well 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 description opens with a specific verb and resource: 'Calculate exact macros and calories for a specific portion of one food.' This clearly distinguishes it from siblings like get_food (which looks up food info) and build_meal (which assembles meals). 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 does not explicitly say 'when not to use' or compare against alternatives, but it provides strong contextual guidance: 'All arithmetic happens in Python. Do not compute these numbers yourself' implies this is the tool for macro calculations. It also references sibling get_food for name resolution, establishing a relationship. Clear enough, though exclusions are not spelled out.

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 burden for behavioral disclosure. It clearly explains the exclusion logic, the rejection of unknown labels, and the exact error format. It even explains the rationale for rejection (to avoid confusing an unfiltered result with a filtered one), giving complete transparency beyond the input 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?

The description is well-structured with clear Args and Returns sections. Every sentence adds value: the purpose, the filtering mechanism, the validation requirement, and the error behavior. It is detailed but not bloated, front-loaded with the main purpose, and easy to scan.

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 only one parameter and no annotations, the description fully covers the tool's behavior: what it does, how it filters, what output to expect, and how errors are handled. The return format is explained even though an output schema exists, and the reference to list_available_tags provides necessary external context. No gaps are apparent.

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 fully explain diet_type. It does this thoroughly: defines it as a single dietary/allergen label, provides concrete examples, states the requirement that it must exist in the data, references list_available_tags for the full list, and describes the behavior for absent labels. This adds significant meaning 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 description opens with a specific verb+resource: 'List every food compatible with one dietary restriction or allergy.' It explicitly positions itself as a convenience wrapper over list_foods and explains the filtering criterion (exclude_for field contains diet_type), clearly distinguishing it from sibling tools like list_foods and list_available_tags.

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 states when to use this tool ('convenience wrapper over list_foods') and directs the agent to call list_available_tags for valid diet_type values, which is an explicit alternative. It also warns against using invalid labels, effectively saying 'do not use with unverified labels' and explains the consequence (silent full database return). This covers both when and when-not.

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 full burden and does an excellent job. It discloses case-insensitive matching, tolerant matching rules, the ambiguity policy for multiple matches, the exact return format, and the no-match error format with suggestions. It even instructs the caller to retry with a suggested name verbatim. This is far beyond typical description depth.

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 with a one-sentence summary, a short matching-behavior paragraph, an Args section, and a Returns section. Every sentence adds useful information—no filler or repetition. The length is justified by the important edge-case behavior that must be communicated.

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 an output schema available, the description still clarifies return semantics and the error structure, which is helpful for planning. The matching rules, ambiguous-name handling, and examples make the tool self-contained. For a one-parameter lookup tool, this is complete and leaves minimal ambiguity.

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 only defines 'name' as a string with no description, so the description must compensate and does so thoroughly. It explains what the parameter means ('The food name'), provides concrete examples including a formatted one ('greek yogurt (0% fat)'), and clarifies matching tolerance. This gives the agent everything needed to construct valid invocations.

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 a specific verb and resource: 'Look up a single food by name and return its full entry with derived calories.' This clearly distinguishes the tool from siblings like list_foods (listing many) and calculate_macros (computing macros separately). It leaves no doubt about the tool's core function.

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 clearly conveys when to use this tool: when you need one food's details by name. It does not explicitly mention alternative tools or when not to use it, but the 'single food' framing and the listed sibling names provide enough context for a competent agent. A direct alternative comparison would lift this to 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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the vocabulary is computed at call time rather than hardcoded, and it exposes a non-obvious nuance: the same word (e.g., 'dairy') can have different meanings across the two vocabularies. This goes beyond a simple list and prevents misuse.

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-structured with a clear opening statement, a specific usage directive, and a bulleted breakdown of return keys with concrete examples. Every sentence adds value, and the length is justified by the need to explain the subtle distinction between vocabulary types.

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 simple metadata tool with no params and an output schema, the description is remarkably complete. It includes dynamic computation behavior, when to invoke the tool, the full return structure, and semantic differences between tag categories. The agent can use the tool correctly and interpret results without additional information.

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 has zero parameters, and the input schema is empty, so there is no parameter semantics to clarify. The description instead explains the output structure and meaning, which is appropriate for a parameterless tool. This aligns with the baseline of 4 for 0-param tools.

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 'Return' and a well-defined resource ('real filter vocabulary present in the database'), making the tool's purpose immediately clear. It distinguishes itself from siblings like list_foods and filter_by_diet by focusing on the vocabulary itself, not the foods or filters.

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?

Explicitly instructs the agent to call this tool before using `tags` or `exclude_tags` on any other tool, and explains the consequence of not doing so. It also clarifies how the two vocabularies (tags vs. exclude_for) are used by different sibling tools, providing clear when-to-use context.

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 carries the burden and does so thoroughly. It discloses OR vs AND matching for tags and exclude_tags, distinct vocabularies, behavior on invalid category (returns error with valid values), the meaning of an empty result, and the caveat about per-unit macros and recommending calculate_macros for scaling.

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-structured with a concise one-sentence summary, followed by Args and Returns sections. Despite its length, every sentence contributes critical details (filter semantics, return shape, edge cases) and it is front-loaded with the primary purpose.

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 is complete for a tool with 3 parameters and no annotations. It covers return format (count and foods with fields), error handling for invalid category, empty result semantics, unit variation, and cross-tool guidance. The output schema exists, but the description still explains the derived calories and scaling caveat, making it self-sufficient.

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 adds rich meaning for all three parameters: category restrictions with exact allowed values, tags OR-match semantics and vocabulary source, and exclude_tags with its own distinct vocabulary and behavior (drop if ANY appear). It also provides examples and clarifies the relationship between tags and exclude_tags.

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 begins with 'List foods from the database, with derived calories, optionally filtered,' which is a specific verb+resource statement. It clearly distinguishes from siblings like get_food (single food) and calculate_macros (portion scaling) by focusing on listing with optional filters.

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 for using filters and points to alternatives: 'To scale a food to a real portion, use calculate_macros rather than multiplying yourself' and 'Call list_available_tags for the complete real vocabulary.' However, it does not explicitly mention when to use this tool over filter_by_diet or get_food, so it lacks explicit exclusions.

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