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

Annotations only indicate destructive, non-read-only, open-world behavior. The description adds critical detail: the deletion is verified by read-back, unknown write outcomes are reported explicitly, and a transport acknowledgment alone is not success. This goes well beyond the 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?

Three tightly packed sentences with no filler. The most important constraints—targeted deletion, read-back verification, and item_id sourcing—are front-loaded and every sentence adds value.

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 targeted delete operation, the description covers required parameter sourcing, scope safety, verification behavior, and timeout bounds. The output schema covers return values. The only mild gap is no explicit guidance on the optional timezone parameter, but it is likely unnecessary for item_id-based deletion.

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 0%, so the description must compensate. It does explain item_id provenance via get_band_schedule and gives a timeout_seconds range (5..90), but it does not describe timezone semantics or how kind relates to item_id beyond the schema's enum values.

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 a specific verb and resource: 'Delete only the identified band alarm/reminder' and adds a verification step ('verify its absence by read-back'). This clearly distinguishes it from sibling setters and getters like set_band_alarm, set_band_reminder, and get_band_schedule.

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 instructs the agent to obtain item_id from get_band_schedule and warns that other entries remain unchanged, which prevents misuse as a bulk-clear operation. It does not explicitly say 'use set_band_alarm to create instead,' but the deletion context is clear enough.

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 the annotations, the description discloses automatic bounded reconnection, local-wall-clock versus UTC/timezone conversion, the 5..90 timeout range, the no-invented-data guarantee, and the use of a read to reconcile unknown writes. readOnlyHint=false is not contradicted by the described automatic reconnect side effect.

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 front-loaded, opening with the core purpose and then adding only high-value operational details. Every sentence covers a distinct concern: scope, connectivity, timezone, timeout, failure behavior, and reconciliation.

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's complexity (device reconnects, timezone conversion, optional parameters) is fully addressed, and the output schema covers return values. An agent receives enough information to call the tool correctly, including defaults and failure-mode guarantees.

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 no property descriptions in the schema, the description compensates by specifying timezone default ('server setting'), timezone conversion behavior, and timeout bounds (5..90). 'kind' is less explained, but the enum values are self-explanatory alongside the phrase 'alarms/reminders.'

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 uses a specific verb ('Read') and names the resource ('band alarms/reminders') plus what is returned ('IDs, repeat rules and device capacity'). This clearly distinguishes it from the write/delete sibling tools (set_band_alarm, set_band_reminder, delete_band_schedule).

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 an explicit use case: 'Read again to reconcile an earlier write whose outcome was unknown,' which tells the agent when this read is especially valuable. It does not explicitly name alternatives or when-not-to-use, but the context is unambiguous given the sibling set.

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 adds significant behavioral detail beyond the annotations: automatic reconnect behavior, the fact that cached reads avoid phone contact, unknown fields being null, numeric bounds for max_age_seconds and timeout_seconds, and no app UI interaction. These are exactly the kind of side-effect and connectivity behaviors an agent needs to know.

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 front-loaded. The first sentence names the resource, the second and third add behavioral constraints, and the final sentence gives parameter bounds. There is no redundant or filler wording.

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 description covers tool scope, read-only monitoring configuration, remote/cached behavior, null handling, numeric parameter ranges, and UI interaction. An output schema exists, so return-value details are not needed. The only notable gap is the underspecified semantics of the freshness enum values.

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 0%, so the description must carry parameter meaning. It provides ranges for max_age_seconds (1..86400) and timeout_seconds (10..90), and the cached/remote distinction clarifies the freshness concept partially. However, it does not define the difference between prefer_fresh and require_fresh, nor how max_age_seconds interacts with freshness.

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 enumerates the content of the tool: band connection, battery, charging, and heart-rate/SpO2/stress monitoring settings. The verb 'get' is present in the tool name)Skip, and the resource scope is concrete. It does not explicitly contrast with siblings such as get_health_status or get_current_state, but the listed fields are specific enough to differentiate them.

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 clear operational context: remote reads reconnect automatically within the timeout, cached reads never contact the phone, and no app UI interaction occurs. This guides an agent on when to choose cached versus remote freshness. It stops short of explicitly naming alternatives or stating when not to use this tool.

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 goes well beyond the sparse annotations by disclosing caching behavior (60-second reuse), freshness failure semantics, and the fact that no app UI interaction occurs. This gives agents a clear model of side effects and timing.

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 packs useful behavioral details into a few lines. The opening is a fragment ('Recent recorded heart rate...') and could be cleaned up, but overall it is front-loaded and efficient.

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?

