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

Annotations only declare the safety profile (idempotentHint, destructiveHint=false, non-read-only). The description goes well beyond: no rollback of already-committed SQLite records, possible incomplete counts, terminal status returned for finished jobs, status=error for unknown/foreground jobs, and no new cloud request.

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?

Purpose and scope are front-loaded in the first clause, and every sentence conveys a distinct fact (rollback behavior, error cases, alternatives). It is dense, but a couple of semicolon-chained clauses could be trimmed without losing meaning.

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, yet the description explains the return value (terminal job status, finished jobs returned unchanged) and the error case. Combined with the mutation caveats and alternatives, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% for the single sync_id parameter, so the schema already documents its meaning and the required/minLength constraints. The description's 'exact sync_id' adds only a mild emphasis on exactness, 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 with scope: 'Cancel a queued/running background MCP sync by its exact sync_id.' It is immediately distinguishable from siblings like get_sync_status (inspection) and sync_data (resumption), which the description itself names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'Use get_sync_status to inspect progress and sync_data with user consent to resume via a new job.' It also states when the tool is inapplicable (unknown IDs, foreground jobs) and what those cases return.

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 description openly discloses network contact and credential rotation ('May contact Xiaomi, authenticate and rotate credentials in the local keyring'), which complements the readOnlyHint=false annotation. It also adds conditional behavior not in the annotations: while syncing, it 'reports existing connection state instead of probing.'

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 compact and every sentence earns its place: purpose, side effects/prerequisites, return fields, conditional behavior, and the alternative tool are all covered without redundancy. It front-loads the main purpose before adding supporting 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?

Despite having no output schema, the description enumerates the returned fields and conditional additions such as connection_state, region, last_connection_error, and sync_in_progress. It provides enough behavioral and environmental context for an agent to invoke the tool correctly, including prerequisites, side effects, and sync-time behavior.

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 input schema is empty, so no per-parameter explanation is required; the baseline for zero parameters is 4. The description still adds useful input-level guidance by requiring interactive CLI setup and forbidding credentials in tool arguments, though that is mostly a usage constraint rather than parameter 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?

The first sentence names the exact operation ('Check whether the configured Mi Fitness account can connect') and positions it 'before requesting a sync,' clearly distinguishing it from sync_data. It also explicitly routes coverage queries to get_data_coverage, preventing confusion with a sibling 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?

The description gives a clear precondition ('Requires local interactive CLI setup, never credentials in tool arguments') and a temporal trigger ('before requesting a sync'). It also provides an explicit alternative with 'For cached date coverage use get_data_coverage' and notes that it 'does not sync health records,' acting as a when-not condition.

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, idempotentHint, destructiveHint, openWorldHint. The description adds valuable behavioral context: read-only local SQLite query, no cloud request, requires configured account/cache, and important caveats about date coverage and empty-list meaning. It enhances rather than contradicts annotations.

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?

Every sentence earns its place: purpose, usage timing, exclusions, behavior, caveats, prerequisites, and return format are all covered without redundancy. It is front-loaded with the core purpose and then provides necessary details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having only one optional parameter and no output schema, the description fully explains the return structure, meaning of empty lists, the non-guarantee of uninterrupted coverage, and the distinction from related tools. Nothing needed 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% for the single data_types parameter, which already explains 'Optional dataset names to inspect; omit or [] for all cached datasets.' The description restates this in prose but adds no new semantic meaning beyond the schema, so the baseline of 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 'Inspect' and resource 'date ranges in the local cache', and immediately differentiates from siblings by naming get_connection_status and get_sync_status for other concerns. It leaves no ambiguity about what this tool does.

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 states when to use ('before choosing query dates or requesting sync_data') and when not to use it, naming the exact alternatives for cloud connectivity and background job status. This is model usage 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/non-destructive/closed-world, yet the description adds real context beyond them: no cloud request, no cache write, the returned JSON shape (status, source, data.profile fields), the guarantee that credentials and plaintext account IDs are never returned, and status=error behavior when disconnected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the core purpose leads, followed by behavioral guarantees, error handling, and the sibling routing hint. Every sentence earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by describing the return payload (status, source, data.profile contents) and error semantics. Combined with the routing guidance, an agent has everything needed to call and interpret it correctly.

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

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

