Oura MCP

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

Annotations already cover readOnly/idempotent safety, and the description adds meaningful context beyond them: the comparison windows are personal 30-day and 90-day rolling baselines, and the return includes the raw value plus contextual framing. It omits an important edge case – what happens when the user has less than 30/90 days of history.

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 short sentences, front-loaded with the core operation, then usage triggers, then output framing. No redundant or filler text.

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 burden of explaining returns, and it does so at a high level (value plus personal context). It leaves the concrete response shape and insufficient-history behavior unstated, which is a minor but real gap.

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 schema already documents the metric enum, its upstream sources, and the local-date format. The description adds only the notion that the date is a 'single day' being compared, so 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?

Names a specific verb and resource (compare a single day's metric to 30/90-day rolling baselines) and implicitly distinguishes itself from absolute-value siblings like get_daily_summary or find_anomalies by framing results as personal-relative. An agent can identify the tool's role 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 explicit trigger phrasings: 'is this normal for me?' and 'how does today compare to my usual?'. It does not name an alternative tool or state when not to use it (e.g., instead of find_anomalies), 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 already declare readOnly/idempotent/openWorld, so the bar is lower, but the description adds real behavior: the returned statistics (mean/median/stdev/mean_delta_pct), a small_sample_warning flag when either group has <5 days, and the tag-exclusivity rule. It doesn't cover rate limits or tie-breaking, but for a pure analytics read this is solid added context.

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 computation, then triggers, then the hard constraints. No filler sentence; each clause carries either selection guidance or a calling constraint.

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?

There is no output schema, and the description does describe the key return fields (per-group stats, mean_delta_pct, small_sample_warning), so an agent knows what comes back. Minor gap: it doesn't frame the result as association not causation, but nothing needed to call the tool 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 baseline is 3. The description's 'provide exactly one of tag_type_code or custom_name' and 'strict YYYY-MM-DD local end_date' largely restate what the schema descriptions already say, adding little new syntax or example detail beyond them.

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: computes mean/median/stdev of a metric on tagged vs untagged days, plus mean_delta_pct. An agent can immediately tell this apart from sibling read tools like get_tags or get_daily_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?

Gives concrete user phrasings that should trigger this tool ('does alcohol hurt my sleep?', 'are tagged days worse for HRV?'), which grounds selection well. It stops short of naming alternatives (e.g. when to use get_tags or compare_to_baseline instead), so it is clear context without explicit exclusions.

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/openWorld, so safety is covered. The description adds genuinely new behavior: empty list plus insufficient_baseline=true when fewer than 14 non-null days exist, and the defaults (90-day window, 2σ). It does not say what each returned day record contains, but with no output schema this is a modest, not fatal, gap.

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?

Four tight sentences with zero filler: mechanism first, usage examples second, edge-case return behavior third, timezone caveat last. Nothing is redundant with the enum list or restates the tool name.

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 disclose the key success and failure shapes (list of anomalous days, or empty list with insufficient_baseline=true). What fields each anomalous day carries is left unspecified, which is the one remaining gap for an agent scoring results.

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 all four parameters, including the local-date constraint and defaults. The description restates the window and threshold defaults and re-emphasizes the LOCAL date format, which is reinforcement rather than new semantics. 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 precise operation: flag days whose metric deviates more than threshold_sigma standard deviations from the rolling-window mean. The statistical method is spelled out, making the output shape inferable. It does not name the closest sibling (compare_to_baseline), which handles a similar baseline-comparison question, so the agent must infer the boundary itself.

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 trigger phrasings ('when did my HRV crash?', 'pick out my worst sleep weeks') that make the intended question type obvious, plus an implicit when-not condition via the insufficient-baseline case. No explicit exclusion relative to compare_to_baseline, which is the main ambiguity an agent would face.

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?

The annotations already establish that this is a read-only, idempotent, open-world lookup. The description adds useful context about what the estimate is derived from and emphasizes the local-date constraint, but it does not describe return format, latency, or any data-availability caveats.

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 compact sentences with no waste. The core purpose is front-loaded, and the required date format follows immediately as an operational constraint.

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 one-parameter, read-only metric lookup with complete schema coverage and annotations, the description gives enough to call it correctly. The absence of an output schema means return details are not covered, but the core invocation requirements are 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 100%, and the single date parameter is already documented with the same YYYY-MM-DD local-date constraint. The description reinforces the format but does not add syntax or edge-case guidance beyond the schema 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?

The description uses a specific verb and resource: it gets Oura's cardiovascular-age estimate for a date and explains that this is a heart-health proxy derived from HRV and resting HR. It is clearly distinguishable from generic summary or heart-rate tools, though it does not explicitly contrast itself with siblings such as get_vo2_max.

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 implies the tool is used when a user wants the cardiovascular-age metric for a given date, and it specifies the local-date requirement. It does not say when to use this versus related metrics or when not to use it, leaving usage mostly implied.

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 readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered structurally. The description adds only the single-day scoping constraint and none of the useful behavioral context an agent might want here — e.g. that Oura attributes data to the day of wake-up, which the schema notes but the description does not, nor how it differs from get_last_night_sleep or get_morning_briefing.

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 short sentences: what it returns, when to use it, and where to go otherwise. Zero filler and the purpose is front-loaded ahead of the routing hint.

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 does tell the agent which three score families come back, and the scopes parameter lets it narrow the set. It stops short of describing the return shape or how a partial scopes selection affects the response, which slightly limits completeness.

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% and the date parameter already carries the important local-vs-UTC guidance. The description adds no parameter-level detail beyond implying a single-date scope, 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 and resource ('Get a single-day summary of Oura Ring data') and enumerates the domains covered (sleep, readiness, activity). It explicitly separates itself from get_date_range, so an agent can choose between them without opening either 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 a concrete trigger ('how was my [day]', snapshot of one specific date) plus an explicit exclusion routing range queries to get_date_range. Both the when and the when-not are stated.

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 readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds real value beyond them by disclosing which metrics are available and which underlying endpoints they come from, though it omits return shape (series of daily points) and any error/empty-data behavior.

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 tight sentences with zero filler: purpose first, then usage examples, then the routing rule to the sibling. Every sentence earns its place.

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 read-only projection tool with full schema coverage and no output schema, the description covers purpose, triggers, supported metrics and the alternative. The main remaining gap is not saying what the response looks like (one value per day, ordering, gaps), which matters for 'trend analysis'.

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 parameters' formats, local-date semantics and the 180-day cap are already fully documented. The description only re-states metric availability and clarifies kcal units, which is a marginal add over the schema's own endpoint mapping.

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 a single metric over a date range') plus its analysis purpose (trend analysis). It explicitly contrasts with the sibling get_daily_summary for single-day snapshots, so an agent can pick correctly without inspecting 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 user-question triggers ('how was my sleep this week', 'show me my HRV over the past month') and names the alternative with the condition that selects it ('For a single-day snapshot, use get_daily_summary'). Nothing essential 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 declare readOnlyHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds the 24-hour window ceiling and bucketing granularity, but does not cover rate limits, gaps in data, or what points look like when no readings exist. Adequate but not rich beyond structured fields.

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, zero filler. The operational scope comes first and the alternative is deferred to the end where it belongs.

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?

Three flat parameters, fully documented schema, and no output schema to explain, so the description only needs to establish scope and routing, which it does. A brief note on expected density or empty results would push this higher, but nothing essential for correct invocation 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%, with the 24h max stated on `end` and the resolution default/enum documented inline, so the schema carries the parameter burden. The description's "bucketed to 5min/15min/raw" restates the enum rather than adding format or interaction detail. 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?

States a specific verb and resource ("Get intraday heart-rate time series"), plus the scope constraint (24-hour window) and available resolutions (5min/15min/raw). An agent can distinguish it from multi-day metric tools 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?

Explicitly names when to use it ("HR patterns within a day (sleep, workout, stress events)") and names the alternative for the other case ("For multi-day trends, use get_date_range with metric=resting_hr instead"), including the exact argument to pass. get_date_range is a real sibling, so the routing is actionable.

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 readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value beyond that by disclosing the return content — scores, stage breakdown, timing, heart-rate metrics — which matters since there is no output schema. It does not say what happens when last night's data is missing or how time zones are handled.

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 short sentences, front-loaded with the action, then the trigger, then the return shape. Every sentence earns its place with no repetition of the title or schema.

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 parameters and no output schema, the description covers what the tool returns and when to call it, which is enough to invoke correctly. The only meaningful gap is edge-case behavior (no data recorded, staleness of 'last night'), which slightly limits completeness.

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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies the night is implicit rather than parameterized.

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 — retrieve detailed sleep data for the most recent night — and scopes it to a single night, which distinguishes it from get_date_range and get_daily_summary without ambiguity.

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 triggering utterance ("how did I sleep last night") and the general condition (user wants the latest sleep details), which is strong positive guidance. It does not name an alternative for retrieving older nights' sleep data, so the agent gets no explicit when-not.

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?

The annotations already establish readOnly, openWorld, and idempotent behavior, so the bar is lower. The description adds useful non-obvious context by explaining that the server returns raw fields and the agent decides what to highlight, though it does not discuss empty data or error behavior.

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 purpose, then usage, then return behavior and parameter guidance. Every sentence earns its place and there is 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?

For a one-parameter read-only overview tool with no output schema, the description is substantially complete: it covers purpose, when to use, raw-field return behavior, and date format. The main remaining gap is that it does not explicitly disambiguate from siblings such as get_daily_summary.

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 date parameter's format and local-date semantics are already documented in the schema. The description reinforces the same point with 'strict YYYY-MM-DD' but does not add new parameter meaning 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 description gives a specific verb and composite resource: a structured 'how am I today' snapshot composed of readiness, recommended sleep, yesterday's sleep, activity, stress, and tags. It also distinguishes this from individual metric tools by calling it a single overview call.

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 explicitly says to use this when the user opens the day and wants a single overview call, which gives clear usage context. It does not name alternatives or state when not to use it, so it falls short of full when/when-not 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 already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds genuine value by disclosing the return fields (start/end HH:MM in local time, status, recommendation), which is important since there is 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?

Two tight sentences with zero waste; the core purpose is front-loaded and the date-format constraint follows.

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 one-parameter read tool with no output schema, the description covers purpose, input format, and return shape adequately. It could mention timezone edge cases or what status values mean, but nothing essential to a correct call 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% and the schema already documents the single date parameter as the user's LOCAL date in YYYY-MM-DD. The description only restates that constraint ('strict YYYY-MM-DD') without adding new semantics, 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 and resource ('Get Oura's recommended bedtime window for a date') and even specifies the return shape (start/end HH:MM, status, recommendation). The resource is unique among siblings, though the description never explicitly contrasts it with get_last_night_sleep or get_daily_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?

