query_health

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

With no annotations, the description carries the full burden and does so well: it discloses that resolution is accepted but ignored, that unknown/ambiguous fields error with a did_you_mean list, that typos/aliases are auto-resolved via _meta.field_resolved_from/field_used, and that empty ranges return empty values rather than errors. It stops short of explicit read-only/permission statements, but the behavioral disclosure is unusually rich.

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 purpose and routing before the denser parameter semantics. Every sentence earns its place, though the parameter block is dense enough that it reads as one long paragraph rather than being cleanly separated.

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 still explains the return shape: per-field 'unit', empty values for no-data ranges, and _meta resolution fields. Combined with the error semantics, an agent has all it needs to call and interpret results.

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 for all 4 parameters — and it does: field naming conventions ('_series' = intraday timeseries vs plain = one value per day), the multi-field sleep_score behavior, ISO YYYY-MM-DD inclusive dates, and the ignored resolution param. This meaning exists nowhere else.

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 (Query) and resource (Garmin health data: heart rate, sleep, stress, body battery, steps) over a date range, and distinguishes itself from siblings query_context (weather/pollen/air quality) and list_available_fields. An agent can tell exactly which tool to pick without opening any 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?

Explicitly routes alternatives: 'Use query_context instead for weather, pollen and air quality; call list_available_fields first if the exact field name is unknown.' When-to-use and when-to-use-elsewhere are both stated concretely.

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