The tool takes zero parameters, so the schema carries nothing and the description need not add parameter meaning. Baseline of 4 applies; no syntax or format gaps exist because there is nothing to pass.

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 (Read) and resource (minimal metadata for the already-connected local account) and explicitly disambiguates from a medical/demographic profile. An agent can distinguish it from siblings like query_body_measurements or query_daily_activity immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use (read connected account metadata), a fallback for the disconnected case (get_connection_status can establish/check first), and a routing alternative (query_daily_activity for activity totals). Nothing is left to inference.

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

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

Goes well beyond the annotations: clarifies this is a local lookup with no cloud request, documents the 500-job retention window per account, states that unknown/expired IDs return status=error rather than failing silently, and notes that restarted lookups omit raw error text for privacy. These are behavioral facts an agent could not infer from readOnlyHint/idempotentHint alone.

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 core purpose and return shape before the state list and routing guidance, and every sentence carries information. It is dense with four packed sentences, but none are wasted or redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still enumerates the returned fields and the complete state vocabulary, plus edge-case behavior for expired IDs and restarted processes. An agent has everything needed to call it and interpret the response correctly.

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

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

Schema description coverage is 100%, so the schema already defines sync_id, its format source, and that it is not a workout ID — establishing the baseline of 3. The description reinforces the lookup semantics (works after a restart, unknown IDs yield status=error) but adds no new syntax or constraint 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?

States a precise verb and resource ('Read one MCP sync job by sync_id') and enumerates the returned fields and the full set of possible states. An agent can distinguish it from get_connection_status and query_sync_history without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes to alternatives with conditions: query_sync_history to discover IDs, cancel_sync to stop a live job, get_connection_status for cloud connectivity. Also names the inverse relationship (IDs come from sync_data or query_sync_history), so the when-to-use picture is complete.

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

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

Annotations already declare the safe read-only profile, but the description adds substantial context beyond them: no cloud request or automatic sync, cache-only results, empty list means no cached matches rather than no measurements, events are upstream flags not a diagnosis, and 'keep filters unchanged and avoid syncing between pages' for stable pagination. That is exactly the kind of behavioral nuance annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and range semantics are front-loaded before the caveats, and almost every sentence carries operational value. It is slightly dense and mildly redundant in flagging empty-list interpretation twice, which keeps it from a 5.

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 supplies the return shapes (data.events fields, data.count, data.pagination with next_offset), pagination termination behavior, precondition (configured local account/cache), and error-surrogate semantics. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so start_date, end_date, limit and offset are already fully documented with patterns, defaults and bounds. The description reinforces the default of 5000 and the offset-for-paging workflow but adds no format or constraint detail the schema lacks, 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 (Read) and resource (device-reported abnormal-heartbeat events) plus the scoping dimension (inclusive YYYY-MM-DD range). It explicitly distinguishes itself from the sibling query_heart_rate, so an agent can route 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?

Names the alternative (query_heart_rate for ordinary bpm samples) and the condition for choosing it, and routes to get_data_coverage for availability checks and sync_data for refreshes. It also warns that this is a local cache query requiring a configured account, which is genuine when-to-use 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 establish read-only, idempotent, non-destructive behavior, but the description goes well beyond: local SQLite query with no cloud request or sync, requirement of a configured local account/cache, and the crucial semantic that empty lists mean no cached matches rather than zero measurements. It also discloses that latest_only selects before pagination and that next_offset is null at the end.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, followed by return shape, semantics, sibling routing, and caching caveats. It is dense and slightly run-on, but nearly every clause carries distinct information and nothing is padding.

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-shape burden and does so thoroughly (data.measurements, data.count, status, source=cache, generated_at, pagination with next_offset). For a 6-param read tool with sibling alternatives, nothing an agent needs to invoke 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: units (kg, percent, dimensionless), the clarification that latest_only returns the last record rather than the latest value per field, and metric-projection behavior with absent fields omitted rather than zeroed. These complement rather than merely restate 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?

States a specific verb ('Read') and resource ('timestamped body measurements') with scope ('inclusive YYYY-MM-DD range'). It explicitly distinguishes itself from the sibling query_metric_series, so an agent can route correctly 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?

Names the alternative ('Use query_metric_series(metric=weight_kg) for a daily or aggregated weight trend') and points to get_data_coverage and sync_data for availability and refresh. It also warns to keep filters unchanged and avoid syncing between pages, which is genuine 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 cover safety profile (readOnly, idempotent, non-destructive, not open-world), but the description adds substantial behavioral detail beyond that: zero values may mask missing data with quality warnings, empty lists mean no cached matches not zero measurements, pagination semantics, date precedence rule, no cloud request or sync, requires configured local cache, and warning not to sync between pages. Rich and specific.

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?