Usage is implied by 'for a date' and the strict date-format instruction, but there is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives such as get_last_night_sleep for actual sleep data.

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 readOnlyHint, idempotentHint and openWorldHint, so safety is covered; the description adds real value by naming the exact scale values (limited → exceptional) an agent will see and by stressing the LOCAL date requirement. It stops short of saying what happens when no data exists for the given date.

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 tight sentences: the action first, then the metric definition, then the level scale and the date constraint. No filler, and the critical constraint is front-loaded.

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 one-parameter read with no output schema, the description is nearly complete — it explains the metric and enumerates the possible returned levels. The main omission is behavior on missing/empty data for a date, which an agent cannot infer.

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% and the single parameter already documents the pattern and "user's LOCAL date", so the description largely restates the schema. The added emphasis on "strict YYYY-MM-DD" reinforces the format but introduces no new semantic information.

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 the resilience score for a date") and defines the metric as Oura's long-term stress-recovery capacity, which implicitly separates it from siblings like get_stress. It never names an alternative tool explicitly, so sibling differentiation is inferential rather than stated.

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?

Usage is only implied by the definition of the metric; there is no explicit statement of when to call this versus get_stress, get_daily_summary, or compare_to_baseline. The level enumeration hints at what the tool returns but not when to prefer it.

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 and open-world, so the safety profile is covered. The description adds real behavioral constraints — local-time semantics and a hard 365-day cap — but says nothing about return shape, whether periods are clipped to the range, or how ongoing/open periods are represented.

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, zero waste, with the resource definition front-loaded and the invocation constraints second. Every clause carries content.

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 two-parameter read tool with full schema coverage and annotations, the description is nearly sufficient. The remaining gap is what the returned periods look like and whether boundary/ongoing periods are included, which matters since there is no output schema.

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 schema already documents both dates as local YYYY-MM-DD with the 365-day max on end. The description's 'strict YYYY-MM-DD' and 'LOCAL' are reinforcement rather than new information, 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 rest-mode periods) and glosses the concept as illness/recovery markers, which no sibling covers. It doesn't explicitly contrast with siblings like get_daily_summary, but the resource is distinctive enough to select on.

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?

