Get sleep

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), yet the description still adds non-obvious behavior: it returns null when no sleep was recorded, it defines the night-to-date attribution rule, and it discloses the upstream request cost relative to get_day_summary. Those are exactly the kind of rate/cost and edge-case disclosures annotations cannot carry.

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 returned fields, then the date-attribution rule, then the sibling/cost tradeoff. Two tight paragraphs, no filler, and the most decision-relevant content comes first.

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 an output schema covering return values and annotations covering safety, the description fills the remaining gaps: the empty-result behavior, the date semantics, and when to pick a sibling tool instead. Nothing needed to invoke this correctly is missing.

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% for the single `day` parameter, so the schema already documents it as a date the night ended on. The description's 'last night is today's date' restates that same rule rather than adding new syntax or format guidance, so 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 and resource ('Return one night's sleep') and enumerates exactly what is returned: start/end, total, deep, light, REM, awake time, sleep score, average respiration. It also distinguishes itself from get_day_summary and get_trend, so an agent can differentiate it from siblings without opening schemas.

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?

Explicit routing: use this for a single night, use get_day_summary for the bundled summary, and use get_trend with metric sleep or sleep_score for multi-night totals. It even quantifies the cost difference (five Garmin requests vs one), giving the agent a concrete reason to prefer this tool.

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