Information-dense but somewhat sprawling: mixes routing rules, field lists, parameter rules, behavioral warnings, error semantics, and pagination advice across many semicolon-linked clauses. Front-loads the key distinction well, but could be tighter.

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?

Complete for a read-only paginated query with no output schema: return structure is described (data.summaries, data.data_quality, pagination shape), empty-result semantics are explained, sourcing (local cache vs cloud) is stated, and sibling alternatives are named. An agent has everything needed 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%, so parameters (date, start_date, end_date, limit, offset) are fully documented in the schema itself. The description's parameter guidance (date precedence, inclusive range, pagination next_offset behavior) is useful but substantially overlaps with schema descriptions, warranting baseline 3.

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?

Explicitly states it returns a multi-column daily activity table with named metrics (steps, distance_m, active_kcal, total_kcal, floors, active_minutes, data_quality). Directly distinguishes itself from query_metric_series ('not a single-metric trend') and notes sleep/workouts have separate 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?

Multiple explicit routing rules: choose this for daily activity table not single-metric trend, use query_metric_series for one metric across days/weeks/months, sleep and workouts have their own tools, use get_data_coverage to inspect availability, use sync_data to refresh. Covers when to use and when not to.

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

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

Annotations already declare read-only, non-destructive, idempotent, and closed-world behavior, but the description adds substantial context: local SQLite only, no cloud request or automatic sync, requires a configured local account/cache, returns cache-sourced JSON, and empty lists mean no cached matches. It also discloses pagination semantics and the warning not to sync between pages. There is no contradiction with annotations.

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 long but front-loaded, beginning with purpose, scope, and return shape before moving into caveats, alternatives, and pagination. Every sentence carries actionable information for selecting or invoking the tool correctly, and there is no redundant or filler 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?

The tool has five parameters, no output schema, and rich annotations. The description compensates by explaining return fields, pagination, cache semantics, empty-result meaning, local-only behavior, and alternatives for workout or coverage inspection. An agent has enough context to call the tool correctly and interpret its 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 description coverage is 100%, so the baseline is 3, but the description adds meaningful parameter context beyond the schema. It explains limit defaults, recommends smaller page/date windows for large datasets, notes that sample_type=workout may be empty on cloud adapters, and clarifies pagination fields such as next_offset being null at the end. The schema already covers most parameter semantics, so a 4 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 states a specific verb and resource: read timestamped heart-rate samples in bpm over an inclusive date range, with optional sample_type filtering. It clearly distinguishes this tool from query_workout_series by explaining when to use the latter for workout-window samples. An agent can identify the tool's scope 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?