An output schema exists, so return format is not needed. The description covers freshness modes, caching, and parameter ranges, but the missing definitions for wait_seconds and max_age_seconds leave an agent uncertain about how to set them effectively. For a tool with 3 optional params, this is incomplete.

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 0%, so the description must fully explain parameters. It thoroughly explains the freshness enum, but only gives numeric ranges for wait_seconds and max_age_seconds without defining what they actually control (e.g., wait time, freshness threshold). This is a notable gap.

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 lists the data returned (heart rate, steps, historical sleep/workouts, battery via Gadgetbridge) and this differentiates it from get_health_status, get_daily_report, and query_health. It lacks an explicit verb like 'retrieves' but the resource and scope are 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?

The freshness modes are explained with concrete behavior (cached returns immediately, prefer_fresh attempts a pull, require_fresh returns freshness_unmet), giving agents clear context on how to choose modes. It also states 'No app UI interaction', but does not name alternatives or explicitly say when not to use this tool versus siblings.

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

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

Annotations already declare readOnlyHint and destructiveHint, and the description adds meaningful behavioral detail: results are cached, sleep is assigned to the waking day, missing days are excluded, and timezone has an effective default. This goes beyond the annotations without contradicting them.

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 front-loaded: core definition first, followed by inclusions, usage guidance, and timezone semantics. Each sentence adds distinct value with no filler or repetition.

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 an output schema and read-only annotations covering return values and safety, the description supplies the remaining context: caching, sleep-day assignment, missing-day handling, timezone, and sync prerequisite. Minor gaps like the precise meaning of 'sample coverage' and the exact freshness rule prevent a 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 description coverage is 0%, so the description carries the full burden for parameters. It compensates well: date is described as YYYY-MM-DD, timezone is described as an IANA name with default Asia/Shanghai, and compare_days is conveyed through 'optional preceding-day comparisons (missing days excluded).' An agent can correctly populate all parameters from the description.

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 identifies the tool as a cached natural-day summary, specifies the date format, and highlights the sleep-assignment nuance, which makes its purpose understandable and distinct from sibling health/status tools. It lacks an explicit verb in the description, relying partly on the tool name, so it stops short of a 5.

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

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

The description gives explicit usage context: 'For a morning digest, query yesterday's activity and today's waking sleep separately' and 'Call sync_health first if needed.' It also explains optional preceding-day comparisons and missing-day exclusion. It does not explicitly name when-not-to-use alternatives, so it is not 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?

The description adds substantial behavioral detail beyond the sparse annotations: each observation has its own age/source, current sleep_state is a classification rather than a historical session, cached uses local data, remote reads reconnect, and the tool does not start measurements or change settings. This is strong disclosure of behavior and side effects.

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 front-loads the high-level resource before adding technical detail. It wastes few words)Skip, though the first sentence is a noun fragment and some concepts are packed densely.

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 output schema covers return values, the description provides most needed operational context: freshness modes, age caps, timeout ranges, and side-effect absence. The main gaps are the unexplained prefer_fresh/require_fresh semantics and lack of explicit sibling routing, but overall an agent can still call this tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It adds useful semantics for max_age_seconds (1..86400, device-state age capped at 120s) and timeout_seconds (10..90), and explains the cached freshness value. However, prefer_fresh and require_fresh are left unexplained, leaving a meaningful gap for a central parameter.

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 enumerates the data categories returned (HR, steps, sleep/workout history, wearing, sleep/activity state), so an agent knows what resource this tool exposes. However, it lacks an explicit verb and does not name sibling tools like get_current_state or query_health, leaving differentiation to inference.

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

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

