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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower; the description still adds real value by disclosing the output boundary and a security guarantee ('Never shows the secret or tokens'). It does not mention that no network call is needed or what happens when credentials are partially configured, but for a zero-parameter local status probe this is strong.

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?

One front-loaded sentence names the two conditions checked and enumerates the returned details, and a second short sentence delivers the confidentiality boundary. No filler, nothing restated from the schema or annotations.

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 input schema, no output schema, and no annotations gaps beyond the standard safety hints, the description carries the whole burden of explaining what comes back and it does so concretely. An agent knows enough to call it and interpret the result without further documentation.

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 clarify; baseline 4 applies. The description's field list refers to return values rather than inputs, which is appropriate here.

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 pair: reports whether Withings credentials are configured and whether access has been authorized, plus exactly which fields come back (token file location, scopes, minutes remaining). This is clearly distinguishable from the sibling auth tools start_authorization and exchange_code, which perform the flow rather than report on it.

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 rather than stated: an agent can infer this is the diagnostic step for the Withings auth flow, but the description never says when to call it versus start_authorization or exchange_code (e.g., 'call this first to decide whether authorization is needed'). No exclusions or prerequisites are given.

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 substantial context beyond the annotations: codes expire in 30 seconds, are single-use, and the resulting tokens are written to a local file with chmod 600 and never returned. This makes the non-idempotent, non-readable outcome concrete. It does not explain failure modes (e.g., what happens on an expired or already-used code).

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, front-loaded with the scoping condition, and each subsequent sentence contributes distinct information (input form, expiry/churn caveat, side effect). 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 single-parameter tool with no output schema, the description covers where the result goes (local token file), why nothing is returned, and the operational risk of short-lived one-time codes. An agent has everything needed to call it correctly or route to the CLI.

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 description already documents that the URL contains ?code=...&state=... or the code alone. The description restates the same flexibility ("full URL ... or just its code") without adding format or validation 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 (finishes the one-time authorization) plus the precise scope condition (callback URL is not on localhost). Combined with sibling names like start_authorization and auth_status, an agent can immediately place this as the second step of the OAuth flow.

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 an explicit when-condition (non-localhost callback), implies the inverse case where it isn't needed, and names a concrete alternative invocation (`node server/cli.mjs authorize`) with the reason to prefer it. The accepted input forms are stated inline.

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 open-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: empty results if no data exists, a default 30-day window, and a 366-day cap, which an agent needs and the annotations do not 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 tight sentences, front-loaded with the returned metrics, followed by the empty-result behavior and date-range defaults. 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 two-parameter read tool with full annotation coverage and no output schema, the description gives the important call-shaping details: what fields come back, what an empty response means, and default/max date ranges. It does not mention ordering or multiple readings per day, but nothing critical for calling the tool 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 a constraint not present in the schema: the 366-day maximum range. It also restates the 30-day default in a more usable form, which helps an agent set start_date/end_date correctly.

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 the exact resource and metrics returned (systolic/diastolic mmHg plus pulse bpm) and the data source (Withings BP monitor). This clearly separates it from siblings like get_body_measurements, get_sleep_summary, and get_daily_activity.

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 implies when the tool applies by naming the data it returns and notes the default window (30 days) and maximum (366 days), but never states when to prefer this over get_body_measurements or other health tools. No explicit exclusions or alternatives are given.

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), yet the description adds genuinely useful behavior: units are decoded, metrics the scale didn't measure return null, and range is capped at 366 days. These details are not derivable from the annotations and prevent misinterpretation of nulls as zeros.

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 date-range scope, then the metric inventory, and closes with defaults. The metric list is long but each item earns its place as return-value content; otherwise no wasted prose.

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-output-schema tool, it covers the essentials an agent needs: what rows represent (one per step-on), what fields appear, null semantics, and date-range defaults/limits. Only the manual-entry parameter behavior is left 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?

Schema coverage is 100%, so both date parameters are already documented, and the description's default/limit note largely reinforces 'Default: 29 days before end_date.' It adds nothing about include_manual (manual vs device entries), so it does not meaningfully exceed 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?

