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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds meaningful behavioral context beyond annotations: missing permissions cause the affected data types to appear under `unavailable` rather than failing the call, and it lists the returned categories for a tool with no output schema.

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 description is front-loaded with the primary action and scope, then efficiently layers in usage routing, default behavior, and fallback behavior. The long data-type list is information-dense but earns its place by telling the agent exactly what a 'daily overview' returns.

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?

Given no output schema, the description carries the burden of explaining return contents and does so by enumerating the included data categories. It also covers selection guidance, default behavior, and partial-availability handling, leaving no significant gap for an agent deciding to call this tool.

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 100%, so the schema already documents the single `date` parameter, including its default. The description adds a small refinement beyond the schema: 'Omit date for the latest day with a sleep or readiness score,' which clarifies what 'latest day' means in practice.

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 opens with a specific verb+resource: 'Get everything Oura recorded for one day in a single call.' It enumerates the data types covered and explicitly distinguishes itself from get_trends (multi-day) and list_* tools (one data type over a range), so an agent can select it confidently against siblings.

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 explicit when-to-use guidance: 'Start here for today, last night or any single date,' and names alternatives for other cases ('use get_trends for multi-day questions and the list_* tools for one data type over a range'). It also clarifies the default when date is omitted, leaving nothing to inference.

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

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

Annotations already declare a safe, idempotent read, but the description adds genuinely new behavior: a 30-day range cap per call, raw resolution truncating at 2000 samples, latest:true overriding all other arguments, and the meaning of a truncated:true response. These are operational constraints not present in the annotations or schema.

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 core purpose before the usage routing and edge cases. It is a single dense paragraph with heavy parenthetical enumeration of sources and stats; every clause carries information, though it could be broken into sentences for easier scanning.

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 carries the return-value burden and does so: it names the returned fields (avg/min/max bpm, dominant source, overall and per-source stats) and the truncated flag. Combined with defaults, limits, and the sibling routing, an agent has everything needed to call it correctly.

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 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it clarifies that latest:true causes other arguments to be ignored, that raw returns individual samples capped at 2000, and that buckets are aligned to local time. The interaction between latest and the other params is not derivable from the schema alone.

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+resource (get the heart-rate time series) and immediately qualifies the shape of the result: bucketed aggregation with avg/min/max bpm, dominant source, and per-source stats. It also explicitly distinguishes itself from list_sleep_periods for overnight/HRV use cases, 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?

Gives concrete when-to-use cases (at particular times, during a workout, across a day) and an explicit when-not with a named alternative (overnight averages, lowest HR, HRV → prefer list_sleep_periods). It also states defaults (last 24h at hourly) and the 30-day per-call range limit, leaving little to inference.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so safety is covered. The description adds genuinely non-obvious behavior: that missing scopes yield an error field for that part while the rest of the payload still returns, which directly affects how an agent should parse a partial response. It also confirms the tool takes no arguments.

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 most important fact – what this tool returns – is front-loaded in the first sentence, followed by usage, argument count, and partial-failure behavior. All four sentences carry information the agent needs; none is filler.

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 carries the full burden of describing the return payload, and it does so field by field, including the error-field-on-missing-scope case. Combined with annotations covering the safety profile, an agent has everything needed to call and interpret this tool.

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 are zero parameters, which is the baseline-4 case. The description explicitly states 'Takes no arguments', consistent with the empty schema, so nothing further is required.

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 (get) and resource (Oura profile + ring hardware), then enumerates the concrete fields returned: age, height, weight, sex, email, ring model/size/color/firmware/setup date, battery level. This is enough for an agent to distinguish it from siblings like get_daily_overview or get_trends without opening the 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?

