Sleep (one night)

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context about the detail modes (compact = readable units matching the summaries shape; full = raw Garmin payload), but says nothing about behavior for missing nights, partial data, or unresolved dates.

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?

Two short sentences, front-loaded with the resource and scope, and the second sentence carries the actionable detail flag. It is slightly cryptic because 'same compact shape as get_sleep_summaries' only pays off if the agent knows that sibling's output.

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?

For a simple two-parameter read tool with full schema coverage, complete annotations, and no output schema, the description covers scope, the key modifier, and the relationship to the summaries sibling. The main omission is what the response looks like concretely and how empty or partial nights surface.

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%, so both parameters are already documented, including the anyOf pattern for date and the compact/full enum. The description reinforces the detail semantics ('complete record') without adding syntax, format, or edge-case behavior beyond the schema, so the baseline of 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?

The description states a specific resource and scope: one night's sleep, explicitly tied to the 'compact shape' used by get_sleep_summaries, which distinguishes it from the multi-night summary sibling. The verb is implied by the tool name rather than stated, and 'same compact shape as get_sleep_summaries' assumes the agent already knows that sibling.

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?

It gives one clear usage rule: use detail='full' for Garmin's complete record. It also gestures at the sibling relationship via get_sleep_summaries, but never states the actual decision boundary (single night here vs date range there) or what to do when no sleep was recorded.

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