States a specific verb+resource ('Weigh-ins in a date range') and enumerates the exact metric fields returned, including cardio-scale-only extras. An agent can immediately distinguish this from get_blood_pressure or get_daily_activity 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 operating context: default window of last 30 days and a hard ceiling of 366 days, which guides how to call it. It does not explicitly name when to prefer a sibling (e.g., a blood-pressure readout) or state exclusions, so it falls short of the top band.

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 openWorld, so the safety profile is covered. The description adds genuinely new context: it discloses the data source (a Withings watch or the app's own step tracking) and the retention/query ceiling of 366 days, which the annotations cannot convey. It stops short of saying what happens when no device 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?

Two sentences: the first front-loads what a row contains, the second front-loads the default and the limit. There is no filler, hedging, or repetition of schema 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 describing return values and does so concretely by listing the per-day fields and the row granularity. Data provenance is noted, but units, timezone handling, and behavior on empty/missing device data are left unstated.

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 both date parameters are fully documented, so the schema does the heavy lifting and a 3 is the baseline. The description does contribute the 366-day cap, which is not in the schema, but adds no date-format or timezone nuance beyond what the parameter descriptions already state.

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 names the resource (daily activity) and enumerates the exact per-day metrics returned — steps, distance, floors, minute buckets, calories, heart rate, HR-zone minutes — which effectively separates it from siblings like get_sleep_summary and get_body_measurements. It lacks an explicit verb but the 'one row per day' framing makes retrieval 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?

It states the default window (last 7 days) and a maximum span (366 days), which gives practical range guidance. However, it never says when to choose this tool over the other health-data siblings, nor any exclusions or prerequisites (e.g. device pairing or auth), so usage is only 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/idempotent/non-destructive, so safety is covered; the description adds real value beyond them with the day-labelling convention and the range cap of 366 days. It does not disclose what happens when no device/data exists for a night, which is the main remaining behavioral 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?

Front-loaded with the source and contents, then defaults and limits in a short trailing sentence. The metric list is long but each item is informative for an agent deciding whether this is the right tool; no filler sentences.

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 responsibly enumerates the returned fields, and it states defaults, range cap, and date semantics. Missing only edge-case behavior (missing nights, multiple devices, per-night vs aggregated) for a full 5.

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% with per-param descriptions, so baseline is 3; the description adds a constraint not present in the schema (maximum 366-day span) and corroborates the 7-day default. That is modest but genuine added meaning over 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?

Specific verb+resource ('Nightly sleep from a Withings sleep mat or watch') with an explicit enumeration of the metrics returned (total sleep, time in bed, stage minutes, efficiency, latency, score, HR/BR, snoring, disturbances). This clearly separates it from siblings like get_body_measurements, get_blood_pressure, and get_daily_activity.

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 defaults (last 7 days) and an explicit ceiling (up to 366 days), plus the non-obvious rule that a night is labelled by the day it ends. It doesn't explicitly name alternatives or when-not to use it, but the domain boundary against the other health-data siblings is evident.

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 open-world behavior, so safety is covered. The description contributes beyond that by disclosing the freshness field ('last time each synced') and explicitly what is excluded ('No serial numbers or ids') — valuable because there is no output schema to reveal the response shape.

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 clauses: the resource plus its returned fields first, then the diagnostic use case, then the exclusion note. Every phrase carries information and nothing is repeated.

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 and no parameters, the description must carry the return-value burden, and it does so by enumerating the fields plus what is omitted. Minor gaps remain (ordering, whether an empty list is possible, whether auth is required), but nothing critical to 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is applied. The description does not waste space restating an empty 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?

Names the specific resource (Withings devices linked to the account) and enumerates exactly what it exposes: type, model, battery level, firmware, last sync. The verb is only implied by the name/title rather than stated in the description, and it does not explicitly contrast itself with the data-fetching siblings, but the resource is unmistakable.

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 parenthetical 'useful when data looks missing' gives one concrete diagnostic scenario, which is real usage guidance. However, no alternatives are named (e.g. auth_status for connection problems) and there is no when-not guidance, so routing is only weakly supported.

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 real context beyond the annotations: the granted scopes are read-only, the local listener has a 10-minute lifetime, the manual path has a 30-second window, and the only write is the local token file. This productively reconciles readOnlyHint=false with an otherwise non-destructive flow. It does not say what the URL or returns look like on failure/timeout, leaving a small 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?

Front-loads 'One-time setup step' and the return value, then branches cleanly into the localhost and non-localhost paths. Dense but nearly every clause carries information; the parenthetical CLI mention is the only mild noise.

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 states what is returned (the authorization URL), what side effect occurs (local token file), and how the flow completes in each deployment scenario. An agent has everything needed to call it and hand off 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?

There are zero parameters, so the baseline is 4. The description adds relevant meaning by naming the exact scopes (user.info, user.metrics, user.activity) the resulting token will carry, which the empty schema cannot convey.

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 (one-time setup) and resource (Withings authorization URL), and explicitly names the scopes granted. It is clearly distinguishable from siblings exchange_code (the follow-up step) and auth_status (the check), which it references by name.

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 routing: if the callback is on localhost the server self-completes in 10 minutes; otherwise the user must run exchange_code (or the CLI) with the redirect URL within 30 seconds. Both the alternative tool and the condition that selects it are spelled out.

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