oura

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

With annotations carrying only destructiveHint=true (and a title), the description does real work: it discloses that Oura verifies the callback URL before activation and that the subscription expires and must be renewed. It omits auth requirements and what the call returns (subscription id), so it is strong but not complete.

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 compact sentences, front-loaded with the core action, followed by the two behavioral facts an agent needs (verification, expiry) and the raw endpoint. No filler or repetition of the title.

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 mutation tool with no output schema and only destructiveHint in annotations, the description covers the critical lifecycle facts (verification handshake, expiry, renewal sibling) and the API endpoint. It does not mention permissions/scopes or the returned subscription identifier, leaving a small 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 description coverage is 100% for all four required parameters (callback_url, verification_token, event_type, data_type), so the schema already carries parameter meaning. The description adds no additional syntax, constraints, or format detail beyond the endpoint path, making 3 the correct 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 and resource ('Register a webhook so Oura notifies your callback URL when data changes') and clearly distinguishes itself from the renew/delete/list/get webhook siblings by naming the renewal path explicitly.

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 context for when this tool matters (subscriptions expire) and routes the agent to oura_renew_webhook_subscription as the follow-up alternative. It lacks explicit when-not-to-use guidance or comparison against oura_get_webhook_subscription / oura_list_webhook_subscriptions, so it falls 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 declare destructiveHint=true, so the description's addition of 'Notifications stop immediately' is genuine extra value about the side effect timing. It does not clarify whether deletion is reversible or whether the subscription could be re-created, leaving a minor gap for an irrecoverable mutation.

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, front-loaded sentences with no filler: the action first, then the key consequence, then the API mapping. 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 destructive call with no output schema, the description covers the action, the effect on notifications, and the endpoint. It lacks only error/not-found behavior and idempotency notes, which are minor.

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 is fully documented in the schema, so the description neither needs nor provides parameter details. 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 ('Remove a webhook subscription') and includes the exact API route, so the agent knows precisely what operation this performs and can distinguish it from the create/get/list/renew webhook 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?

There is no guidance on when to use this versus alternatives such as oura_renew_webhook_subscription, nor any statement of prerequisites, confirmation needs, or conditions under which deletion should be avoided. Usage is only implied by 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 declare readOnlyHint=true, so the description needn't explain safety. It adds the REST endpoint, which helps an agent map behavior, but does not mention error cases (e.g., missing id or invalid collection) or response shape, leaving behavioral gaps.

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, no waste, front-loaded with the core action. The endpoint reference is a compact addition.

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 fetch tool with full schema coverage, the description covers purpose, parameter provenance, and the underlying path. It omits error behavior and response format, which are minor given annotations and 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%, so each parameter is already documented. The description adds only that ids come from oura_list_documents, which is useful provenance but not syntax or format detail beyond the schema. 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 (fetch) and resource (a single document by id from one collection). It also names the sibling that produces the ids (oura_list_documents), distinguishing it from the list tool.

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 says ids come from oura_list_documents, giving clear upstream context. It does not state when-not-to-use this tool versus alternatives like oura_get_heartrate, but the collection-scoped fetch makes the scope obvious.

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 only declare readOnlyHint=true, so the description carries most of the behavioral burden and does so well: it explains that the collection is sampled continuously, which is why datetime (not date) parameters apply, and warns that the call can return a great many points. It also cites the underlying API endpoint for reference. It does not describe pagination mechanics or how to interpret the returned samples, which keeps it out of the top band.

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 sentences, all front-loaded: what it fetches, how it is scoped, and the practical caveat. Zero filler, and the endpoint citation is compact enough to help without bloating.

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, no-required-params endpoint with a fully documented schema and no output schema, the description covers purpose, timing semantics, and volume risk. The main omission is any hint about the shape or fields of a returned sample, which matters somewhat given there is no output schema, and the sandbox parameter is left entirely to the 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 description coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema by explaining the rationale for start_datetime/end_datetime over dates and by flagging latest as the escape hatch from a large result set. It pairs the two datetime params as a window rather than leaving them as isolated fields.

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 ('Fetch individual heart-rate samples') plus the scope constraint (DATETIME range). No sibling touches heart rate, so the resource alone cleanly separates it from the webhook/document/personal-info tools in the sibling set.

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 actionable usage guidance: narrow the window or pass latest, which tells the agent how to avoid an unusably large response. It stops short of naming explicit alternatives or when-not-to-use conditions, but the context it gives is clear and operationally useful.

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 readOnlyHint=true annotation already establishes this is a safe read, so the description only needs to add context. It does enlarge the picture usefully by enumerating the field set (substituting for the absent output schema), but says nothing about auth requirements, rate limits, or what happens if no ring/account data exists.

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 front-loaded sentence plus the raw endpoint reference; no padding, and the payload contents are stated before the implementation detail.

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-required-param, read-only tool with no output schema, the field enumeration adequately describes the return payload. Minor gap: no mention of auth/prerequisites or failure modes, and the sandbox parameter goes unaddressed.

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?

