Rank foods by a nutrient

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

Annotations already declare read-only, idempotent, non-destructive, but the description adds substantial non-obvious behavior: Premium gating with a 'forbidden' failure mode and an explicit do-not-retry instruction, recipe expansion into ingredients, unit conventions (kcal for energy, g otherwise, summed over the range), and null per100 for custom items. This goes well beyond what the annotations 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?

Front-loaded with the result shape and a one-phrase example query, then the Premium constraint. Dense and mostly waste-free, though the first sentence's nested parentheticals (unit rules, per100 semantics) make it slightly heavy to parse for information the output schema may already carry.

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?

Covers the operation, ordering, unit conventions, recipe expansion, and the Premium failure path, which is the main thing that could cause a wrong agent action. Since an output schema exists, some of the returned-field explanation is redundant, and date-parsing guidance lives in the schema rather than the description, so it is strong but not exhaustive.

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%, including the nutrient enum and the get_today counting hint on both date parameters, so the schema carries the parameter burden. The description adds only indirect meaning (units/summation tied to the nutrient choice) and no per-parameter syntax or constraints beyond the schema. Baseline 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?

States a specific verb-like operation and resource: foods ranked by nutrient intake over a date range, with ordering ('most first') and the returned fields named. It is clearly distinguishable from siblings like get_favorite_foods (favorites, not nutrient totals) and get_range_summary (aggregate totals, not per-food ranking). An agent can select it without opening the 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 a concrete usage framing ('where does my sugar come from') and a hard precondition with handling instructions: Premium-only, forbidden error, tell the user, do not retry. It does not explicitly name an alternative tool to use instead when the user wants totals rather than rankings, so it stops short of full when-not/alternative guidance.

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