Usage is only implied by the date-range framing; there is no statement of when to reach for this versus get_daily_summary or get_tags, nor when-not. For a narrow, single-purpose resource this is tolerable but not helpful 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 already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description's only behavioral addition is the local-date/format constraint and date-range scoping, both of which are largely mirrored in the schema; it does not describe return shape, ordering, or empty-range behavior.

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, followed by the one non-obvious input constraint. 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?

For a simple two-parameter read tool with full schema coverage and annotations declaring a safe read, this is nearly complete. The only gap is that without an output schema, nothing tells the agent what fields a returned session record contains.

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% and the schema already documents both start and end as local YYYY-MM-DD, including the 180-day max on end. The description reinforces the local-date convention but adds no new syntax or semantic detail, 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 ('List mindfulness sessions') plus the domain covered (meditation, breathing, relaxation). It is clear what the tool returns, but it does not explicitly differentiate itself from siblings like get_workouts or get_daily_summary, which an agent may also consider for activity data.

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 instruction to pass LOCAL dates in strict YYYY-MM-DD implies the usage context (querying a history window), but there is no guidance on when this tool is preferred over alternatives or what happens outside the date range. Usage is implied rather than stated.

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 readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds the returned metric names and the local-date constraint, but says nothing about data availability (e.g. nights with no recording), units, or typical value ranges.

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 short sentences with the metric definition front-loaded, then use cases, then the calling constraint. 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 is careful to name the two values returned, which is the key missing piece an agent would otherwise lack. It could still say what happens for nights without data, but it is otherwise sufficient for a single-parameter read 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% and the schema already specifies the YYYY-MM-DD pattern and local-date semantics, so the description's date instruction is largely redundant. Baseline 3 applies since 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 (get) and resource (nightly SpO2 average plus breathing disturbance index) and scopes it to a single date. The named metrics distinguish it cleanly from sibling tools like get_heart_rate_series or get_daily_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?

