garmin_nutrition

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds behavioral substance beyond that, notably the 61-day cap on range queries and the fact that energy_balance compares intake against burn and infers weight-trend implications. That range limit is a real constraint an agent could otherwise violate.

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?

Compact and front-loaded with the resource and kind list before the range caveat. The telegraphic, semicolon-joined fragment style is slightly awkward to parse but contains no filler sentences.

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 no output schema, the description carries return meaning and does so at a high level for each kind (totals, intake-vs-burn, goals). Defaults and date formats live in the schema. It stops short of describing the returned fields or empty/missing-data behavior, which leaves a modest gap for a five-mode 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?

Schema coverage is 75% and the schema already documents date formats and the range parameters, but the description adds the mapping the schema lacks: which kinds are single-date (food_log, meals, settings) versus range-based (summary, energy_balance). That is genuine semantic value over the bare enum.

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?

Names the specific resource ("Garmin Connect's food log") and enumerates the five kinds of data retrieved, so the agent knows this is a read tool for food log, meals, goals, daily summaries and energy balance. It is not explicitly contrasted with sibling writers like garmin_log_food or garmin_set_nutrition_goals, but the kind list distinguishes it well enough.

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?

Implicit guidance comes from the kind names and from the phrasing that food_log/meals/settings are "for one date" while summary/energy_balance span "up to 61 days", which tells the agent which kind to pick for which question. There is no explicit statement of when to prefer this over garmin_log_food, garmin_food_search or garmin_set_nutrition_goals, so the agent must infer the read-vs-write split.

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