It provides useful context: cached means local data, remote reads reconnect automatically, and this tool does not start a new measurement. This implicitly steers users needing a new measurement to measure_heart_rate, but it never explicitly states when to use get_health_status instead of get_current_state, query_health, or get_daily_report.

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 goes far beyond the annotations by disclosing behavioral nuances: it uses authenticated Bluetooth, reports received_at and start/stop acknowledgments and cleanup errors, may return no reading if the band is not worn, has a 30-90s timeout, always attempts to stop, and requires checking stop_confirmed rather than assuming success. This is rich, non-obvious operational guidance.

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 action, then packs every subsequent sentence with relevant operational detail. Nothing feels redundant or decorative, and the format is scannable despite its length.

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 tool with one optional parameter and an existing output schema, the description is complete enough to call correctly: it covers prerequisites, failure conditions, timeout bounds, return fields, and stop-confirmation expectations. The agent knows what to expect and how to handle ambiguous outcomes.

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 only provides a default value for timeout_seconds with no description. The description compensates by stating the valid timeout range (30..90s) and implying that timeout controls how long to wait for the reading. It does not explicitly map the parameter name to its semantics, but it adds meaning the schema lacks.

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: 'Request one live heart-rate reading from the connected, worn Mi Band, then stop.' It also distinguishes itself from historical/higher-level queries by clarifying it uses the Bluetooth connection rather than the historical database, and notes how current-state queries versus daily aggregates relate to its output.

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 clear context: it is for a single live reading, requires Xiaomi Health running and the band connected, and is not a historical database query. It also explains that current-state queries prefer a newer successful live reading while daily aggregates use recorded history, which routes the agent semantically. However, it does not explicitly name sibling tools or state 'use X instead' for specific 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?

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is clear. The description adds useful behavioral context: 'Bounded cached detail' indicates a bounded and cached dataset, 'Missing buckets remain missing' discloses handling of gaps, and 'No arbitrary SQL' restricts query capability. It also explains the aggregation_minutes range. This goes beyond the annotations and covers key runtime behavior.

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

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

The description is a single, dense paragraph that front-loads the core idea ('Bounded cached detail') and then presents usage rules in a structured, scannable way using semicolons and line breaks. Every sentence adds value: time semantics, defaults, limits, pagination, session selection, metric options, backend note, and aggregation range. 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?

With 9 parameters and an output schema present, the description covers the critical usage aspects: time ranges, limits, session selection, metric flexibility, aggregation bounds, and the caching caveat. It references a device profile for extended metrics. It does not explicitly explain timezone format or offset behavior, but given the mention of offset-aware ISO timestamps and the existence of an output schema, the description is sufficiently complete for safe invocation.

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 0%, so the description must compensate. It does so by explaining start/end semantics (inclusive/exclusive, ISO timestamps, optional defaults), limit and pagination, metric examples ('heart_rate.bpm (default), steps, calories, distance'), and aggregation_minutes range. It mentions timezone indirectly via 'offset-aware ISO timestamps' but does not detail the timezone parameter or offset parameter. Overall, it adds substantial meaning beyond the raw 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 'Bounded cached detail: metric buckets, sleep sessions, or workouts.' This clearly names the resource (bounded cached health data) and the specific data kinds, distinguishing it from live measurement tools like measure_heart_rate and daily summaries like get_daily_report. The verb 'query' is implied and the scope is explicit.

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 usage conditions: 'Supply both start (inclusive) and end (exclusive) as offset-aware ISO timestamps, or neither for the last 24 hours (timeseries) / 30 days (sessions).' It also explains pagination with 'limit 1..500; use returned pagination for more' and session selection via 'Session IDs from summaries.' It does not name specific alternatives but the conditions make the intended usage clear. A minor gap is not explicitly stating when not to use the tool, but it is effectively 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?