Gives clear usage contexts ('questions about the person or the device', 'put scores in context, e.g. age next to VO2 max or cardiovascular age'), which is stronger than implied usage. However it never explicitly names an alternative tool or states when not to use it, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavioral context beyond them: the 404 on unknown ids, the 5-minute hypnogram resolution in local time, the downsampling cap of 120 points for HR/HRV, and the effect of raw:true.

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 action and payload, then usage, then edge cases. Every sentence carries information (return content, id source, error behavior, raw flag) with no filler.

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 fully compensates by enumerating what comes back and at what granularity. Combined with the error and raw behaviors, an agent has everything needed to call and interpret this tool.

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 100%, so both parameters are already documented. The description restates the raw flag's behavior ('raw: true returns Oura's original object') and the id's provenance, adding negligible meaning beyond the schema. 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 ('Get one sleep period in full detail by its sleep_id') and immediately distinguishes itself from list_sleep_periods by describing the extra payload (hypnogram, HR/HRV curves, readiness contributors). An agent can tell this apart from its siblings without opening a 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 states when to use it ('Use it to explain one specific night') and where the required id comes from ('get the id from list_sleep_periods or get_daily_overview first'). The alternative list tool is named, so routing is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: days without data are omitted, today is flagged in_progress, and today's partial activity is excluded from averages. It stops short of describing granularity/pagination behavior, but for a read-only aggregate this is strong disclosure.

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 sentences, front-loaded with the output shape then the routing guidance, then the edge-case behavior. The long metric enumeration is justified because no output schema exists to convey the return columns; every clause carries information.

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 correctly takes on the burden of describing the returned table and per-metric aggregates, and it also covers the two behaviors an agent could otherwise get wrong (missing days, in-progress today excluded from averages). An agent has everything needed to call it correctly.

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 100% and the single optional parameter is fully documented in the schema (default 14, range 1-90, inclusive of today). The description restates those same facts (default 14, up to 90, including today) without adding syntax or edge-case meaning beyond the schema, 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?

Specific verb ("Summarize") plus resource ("last N days") and an explicit enumeration of what the summary contains (readiness, sleep, activity, HRV, steps, stress, workouts per day). It is clearly distinguishable from siblings like get_daily_overview and the list_* tools 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 names the use cases ("week or month comparisons", "how am I trending" questions) and routes to alternatives with a condition: get_daily_overview for a single day, list_* tools for full detail on one data type. Nothing is left to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the 4 a.m.–4 a.m. Oura day boundary, partial today rows, missing days for no-data, sync latency before today's data appears, oldest-first ordering, and pagination via next_token. This is unusually rich behavioral disclosure.

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 scope, and every sentence carries information the agent needs. The opening field enumeration is long, but with no output schema it earns its place by telling the agent what data comes back.

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?

Even without an output schema, the description specifies the return shape ({ records, next_token }), ordering, pagination continuation, and the raw flag. Combined with the range semantics, an agent has everything needed to call and interpret it correctly.

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 100%, so the baseline is 3, but the description adds real meaning: end is inclusive, days is capped at 400 and ignored when start is set, and next_token should be re-passed for the rest. It stops short of adding syntax beyond the schema's YYYY-MM-DD format.

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 ('List daily activity') and enumerates exactly what each record contains (activity score and contributors, steps, calories, distance, activity minutes, sedentary/resting/non-wear hours, alerts). It also distinguishes itself from list_workouts, so an agent can tell it apart 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?

Explicitly routes usage: 'Use it for movement, step and calorie questions over a range; individual workouts are in list_workouts.' It also gives the default range (last 7 days) and the selection rule between start/end and days, leaving little to inference.

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

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

Annotations already declare read-only/idempotent, but the description adds materially new behavior: fields appear only on days Oura computed them (VO2 max and cardiovascular age are sporadic), the default window is 7 days, and the response includes an `unavailable` list for data types the user didn't grant. That permission-gap disclosure is exactly the kind of context 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-loads the resource and field list, then usage routing, then range rules and return shape. It is dense and somewhat long, but nearly every clause carries operational information that the schema does not.

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?

Despite having no output schema, the description documents the return shape ({ records } oldest first plus `unavailable`), data sparsity behavior, and full range semantics. An agent has everything needed to call and interpret the result.

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 100% so the baseline is 3, but the description adds real meaning: the range is inclusive, the default is the last 7 days, days caps at 400, and days is ignored when start is set. The inclusive semantic is not stated in the schema itself.

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?

Names a specific verb and resource (list per-day health metrics) and enumerates the exact fields returned: stress, resilience, SpO2, breathing disturbance, cardiovascular age, VO2 max, bedtime guidance. It explicitly distinguishes itself from siblings by noting readiness, sleep and activity scores live in their own list_* tools.

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?

