Sleep and stress in depth

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: explicit lookback windows (4 weeks for sleep, 2 weeks for Balance), the fact that clock times are local, and the derived-value logic for the suggested bedtime including the 30-minute adjustment rule. It does not describe response shape or fallback behavior when data is missing.

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 single long paragraph is front-loaded and internally labeled ('Sleep:' ... 'Stress:'), making it scannable despite its length. Every clause names a concrete data point, though the nested parenthetical about 'Garmin's need counted back from the usual wake time...' is dense enough to slow comprehension.

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 and a 0%-documented parameter, the description must carry the full burden. It does well on return contents but leaves the sole input undocumented and says nothing about data freshness, sync requirements, or behavior when a night is missing — reasonable gaps for a read-only report, but not complete.

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% — the single `date` parameter appears only as a regex pattern with no explanation. The description never mentions this parameter; phrases like 'tonight's suggested bedtime' and 'the last 4 weeks' only indirectly imply a default of today, leaving ambiguous what happens if a date is supplied (does the 4-week window end there? does the schedule shift?). This is the definition's most significant gap.

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 enumerates the exact resources returned — 4 weeks of sleep nights, sleep debt, timing consistency, stage mix, plus Body Battery charge/drain and stress-level awake minutes — so an agent knows precisely what data this tool yields. It lacks an explicit verb (e.g. 'returns') but the enumeration is specific enough to distinguish it from generic siblings like get_weekly_summary.

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 only routing guidance is the closing pointer: 'For what affects sleep for this user, also see get_insights', which usefully separates causal analysis from raw reporting. There is no guidance on when to prefer this over get_weekly_report, get_body_report, or get_today, and no stated preconditions such as whether Garmin sync must have run first.

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