The description gives explicit when-to-use guidance, including date-range filtering, optional sample_type, and pagination behavior. It names alternatives for unavailable or workout-specific data: query_workout_series with a workout_id, get_data_coverage to inspect availability, and sync_data to refresh with user consent. It also states when empty results should not be interpreted as zero measurements.

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/local, yet the description adds substantial non-obvious behavior: local SQLite with no cloud request or auto-sync, requires a configured account/cache, empty lists mean no cached matches rather than zero measurements, and pagination semantics (keep filters unchanged, don't sync between pages). This is well beyond what the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and metric list are front-loaded before the routing and behavioral details, and nearly every sentence carries operative information. It is dense and long, bordering on a wall of text for a fast scan, but the length is largely justified by seven parameters and non-trivial bucketing semantics.

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 present, the description fully compensates: it describes the return payload (data.metric, data.series of {date,value}, ascending, no gap-filling) plus status/source/generated_at and the pagination object with next_offset. An agent has everything needed to call and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: activity uses daily totals while weight uses the latest stored measurement per day, and it reinforces that aggregation applies only to week/month buckets. Marginal extra value over the already-complete 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 opens with a specific verb+resource+scope: build a dated trend for named metrics over an inclusive YYYY-MM-DD range. It enumerates the four supported metrics with units and explicitly names the siblings it is not (query_body_measurements, query_heart_rate, query_workout_series), so an agent can distinguish it without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: raw body readings go to query_body_measurements, heart-rate samples to query_heart_rate, single workouts to query_workout_series. It also states when to prefer alternative aggregations ('Prefer avg or latest for weight') and points to get_data_coverage/sync_data for availability gaps.

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/closed-world, and the description adds substantial context beyond them: local SQLite with no cloud request or auto sync, dependency on a configured account/cache, empty lists meaning no cached matches rather than zero measurements, and the definition of main sleep as the longest valid non-nap per wake 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?

Front-loaded with purpose and scope, and nearly every clause carries operational information. It is very dense and comma-spliced, which slightly hurts scannability, but there is little pure filler to cut.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully compensates by enumerating returned fields (sessions, count, main_sessions, metrics, data_quality, pagination) and their caveats. Prerequisites, coverage checks, and the null-score/missing-score distinction are all stated, so an agent has what it needs to call and interpret 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 baseline is 3, but the description adds non-schema semantics: include_naps affects only the raw list and never main-sleep selection, and pagination affects only sessions/count while main_sessions/metrics/quality describe the full range. It does not add date-format detail beyond the schema, which already carries pattern and examples.

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 (read) and two precise resources (sleep sessions, main-sleep summary), with the differing filter semantics for each (start-date vs local wake-date). It explicitly distinguishes itself from the sibling query_daily_activity, so an agent can route without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing ("Use this instead of query_daily_activity for sleep"), names get_data_coverage and sync_data with their conditions, and adds an operational rule ("keep ranges narrow", "avoid syncing between pages"). When-to-use and when-to-use-something-else are both covered.

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

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

With annotations already covering read-only, idempotent, non-destructive, and non-open-world behavior, the description adds substantial context beyond them: local SQLite query, no cloud request or automatic sync, configured account/cache requirement, empty-list semantics, pagination behavior, and output shape. It clearly discloses important operational and interpretation 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?

The description is front-loaded with the core purpose and then moves through behavior, output, pagination, and caveats in a clear order. It is information-dense and mostly earns its length, though several pagination and output details are repeated across multiple 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?

There is no output schema, so the description carries the burden of explaining return values and does so thoroughly: data.samples with timestamp and spo2_pct, data.count, status, source, generated_at, and pagination fields. It also covers prerequisites, empty-results meaning, and pagination continuity, leaving little an agent needs missing.

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

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

Schema description coverage is 100%, so the input schema already documents all four parameters, including limit, offset, start_date, and end_date. The description repeats the inclusive date range, limit default, and offset usage but adds little parameter-level meaning beyond what the schema already provides, so the baseline of 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 states a specific verb and resource: read stored blood oxygen saturation samples (spo2_pct, percent) over an inclusive date range. It distinguishes this from query_heart_rate by explicitly saying to use that tool for bpm rather than oxygen saturation. An agent can identify the tool 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?

It gives explicit routing guidance: use query_heart_rate for bpm, get_data_coverage to inspect availability, and sync_data to refresh with user consent. It also warns that missing records do not indicate normal oxygen levels and instructs keeping filters unchanged between pages.

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 cover the safety profile (read-only, idempotent, non-destructive); the description goes well beyond them by disclosing the local SQLite/cache execution model, no cloud request or auto-sync, the local-account prerequisite, the semantics of empty result sets, the status/source/generated_at envelope, and the 'keep filters unchanged between pages' constraint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, scope, then return shape, then constraints. Dense but every line carries information; a few items (limit default, offset usage) mildly duplicate the 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?

No output schema exists, yet the description specifies the returned envelope (status, source=cache, generated_at, data.samples fields, data.count, data.pagination with has_more/next_offset) and the caveat about the upstream device score not being clinical. Nothing needed to call or interpret 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?

Schema coverage is 100%, so start_date/end_date/level/limit/offset are already documented with formats, defaults, and bounds. The description adds only marginal context (limit defaults to 5000, offset for subsequent pages) that mostly restates the schema, so the baseline of 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 ('Read device stress samples') with the exact scope (inclusive YYYY-MM-DD range, optional level filter) and the return shape. Names the sibling it is not (query_sleep) so an agent can distinguish it immediately.

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?

Explicit routing: use query_sleep instead of inferring sleep from stress, use get_data_coverage to inspect availability, use sync_data to refresh with consent. Also gives a when-not condition ('empty lists mean no cached matches, not zero measurements') and a pagination discipline rule.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), but the description adds substantial context beyond them: retention (latest 500 completed plus active), scope exclusions (no CLI syncs), no cloud calls, and exactly what is withheld (credentials, raw errors, health records). A rare case of the text genuinely extending the 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?

Front-loaded with purpose first, then return shape, scope, retention, alternatives and pagination. Dense and mostly waste-free, though the sheer number of clauses packed into a single block makes it heavier than necessary.

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?