Only one optional parameter (sandbox), and schema description coverage is 100% — the schema itself explains that sandbox reads synthetic data. The description adds nothing about this parameter, 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 (fetch) and resource (the wearer's profile), then enumerates the returned fields: age, weight, height, biological sex and email. This is clearly distinguishable from siblings such as oura_get_heartrate, oura_get_ring_battery_level and the webhook/document 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?

The description says what the tool returns but never states when to reach for it versus the other Oura getters, nor any prerequisite (e.g. an authenticated wearer). For a zero-arg fetch the context is largely implied, but no explicit guidance or exclusions are offered.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds the REST endpoint and selection modes, but does not disclose pagination behavior, auth requirements, rate limits, or return format beyond what the schema implies.

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 the core purpose and scope front-loaded. The endpoint reference is compact and useful with no wasted words.

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 low-complexity, read-only data fetch with 100% schema coverage and a readOnlyHint annotation, the description covers the essential selection behavior. No output schema exists, but the return type (battery readings) is self-evident enough that this is nearly 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 coverage is 100%, so all five parameters are documented in the schema. The description echoes the range/latest distinction but adds no syntax, format, or interaction details beyond what the schema already provides, making the baseline 3 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 ('Fetch') and resource ('ring battery readings'), with the scope of a DATETIME range or latest reading. The resource clearly distinguishes it from siblings like oura_get_heartrate or oura_get_personal_info.

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 phrase 'over a DATETIME range, or just the latest' gives clear context for choosing between the two retrieval modes. It stops short of naming exclusions or alternatives, but for a simple read tool this is adequate 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=true, so the safe-read profile is covered. The description adds useful context by naming the returned fields, which partially compensates for the missing output schema, but it says nothing about auth requirements, error behavior for unknown ids, or expiry semantics.

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 packed sentences: the value statement first, then the underlying API path. Nothing is redundant or padded.

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 one-param read with annotations covering safety, the description is adequate, and it names the returned fields in lieu of an output schema. It remains thin on error/expiry behavior, 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?

With a single parameter at 100% schema description coverage, the schema fully documents subscription_id. The description adds no format or sourcing detail beyond what the schema 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?

States a specific verb and resource ('Fetch a single webhook subscription') and enumerates the salient payload fields (callback URL, event type, expiry). It is clearly distinguishable from the sibling list/create/delete/renew webhook 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?

The singular 'single subscription' wording implies retrieval by id versus oura_list_webhook_subscriptions, but there is no explicit when-to-use statement or precondition guidance. Usage is inferable from the name and siblings 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=true, and the description adds the underlying REST endpoint (GET /v2/usercollection/{collection}) and the date-range scoping. It does not disclose pagination behavior, rate limits, or auth requirements, so with annotations covering the safety profile this is adequate but not rich.

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 purpose and endpoint, and every clause in the enumeration earns its place by resolving an opaque enum. The long middle mapping is dense but functional; there is no redundant restatement of the title.

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 focuses on selection and scoping rather than return values. It covers collection semantics and the date range; the only meaningful gap is the undocumented sleep_time collection and no mention of how next_token pagination behaves in practice.

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, and the description goes beyond the schema by decoding the bare enum values into human-meaningful categories (daily_readiness = recovery, workout/session = exercise). It omits sleep_time, which appears in the enum but not in the mapping, and adds nothing on next_token or start/end date formats.

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 documents from one Oura collection over a date range') and explicitly positions it as 'the main read', distinguishing it from the single-document sibling oura_get_document. An agent can select it 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 strong selection guidance by mapping each collection value to its domain (sleep, recovery, movement, exercise, cardiovascular), effectively telling the agent when to choose which collection. It does not explicitly state when to use this vs oura_get_document or 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 declare readOnlyHint=true, so the safety profile is covered. The description adds the scoping detail that results are application-level subscriptions, but says nothing about pagination, ordering, or what an empty result means.

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, front-loaded sentences with the purpose stated first. The trailing 'Oura: GET /v2/webhook/subscription' is endpoint metadata rather than agent guidance, but it costs little and aids mapping.

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-parameter read-only list with annotations covering safety, the description covers what the agent needs to decide and call. The only real omission is the shape of the returned list, which is not documented anywhere 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4.

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 the webhook subscriptions') and scopes it to those 'registered for the application', which cleanly separates it from the singular get_webhook_subscription sibling. It does not explicitly name that sibling, but the plural/list framing is unambiguous.

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?

There is no explicit guidance on when to use this versus oura_get_webhook_subscription or the other webhook siblings. The list-vs-get distinction is inferable from the verb, but the description states no conditions, prerequisites, or alternatives.

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 annotation already flags destructiveHint=true, so the safety profile is partly covered, and the description usefully adds the lapse/expiry rationale that motivates renewal. It does not, however, explain what makes this 'destructive' (e.g., whether renewal resets state or changes the expiry window) or disclose the side effects of the PUT.

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 the core action front-loaded, followed by the motivating rationale and the underlying endpoint. Zero filler; the endpoint reference is the only marginally non-essential element.

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 mutation with annotations present and no output schema, the description covers the essentials. It still omits how far the expiry is extended, what the renewal returns, and any auth requirements, leaving the agent with gaps for a state-changing call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema description coverage, so the schema already documents subscription_id fully. The description adds no format, source, or retrieval guidance for the ID, 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 ('Extend a webhook subscription's expiry'), which is clearly distinct from the sibling operations create/delete/get/list. It is immediately clear what the tool does, though it doesn't explicitly name a sibling it must not be confused with.

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 usage context indirectly by explaining the consequence ('Oura subscriptions lapse if not renewed, so this is the tool that keeps a live integration alive'), which implies when to reach for it. However, there is no explicit when-not guidance, no mention of alternatives, and no prerequisites such as required auth scope.

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