Gives concrete use cases (altitude effects, suspected sleep apnea, illness tracking), which tells an agent when this tool is the right pick. It stops short of naming alternatives or exclusions, e.g. when to prefer correlate_tag_with_metric or get_daily_summary instead.

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 readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds genuinely useful context the annotations lack: the payload contents (high-stress and recovery seconds) and the requirement that the date be the user's LOCAL date rather than UTC, a real source of off-by-one errors.

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, zero filler, with the what and the how-to-call-it front-loaded. Nothing could be removed without losing 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?

For a single-parameter, read-only metric fetch with no output schema, the description discloses enough: what is measured, in what unit-framed terms, and which calendar the date follows. Minor gaps remain around behavior when no data exists for a date (empty vs error), but overall it is sufficient to call 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% and the date parameter already carries the pattern and local-date note, so the description largely repeats structured data. The emphasis on 'strict YYYY-MM-DD' and LOCAL is a mild reinforcement but adds no new syntax or meaning.

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 (get) and resource (daily stress metrics) and even enumerates the returned measures: high-stress and recovery seconds. It does not, however, distinguish itself from adjacent siblings like get_resilience or get_daily_summary, which also touch stress/recovery data.

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 second sentence only gives the parameter format, not when to choose this over get_daily_summary, get_resilience, or get_date_range. There is no stated prerequisite or exclusion, leaving usage to inference from the tool name.

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 readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds that tags are user-annotated with examples, but does not disclose return format, pagination, or other behavior beyond what annotations and schema already provide.

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 core purpose, then usage and formatting notes. No filler or redundancy.

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 read-only list tool with 2 required parameters, no output schema, and annotations covering safety, the description provides enough to call it correctly. It could be slightly more complete if it hinted at the return shape or explicitly distinguished it from correlate_tag_with_metric.

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%, and both start and end are documented with local date format and a 180-day max for end. The description's emphasis on 'LOCAL dates as strict YYYY-MM-DD' largely repeats the schema, so 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?