States intended use ('for stress, resilience, breathing and cardio-fitness trends') and routes the agent away from this tool for readiness/sleep/activity via named sibling tools. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile, and the description adds substantial extra behavior: default 7-day window, 400-day cap, days ignored when start is set, inclusive bounds, oldest-first ordering, absent days for missing data, today only after ring sync, and next_token pagination. raw:true semantics (Oura originals vs friendly units) are also disclosed.

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 drivers before usage guidance, then range, return shape, and caveats. Dense but essentially waste-free; the contributor enumeration is long, though each item is a real field name an agent may need.

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 compensates by naming the return shape ({ records, next_token }), ordering, pagination contract, and the raw-vs-summary switch. Combined with full schema coverage and read-only annotations, an agent has everything needed to call and page this tool correctly.

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 100% so the baseline is 3, but the description adds meaning beyond the schema: start/end are inclusive, days is capped at 400 and silently ignored when start is set, and next_token is the continuation handle from a prior call. It does not restate the parameter formats, so it stays above rather than at baseline.

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 (list) and resource (daily readiness scores) and immediately defines the payload: score scale, Oura zones, the nine contributors, and temperature deviation. It explicitly distinguishes itself from get_daily_overview (single day) and get_trends (readiness next to sleep/activity), so an agent can route 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?

Gives explicit when-to-use plus two named alternatives with the conditions that select them: single day -> get_daily_overview, combined sleep/activity view -> get_trends. Range defaults and overrides are also stated, leaving nothing to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: default 7-day range, inclusive date semantics, days capped at 400 and ignored when start is set, oldest-first ordering, absent days, sync delay for today, and pagination via next_token. This is well beyond what annotations and schema alone convey, though a few operational details (unit of the score contributors, rate limits) remain unstated.

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?

