get_nutrition_scores

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations, including date resolution semantics: 'Defaults to today in the account timezone, resolved at call time,' and guidance to prefer relative date inputs. This explains call-time behavior without contradicting the annotations.

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 and front-loaded: a clear one-line purpose, then return contents, then usage guidance, then parameter details. The category list is long but directly informs what the agent will receive. No sentence is filler.

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?

With only one optional parameter, a full explanation of that parameter, an output schema present, and annotations covering safety/idempotency, the description is complete for a correct call. The agent knows what data comes back, when to use it, and how to specify the date.

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 provides only the parameter name 'date' with no description, so schema coverage is 0%. The description fully compensates by specifying accepted formats ('YYYY-MM-DD, today, yesterday, or N days ago'), the default behavior, timezone handling, and a recommendation about relative inputs. This is exemplary parameter documentation.

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 names a specific verb and resource: 'Get nutrition scores with per-nutrient consumed amounts and category grades.' It enumerates the exact categories returned and labels itself 'the richest nutrition endpoint,' which differentiates it from siblings like get_food_log or get_macro_targets. An agent can immediately tell what this tool does.

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 when to use the tool: 'use it when you need to know both how much of each nutrient was consumed AND how close each is to the target.' It does not name alternative tools or give when-not-to-use guidance, but the intended context is clear and actionable.

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