Last night and the days before it

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely non-obvious behavior: it computes no averages or deltas and returns raw records, `today` is frequently empty because of ring sync latency, and a `missing` field names which record came back empty. That last point prevents an agent from misreading an empty result as a real signal.

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 purpose is front-loaded in the first sentence, but the body is long and rhetorical for a single-parameter read tool – capitalised emphasis, "and that is the whole of it", and a nine-year-data argument about why percentages would be misleading. Some of that is justification rather than operational guidance, and the key caveats (empty `today`, `missing`) are buried at the end.

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 ably compensates by explaining what comes back (raw records, no derived metrics) and how to read an empty result via the `missing` field. It is close to complete for a simple read tool, though the shape/fields of the returned records remain unspecified.

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?

There is only one parameter (`days`, 1-30, default 7) and schema description coverage is 100%, so the schema already carries the semantics and baseline 3 applies. The description gestures at the history window ("enough history", "the days before them") but adds no syntax or bounds beyond the schema.

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 opening line names the exact resources returned (last night's sleep, today's readiness, plus preceding days) and the description explicitly contrasts itself with `oura_query` – the four round trips it replaces. An agent can distinguish this from oura_check, oura_collections, and oura_query 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?

It names the concrete trigger question ("How did I sleep?") and the alternative it supersedes (four calls through `oura_query`), giving a clear selection rule. It stops short of stating when NOT to reach for it (e.g. for non-sleep/readiness metrics, which presumably belong to oura_query).

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