The description clearly states the verb and resource: 'List user-annotated tags' over a date range, with concrete examples (caffeine, alcohol, late meal, custom notes). It does not explicitly differentiate from the sibling tool correlate_tag_with_metric, so it falls short of a 5.

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 provides a usage hint ('correlate behaviors with sleep/readiness or to recall what was logged'), but does not say when to use this tool instead of the dedicated correlate_tag_with_metric sibling or other alternatives. This is implied guidance rather than explicit routing.

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 readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so safety behavior is covered. The description adds meaningful behavioral context beyond annotations: a 30-day lookback window and the fact that measurements may be sparse due to how Oura computes VO2 max.

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 short sentences, front-loaded with the core action and immediately followed by the key caveat and input format. No wasted words; every sentence earns its place.

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 single-parameter, read-only lookup with annotations covering safety, the description is nearly complete: it explains the window, sparsity, and date format. The only minor gap is not stating what is returned when no measurement exists, but no output schema is present and the core behavior is clear.

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%, and the sole parameter is fully documented in the schema with the YYYY-MM-DD pattern and local-date requirement. The description reinforces the local-date and strict format requirement but adds no syntax or interpretation beyond what the schema already provides, 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?

The description states a specific verb and resource: 'Get the most recent VO2 max measurement within 30 days of the queried date.' It is clear what the tool does, but it does not differentiate from related siblings like get_cardio_age, which could also cover fitness metrics.

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?

Usage is implied — use this tool when you need a VO2 max value near a given date. The description adds useful context that measurements may be sparse because they come from outdoor walks/runs, but it never explicitly states when to choose this over alternatives or what to do if no measurement exists.

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 and openWorld, so the safety profile is covered. The description adds real value beyond that: the window bounds (1-28), the default (7), the aggregation shape, and the requirement to pass the user's LOCAL date in strict YYYY-MM-DD format.

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 short sentences, front-loaded with the core capability, then the trigger condition, then the critical formatting constraint. No filler and nothing important buried.

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?

There is no output schema, so the description usefully sketches the return shape (per-metric mean/min/max) and defines the input's local-date convention. It doesn't say which metrics are covered or how missing days are handled, but the essentials for a correct call are present.

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 in the schema, establishing a baseline of 3. The description's notes about the default window and the local/strict date format largely restate the schema rather than adding new syntax or edge-case meaning.

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 a 1-28 day window of daily Oura metrics') plus the aggregation performed (per-metric mean/min/max), so the agent knows exactly what it retrieves. It does not explicitly differentiate itself from siblings like get_daily_summary or get_date_range, which is the only thing keeping it from a 5.

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 trigger phrase ('how was my week') and the general intent ('scan the past N days at a glance'), which is enough to route most requests correctly. It never states when NOT to use it or names the sibling tools that handle single-day or raw-range queries.

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 disclose readOnlyHint, openWorldHint, and idempotentHint. The description adds that workouts may be logged or auto-detected and emphasizes local dates, but it does not describe return shape, pagination, or limits beyond what the schema states.

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 tightly written sentences with no filler. The primary action and the key date-format instruction are front-loaded, and the usage context follows naturally.

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 read-only list tool with full schema coverage and annotations, the description is largely complete. It omits details about returned workout fields, but that is a modest gap rather than a blocking one.

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 both start and end dates with patterns and local-date guidance. The description reinforces the strict YYYY-MM-DD local-date requirement but adds little 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 description gives a specific verb and resource: "List workouts" over a date range, with additional context about logged/auto-detected workouts. It does not explicitly distinguish this tool from related siblings like get_sessions or get_daily_summary, so it falls short of a 5.

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 states clear usage contexts: exercise/training questions and correlating workouts with recovery. It does not mention when not to use it or name alternative tools for overlapping needs, but the positive guidance is explicit.

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?

Adds genuine value beyond annotations: discloses the exact return payload shape and the important trait that it makes no upstream Oura call (no latency/quota cost). Annotations already cover readOnly/idempotent/no-open-world, so this is solid extra context without full failure-mode detail.

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 short sentences, front-loaded with the return value, then purpose, then the negative scope. Zero 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?

For a zero-param health-check tool with annotations covering safety, the description covers return shape, purpose, and isolation from the backend. Nothing needed to call it 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?

Zero parameters, so baseline is 4; the description correctly requires no argument input and instead describes the output shape.

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: states it returns {ok: true, user_id} and its purpose is verifying auth + connectivity. Explicitly states 'Does not call Oura,' which cleanly distinguishes it from all 19 data-fetching 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?

Implied usage is clear — call this to verify credentials/connectivity before other calls. It explicitly rules out the data-fetching use case of siblings, but doesn't say e.g. 'use as a first-call handshake' or when-not-to-call.

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