No output schema exists, but the description explains the return structure (data.jobs, data.pagination, next_offset null at end) and the empty-jobs meaning, so an agent has everything needed to call and interpret 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 defines limit/offset fully, making 3 the baseline. The description adds pagination semantics not in the schema: next_offset is null at the end, and the guidance to keep filters unchanged while paging, which improves correct offset reuse.

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 this account's MCP sync jobs') plus scope (newest first, from persistent local SQLite), which clearly distinguishes it from siblings like get_sync_status and cancel_sync. An agent can identify the tool 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 the alternatives and their conditions: 'Use get_sync_status for one ID and cancel_sync for a live background job.' It also clarifies what counts (foreground/background since install, not CLI syncs) and how to page (keep filters unchanged, avoid syncing between pages).

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?

Goes well beyond the read-only/idempotent annotations: returns JSON with status, source=cache, generated_at, and pagination metadata; explains that empty lists mean no cached matches (not zero measurements); notes it requires a configured local account/cache and performs no cloud request or sync. This is exactly the extra behavioral context the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and generally dense with useful facts, but it is a long run-on block and repeats pagination/return guidance, so a little trimming would help. Nearly 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?

With no output schema present, the description fully carries the return-shape burden (data.workouts, count, data_quality, pagination fields) and the caching/account prerequisites. Nothing essential for calling 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics: 'min_duration is minutes and min_distance_km is kilometers (unlike output distance_m)' and 'filters combine with AND before pagination'. These clarify unit mismatches and filter combination logic beyond the per-field schema text.

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 recorded workouts') plus its range scoping, and explicitly distinguishes itself from the sibling query_workout_series ('this tool returns session summaries, not samples'). An agent can tell exactly what this returns 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?

Names alternatives and the conditions selecting them: query_workout_series for heart-rate curves via a returned workout_id, get_data_coverage to inspect availability, sync_data to refresh with consent. It also gives operational guidance ('keep filters unchanged and avoid syncing between pages'), which is explicit when/how-to-use advice.

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, but the description adds substantial context beyond them: local SQLite only, no cloud request or automatic sync, requires a configured local account/cache, error status for unknown workout IDs, and the important caveat that empty lists mean no cached matches rather than zero measurements. The downsampling/clamping behavior and the 500-point hard cap are also disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose in the first sentence, then layers contract, semantics, and caveats. It is dense and long, but nearly every clause carries operational information; a few items (contract string, source=cache) are borderline overhead.

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, yet the description enumerates the returned fields (t offsets, bpm, downsampled/source_points/returned_points/method, summary statistics) and the envelope (status, source, generated_at, data). For a read tool with five parameters and no output schema, nothing material 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 meaning the schema does not: the resolution/max_points interaction ('resolution defaults to 60 seconds and increases to respect max_points') and the cross-activity comparability rationale for reference_max_hr. These go beyond the per-field schema text.

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 ('Read an auto-downsampled heart-rate curve for one workout_id') and scopes it to a single workout rather than a date range, which distinguishes it from query_heart_rate and query_metric_series. It also names the contract identifier, so an agent can identify the exact operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'For raw date-range samples use query_heart_rate', 'Use get_data_coverage to inspect availability or sync_data to refresh with user consent'. It also gives the conditional rule for reference_max_hr (pass the same value for comparable time_in_zone, omit otherwise), which is real when-to-use 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?

Beyond annotations (readOnlyHint false, destructiveHint false), the description discloses detailed behavior: it may authenticate/rotate credentials, requires local CLI setup and user authorization, runs only one sync at a time, handles partial results, and clarifies that force_full_sync does not erase the database. This significantly exceeds the sparse annotation information.

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 long but every sentence serves a purpose. It front-loads the core purpose and then systematically covers prerequisites, parameter nuances, execution behavior, and alternative tools. No redundant or filler sentences; each adds necessary context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 parameters, no output schema), the description covers all aspects needed for correct invocation: prerequisites, authorization, date handling, sync semantics, background modes, and result interpretation. It also warns about partial results and retry considerations, making it fully 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% and the description adds substantial meaning: omitted data_types selects all supported types, empty list invalid, date ranges are inclusive, start_date omitted resumes watermark, force_full_sync ignores watermark but not date range, background behavior differences. It enriches the schema definitions with usage semantics.

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 tool downloads Mi Fitness datasets into local SQLite, writes records and sync watermarks, and explicitly notes it does not modify cloud health records. It distinguishes itself from sibling query tools by naming them as cached alternatives. The verb 'download' and resource 'datasets' are specific.

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 explicitly states when to use the tool (when a refresh is needed) and when not to (use cached query tools instead). It also mentions polling with get_sync_status for background syncs, providing clear routing to alternatives.

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