The description adds substantial behavioral detail beyond the annotations: it preserves other alarms, verifies by read-back, reconciles lost writes without blindly retrying, and clarifies that timezone labels the wall clock without changing the band's timezone. This is exactly the kind of context an agent needs beyond readOnly/destructive hints.

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 dense but every sentence carries necessary operational detail. It is front-loaded with the main action, then systematically covers time, weekdays, alarm_id, timezone, write reconciliation, and timeout. 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?

Given six parameters, no schema descriptions, and only basic annotations, this description provides complete guidance for calling the tool correctly. It covers create vs. update, value semantics, edge cases like one-time vs. daily alarms, and failure handling. An output schema exists, so return-value details are not required.

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 0%, but the description compensates fully: it explains time format (HH:MM), weekday numbering (ISO 1=Monday..7=Sunday), the meanings of [] and all seven days, the role of alarm_id, timezone semantics, and the timeout range 5..90. This is strong semantic guidance for every meaningful parameter.

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 action ('Create or update one band alarm') with a clear resource and scope. It also distinguishes itself from siblings like set_band_reminder by focusing on band alarms, and from delete_band_schedule by covering create/update rather than deletion.

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 clearly explains when to create vs. update: omit alarm_id to create, provide a listed ID to update. It gives context on preserving other alarms and using complete desired values, though it does not explicitly name alternative tools or when not to use this one.

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 indicating destructive/write behavior, the description adds meaningful behavioral detail: created updates verify stored fields, unrelated entries are preserved, recurrence follows UTC and does not track DST, and timeout_seconds is range-limited to 5..90. No contradiction with annotations 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?

The description is compact and front-loaded with the core purpose, followed by parameter details and caveats. The text is slightly choppy in places, but every sentence contributes useful information without 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?

The description covers key operational caveats, timeout bounds, and create/update semantics, which is good for a tool with six parameters. However, it does not clearly define the repeat or timezone parameters, leaving a meaningful gap in a callable description.

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 0%, so the description must compensate. It does explain 'at', 'title', 'reminder_id', and 'timeout_seconds', but repeat and timezone are only indirectly addressed through the recurrence/UTC caveat. The meaning of the timezone parameter in particular remains underspecified.

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 action: 'Create or update one wrist reminder, then verify its actual stored fields,' naming both the verb and the resource. It is distinct from the sibling set_band_alarm by referring to a wrist reminder, but it does not explicitly contrast itself with that sibling.

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 provides concrete usage guidance: omit reminder_id to create, use a listed ID to update, supply all desired fields, and inspect get_band_schedule on an unknown result before retrying. It does not explicitly mention when to choose this tool over set_band_alarm, so it stops short of full alternative routing.

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

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

Annotations only say the tool is not read-only and not destructive, leaving much behavioral detail uncovered. The description adds substantial value: backend-specific sync over ADB/SSH, refresh_app=true waiting for completion, no new physiological measurement, one-time transport configuration, offline cached queries, and a single-writer concurrency 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?

The description is compact and front-loaded, with the core purpose stated first and every subsequent sentence adding high-value operational details like transport mechanics, concurrency, offline behavior, and timeout bounds. There is no filler or redundant restatement of the tool name.

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

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

For a two-parameter sync command with transport-dependent behavior and no required inputs, this covers all operational essentials: refresh semantics, backend differences, persistence of configuration, concurrency, timeout range, and the reported record-time advancement. Since an output schema exists, return-value details do not need to be repeated in prose.

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 0%, so the description carries the burden and mostly meets it: refresh_app=true's effect is spelled out for both transports, and timeout_seconds is bounded to 1..180, adding information absent from the schema. The only small gap is not explicitly describing the refresh_app=false default path, though it is inferable.

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 precise verb and resource: it updates the selected local cache and reports record-time advancement. It also clarifies that no screen interaction or new physiological measurement is requested, which distinguishes it from measurement-oriented siblings, though it does not explicitly name an alternative 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 explains when refresh_app=true triggers synchronization and notes transport setup, concurrent writer, and offline cache behavior, giving useful context. However, it never explicitly states when to use this tool over query_health or get_health_status, or when to skip it; the usage guidance remains implied rather than directly stated.

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