A single dense but well-ordered passage: purpose first, then sibling routing, then range semantics, then return/pagination behavior, then the raw flag. Every sentence carries load and nothing is redundant.

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 compensates by describing the return shape ({records, next_token}), ordering, pagination loop, and edge cases (missing days, unsynced today). It is complete enough for an agent to call and page through results correctly.

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 100% so the baseline is 3, and the description exceeds it by clarifying the interplay between parameters (days is 'ignored when start is set', start/end are inclusive YYYY-MM-DD, raw returns Oura's original objects rather than friendly units). It reinforces and contextualizes the schema rather than merely restating it.

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 ('List daily sleep scores') and immediately distinguishes itself from siblings by naming list_sleep_periods and get_sleep_period with their respective scopes (hours/stages/HRV vs one night's hypnogram). An agent can route correctly 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 names the use case ('how well did I sleep' over a range) and then names the two alternative tools with the exact conditions that select each one. Nothing is left to inference.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description still adds non-obvious behavior: a 90-day default window, inclusive start/end semantics, the rule that any period overlapping the range is included, and the return shape ({ records, next_token }) plus what raw:true does. That is real added behavioral context rather than restating the safety profile.

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?

Three dense sentences with no filler; the entity definition, usage rationale, range rules and return contract each earn their place. Front-loaded well, though the middle sentence packs a lot into one clause chain.

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 conveys the return shape, pagination token, default window and range-inclusion rule, and gives concrete diagnostic use cases. Nothing an agent needs to call 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 coverage is 100%, so the baseline is 3, but the description adds range semantics the schema does not state: start/end are inclusive and overlapping periods are still returned. That extra meaning justifies a notch above baseline.

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?

Names a specific verb+resource and defines the domain entity in-line ('periods the user turns on when sick, injured or recovering'), including the shape of a period (start/end day, ongoing = no end, symptom tags). This clearly separates it from siblings like list_tags or list_daily_readiness.

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?

Gives concrete when-to-use cases: 'explain dips in readiness or activity' and 'check whether the user was unwell on given days', plus the default 90-day window and how to override it. It never names an alternative sibling or a when-not condition, so it stops short of full routing guidance.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: default 7-day window, days capped at 400 and ignored when start is set, days without data are absent, today's data only appears after ring sync, oldest-first ordering, and pagination via next_token. This is rich operational context that materially affects invocation.

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?

Dense but front-loaded: the core purpose leads, then routing, then range semantics, then return/pagination behavior. Every sentence carries information an agent needs, with no filler.

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?

Despite no output schema, the description specifies the return shape ({ records, next_token }), ordering, and how to continue pagination. Combined with annotations covering the safety profile, nothing needed to call 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%, so the schema already documents all five parameters. The description largely restates schema content (raw, days-ignored-when-start-set) but adds that start/end are inclusive, which is marginally useful. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (list mindfulness sessions in the Oura app) and enumerates the exact session subtypes and returned fields. It explicitly distinguishes itself from list_sleep_periods and list_workouts, so an agent can route correctly without opening another 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?

Names the concrete use case (questions about guided practice and its effect on heart rate or HRV) and explicitly routes sleep and exercise to the sibling tools. The when-to-use and when-not-to-use conditions are both present.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: rejected or deleted periods are excluded, each period is attributed to the wake-up day, days without data are absent, and today's data only appears after the ring syncs. It also documents pagination termination (call again if next_token is not null) and the raw:true escape hatch.

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?

Dense but front-loaded: purpose first, then routing to siblings, then behavioral/range/pagination details. Every sentence carries distinct information (exclusions, wake-up-day semantics, defaults, sync caveat, raw mode) with no filler.

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 compensates by specifying the return shape ({ records, next_token }, oldest first) and pagination behavior. Combined with the range defaults, exclusion rules and sync caveat, an agent has everything needed to call this correctly on the first try.

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 the schema already documents start, end, days, next_token, raw and include_naps. The description restates the same facts (inclusive YYYY-MM-DD, days up to 400 ignored when start is set) rather than adding new parameter-level meaning, so the 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+resource (list individual sleep periods) and immediately enumerates the fields returned (bedtime, hours in bed/asleep, stage hours, latency, efficiency, HR, HRV, breathing rate, readiness). It explicitly differentiates itself from list_daily_sleep (scores only) and get_sleep_period (full hypnogram), so an agent can route 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?

Gives explicit when-to-use ('sleep duration, stages and overnight HRV or heart rate across days') and names two alternatives with the exact condition that selects each ('list_daily_sleep for scores only', 'pass a sleep_id to get_sleep_period for the full hypnogram'). Nothing is left to inference.

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

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 goes further: it discloses the merge of classic and enhanced tags, the time-based sort order, the default range, the start/days precedence rule, and the `unavailable` field for ungranted data types. Since no output schema exists, this disclosure of return shape and permission gaps is genuinely valuable.

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?

A dense single paragraph but well front-loaded: purpose and examples first, then usage guidance, then range rules, then return shape. Every clause carries information, though the range/return details could be tightened.

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 steps in to describe the return value ({ records } oldest first, plus `unavailable`), and it fully explains scoping and the permission caveat. An agent has everything needed to call and interpret this tool correctly.

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 all three parameters (start, end, days) are already documented with formats and constraints. The description largely restates this (inclusive YYYY-MM-DD, days up to 400, ignored when start is set, 7-day default) rather than adding new semantics, so the baseline 3 is appropriate.

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?

Uses a specific verb (List) and resource (tags and notes the user logged), enumerates concrete examples (alcohol, caffeine, late meal, sickness, travel, custom tags), and describes how classic and enhanced tags are merged. It is immediately distinguishable from every sibling, none of which deal with tags.

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 states the diagnostic purpose ('Use it to explain unusual readiness or sleep') and names the follow-up tools (get_daily_overview, get_trends) for cross-checking. This is a clear when-to-use with alternatives, not just implied context.

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

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

Annotations already establish a safe, idempotent read, and the description adds substantial context beyond them: default 7-day window, inclusive date range semantics, days ignored when start is set, pagination via next_token, oldest-first ordering, the sync-lag caveat that today's data appears only after the ring syncs, and that days without data are simply absent.

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, then usage, then parameters, then return/pagination behavior — a sensible information hierarchy. It is dense and mostly earns its length, but several clauses (date format, day limits, raw semantics) repeat what the schema already states, costing some tightness.

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 list tool with no output schema, it covers everything an agent needs: result shape ({ records, next_token }), ordering, pagination loop, default range, sync-lag and missing-day caveats, and the raw escape hatch. Nothing material is left to inference.

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 the schema already documents all six parameters, and the description largely restates them (activity substring, days vs start, raw). It adds only marginal meaning, chiefly that start/end are inclusive and that the range defaults to the last 7 days, so the baseline 3 is appropriate rather than a higher score.

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?

Specific verb and resource (list workouts), plus scope detail: auto-detected vs manual, and the fields returned (activity type, label, intensity, source, times, duration, calories, distance). It explicitly distinguishes itself from list_daily_activity and get_heart_rate, so an agent can route 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?

Gives a concrete use case ('how many runs this month'), instructions for narrowing (activity with case-insensitive substring like 'run' or 'swim'), and names two alternatives with the exact condition that selects each — list_daily_activity for whole-day movement and get_heart_rate for in-workout heart rate.

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