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

Annotations already establish that this is a read-only, non-destructive, open-world operation. The description adds meaningful caveats: missing or offline data is treated as unknown, raw water_level has no documented unit, and cleaning/water quality are out of scope. Those details materially help an agent interpret results and avoid overclaiming.

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

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

Three short sentences, front-loaded with what the tool does, followed by caveats and exclusions. Every sentence contributes relevant information with no wasted 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?

For a simple one-parameter read-only tool with no output schema, the description supplies the important reliability and scope caveats an agent needs to avoid misinterpreting water status. It could say more about return shape or alias resolution, but the core invocation context is covered.

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 0%, so the description must carry the burden for the single 'target' parameter. It adds that the target should be 'one confirmed target alias', which is useful, but it does not explain alias format, where confirmed aliases come from, or what 'confirmed' means. This is minimally viable rather than complete.

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 water status') and adds scope boundaries ('does not detect cleaning or water quality'). It is clear what the tool does, though it does not explicitly differentiate itself from sibling status tools such as get_device_status.

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 a prerequisite ('one confirmed target alias') and a negative scope ('does not detect cleaning or water quality'), which helps an agent avoid using it for those purposes. It does not name alternative tools or explain when to prefer them, so it falls short of full when/when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context that this is an inspection before mapping and that it makes no device change, but it does not discuss auth requirements, rate limits, or richer return-shape details.

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 three tight sentences with the action and return categories front-loaded, followed by the identifier rule and the no-change constraint. Every sentence carries useful information and there is no redundant or filler language.

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 status tool with no output schema, the description supplies the main return categories, identifier-selection rule, and mutation-safety statement. It is nearly complete, with the main remaining gap being explicit selection guidance versus sibling status and discovery tools.

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 0% schema description coverage, the description carries the burden and does so reasonably: it explains that exactly one of target or device_id must be supplied, that target is a confirmed alias, and that device_id can come from discovery. It does not fully define alias format or device_id format, but it adds substantial meaning beyond the bare string/null 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 clearly states a read operation and enumerates what is read: current model, controls, readings, and observation time. It is specific enough to distinguish a device-status read from mutation siblings, though it does not explicitly name or contrast with related status/list tools such as get_setup_status or list_devices.

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 useful usage constraints for identifiers: supply exactly one of target or device_id, with target described as a confirmed alias and device_id sourced from discovery. However, it does not say when to prefer this tool over siblings like get_setup_status, list_devices, or check_water_status, so broader tool-selection guidance 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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description does add real value beyond that: it discloses that inbox delivery is local polling rather than a push or audible alarm, which prevents an agent from assuming real-time alerting. It does not describe freshness/staleness of the heartbeat data or error formatting, leaving a gap for a diagnostic tool.

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

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

Two compact sentences with the returned data front-loaded and the delivery caveat placed as a trailing clarification. No filler, though the first sentence is a dense list that could be marginally more scannable.

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, so the description must carry the burden of indicating what comes back, which it does at a category level (heartbeat, errors, per-occurrence outcomes, suppression, inbox). With zero parameters and read-only annotations, this is nearly sufficient, but it lacks detail on data freshness and the shape of occurrence 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 tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The description instead characterizes the scope of what is returned, which is the only parameter-like semantics available 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 (Read) and enumerates the exact resources surfaced: runner heartbeat/errors, per-occurrence outcomes, automatic-write suppression, and the local notification inbox. This is distinguishable from sibling status tools (get_setup_status, get_device_status, check_water_status), though terms like 'runner heartbeat' and 'automatic-write suppression' are domain jargon an agent may not fully resolve.

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

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

There is no guidance on when to call this versus the many sibling status tools (get_setup_status, get_device_status, list_routines) and no stated preconditions. The only qualifying sentence concerns notification delivery mechanics, not tool selection.

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, destructiveHint=false, and openWorldHint=true. The description adds a valuable security guarantee beyond those annotations: "Never returns a token," which tells the agent secrets are excluded from output. It stops short of saying whether vault/runner checks hit external services despite openWorldHint.

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

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

Two short sentences, zero filler, and the inspected areas are front-loaded ahead of the security caveat.

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 parameters and no output schema, the description carries the burden of describing what comes back, and listing the four inspected areas does that reasonably well. A brief note on the shape of the result (e.g. per-area status flags) would make it 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify on the input side.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a concrete verb ("Inspect") and enumerates the four things examined: vault availability, mappings, pending identification recovery, and runner status. It clearly distinguishes this diagnostic tool from the device-control siblings, though it never names 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 enumerated content implies when to call it (setup/diagnostic checks), but there is no explicit guidance such as when to use this rather than get_device_status or list_devices, and no prerequisites or exclusions are stated.

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

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

Annotations already establish that this is a read-only, non-destructive, open-world operation. The description adds useful behavioral context beyond annotations: account scoping, the authoritative nature of nullable metrics and returned dates, and the caveat not to infer a bed side.

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: purpose first, then parameter formats, then default date behavior, then an important data caveat. Every sentence provides actionable information 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?

For a low-complexity read tool with three optional parameters and no output schema, the description covers parameter semantics and key behavioral caveats well. It could say more about what the reports contain or what account scope requires, but it is largely complete for correct 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 carries the full parameter burden. It specifies the start_date format (YYYY-MM-DD), days_back range (0–6), time_zone format (IANA zone), and the default behavior when the date is omitted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a clear verb and resource: reading account-scoped provider reports. It does not explicitly say these are sleep reports or distinguish itself from sibling device/routine tools, but the tool name and report scope make the purpose reasonably clear.

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 the default date behavior when start_date is omitted, but it gives no guidance on when to use this tool versus sibling tools or any alternative reporting tools. Usage is only implied from the read operation and account scope.

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 destructiveHint=true and openWorldHint=true, and the description earns credit beyond them by disclosing that originals are restored by default, that manual changes block restoration, and that keep/force each require specific confirmations. It stops short of describing failure modes or what status actually returns.

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?

Roughly sixty words with no filler, and the most consequential constraint (originals restored by default) is front-loaded. The telegraphic sentence fragments strain readability slightly, but every clause carries operational information.

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

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

For a five-parameter, destructive, open-world tool with no output schema, the description covers lifecycle, safety gates, and parameter prerequisites well. It leaves gaps on return values and error behavior, but the risky parts an agent must get right are documented.

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 0% and the action field has no enum, so the description must carry the load; it does by enumerating actions (begin/status/finish/cancel/recover) and explaining tests, confirmed, keep, and force. Some nuance remains ambiguous, such as whether tests is only meaningful for begin.

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 'Two-controller identification', which gives a specific resource and implies the identify verb, but never plainly says what identification accomplishes or how it differs from siblings like get_device_status or list_devices. The body dives straight into the begin/status/finish protocol, leaving the overall goal implicit.

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 action space is laid out with conditions: begin requires agreed tests and confirmed=true, status reads recovery, finish keep=true confirmed=true keeps settings, and force only after fresh agreement. It also routes the agent onward ('Save confirmed side mapping separately'), though it names no sibling tool explicitly.

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=true, and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations: it discloses the fields returned and warns about a domain caveat that could cause incorrect assumptions about bed sides.

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: it first states what is discovered, then gives two important caveats. Every sentence adds value with no wasteful 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?

For a no-parameter, read-only listing tool with no output schema, the description is complete enough. It explains the returned information, states the scope as claimed devices, and supplies a critical operational caveat about not inferring bed sides.

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 has zero parameters, so there is no parameter semantics to explain. The description does not need to compensate for schema gaps, and a baseline 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: discovering claimed device IDs, names, and attachments. It is clearly a listing/discovery tool, though it does not explicitly distinguish itself from the sibling identify_devices.

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 useful usage context by warning that names and ordering do not establish bed sides, and it directs the agent to read each selected device's status to learn its model. It lacks an explicit when-not or named alternative sibling, but the workflow guidance is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the contents of the result set — paused definitions and routines with targets needing repair — which tells the agent it is a full raw inventory rather than a filtered or health-checked view. No guidance on ordering or size, but that is minor for a zero-parameter read.

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

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

Two sentences, zero waste, with the resource and its scope front-loaded before the alternative-tool routing. Every clause 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 and no parameters, the description sufficiently explains what the tool returns and when to prefer a sibling. The only gap is the absence of any note on result size or ordering, which is not essential for a parameterless read.

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 schema applies. The description does not misrepresent any input.

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 ('List') and resource ('canonical local alarms and routines'), and adds scope detail about paused definitions and targets needing repair. It names get_routine_status as the contrasting sibling, so an agent can separate listing from status/history, though it doesn't differentiate from other list_* siblings like list_devices.

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_routine_status for execution and inbox history,' which gives a clear when-to-use-elsewhere condition. It doesn't spell out when-not-to-use this tool in other cases (e.g., vs. update_routine), but the primary alternative is 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?

Annotations already declare non-read-only and destructive; the description adds real value beyond them by stating it acts immediately, applies the routine's saved power choice, and overrides a paused schedule while requiring explicit user intent. It omits side effects on the physical device and error behavior for an unknown routine_id.

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 front-loaded sentences: action first, then the intent/paused-schedule constraint. No filler, though the second sentence is slightly dense and could be split for scanning.

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

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

For a one-parameter mutating tool with destructive/open-world hints and no output schema, the description covers what it changes, where the values come from, and the intent requirement. Remaining gaps are minor (return values, failure modes).

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 single parameter has 0% schema description coverage, so the description carries the burden. It explains that routine_id refers to a saved routine whose target/temperature/power are applied, but does not say whether the ID is a string handle, name, or where to obtain it (e.g., from list_routines).

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 ('Run a saved temperature routine immediately by routine_id') and clarifies what values are applied (target, temperature, saved power choice). This clearly separates it from list_routines/update_routine, though those siblings are not named explicitly.

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

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

Gives clear usage context with 'immediately' and 'requires user intent... even if the recurring schedule is paused', which tells the agent this is an intent-driven action and not the scheduler. No explicit exclusions or named alternatives, keeping it short of a 5.

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

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

Annotations already mark this as destructive and non-read-only; the description usefully adds that it clears explicit/manual-change suppression and specifically does not replay missed or already claimed occurrences. That is meaningful behavioral context beyond the annotations, though it does not address permissions or reversibility explicitly.

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

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

Two tight sentences, with the core action and agreement condition front-loaded and no redundant 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?

For a destructive two-parameter tool with no output schema and no schema descriptions, the description provides useful scope and non-replay behavior. It remains incomplete on what `target` should contain and what a successful call returns or changes beyond the suppression flag.

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 explains `confirmed=true` as reflecting user agreement, but leaves `target` vague despite being the required 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 effect: clearing the target's explicit/manual-change suppression after user agreement. It is clear enough to distinguish from routine-listing or setup-status siblings, but it does not name the relevant sibling alternatives.

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 `confirmed=true` parenthetical implies the tool should be used after user agreement, and the non-replay sentence sets a boundary. However, there is no explicit guidance on when to choose this over related routine/update tools, nor any named alternative.

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 flag this as destructive and open-world, but the description adds crucial context: it replaces the entire mapping, an empty list deletes all mappings, and confirmed must only be set after user agreement. It also discloses prerequisite discovery of IDs and alias uniqueness.

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, compact, and every sentence adds necessary meaning. There is no redundant restatement of the tool name or schema boilerplate.

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 destructive mutation with no output schema and generic param schema, the description covers all behaviorally relevant points: readback, full replacement, retention rules, empty-list deletion, ID discovery, alias uniqueness, and confirmation timing.

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 0% schema description coverage and generic row items, the description carries the burden and does so well: it explains that rows contain id, alias, optional group, and optional position, that all mappings to retain must be included, and how confirmed is meant to be used.

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 ("Replace") and resource ("entire device mapping"), and clarifies that this is a full replacement rather than a partial update. It is distinct from every listed sibling, none of which perform mapping replacement.

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 operational conditions: read the mapping back to the user first, include every mapping to retain, use an empty list to remove all, and set confirmed only after agreement. These are clear when/how constraints rather than vague 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 this is not read-only, is open-world, and has a destructive hint. The description adds useful behavioral context: target temperature is preserved, a connected Dock Pro is required, and standby is not a mains disconnect. That clarification is valuable beyond the annotations, though error behavior is not described.

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 three tight sentences with the main action front-loaded, followed by the precondition and an important behavioral caveat. Every sentence contributes useful information.

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

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

For a simple two-parameter tool with no output schema, the description covers the action, parameter meaning, prerequisite, and a key caveat about standby. The main remaining gap is lack of detail about how target should be identified.

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 clearly defines the on parameter as active (true) or thermal standby (false) and indicates target is a confirmed target. However, it does not specify the target format or accepted values beyond that.

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: setting one confirmed target to active or thermal standby. It also distinguishes the action from sibling set_temperature by noting that target temperature is preserved. An agent can understand the operation 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 clear usage context: use this to switch a confirmed target between active and standby, and it requires a connected Dock Pro. It does not explicitly name alternatives or when not to use it, but the preserving-temperature note helps differentiate it from temperature-setting tools.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the mutation profile is covered. The description adds valuable beyond-annotation context: it does not turn power on, only one confirmed target is affected, and 'Accepted is not physically ready' warns of eventual consistency between acknowledgement and physical change. It does not discuss reversibility or permission requirements.

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

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

Four tight sentences with zero waste. The primary action and scope are front-loaded, followed by invocation forms, then the two behavioral caveats.

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 destructive, no-output-schema mutation tool whose annotations cover safety, the description supplies enough to call it correctly: value ranges, unit rules, mode exclusivity, and the acceptance-vs-physical-readiness caveat. Remaining gap is how 'target' must be identified and confirmed before calling.

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 the parameter burden, and it largely does: F range 55–115 integer, C range 13–48 in 0.5 steps, enumerated mode values maximum_cooling/maximum_heating, and mutual exclusivity of mode vs value/unit. The 'target' parameter is only described as a 'confirmed target' with no format or confirmation mechanism, leaving one 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?

States a specific verb and resource ('Change ... temperature') with a scope constraint ('only one confirmed target') and explicitly differentiates from the power path ('Does not turn power on'). An agent can tell this apart from set_power without opening either schema.

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

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

Gives explicit invocation shapes: value+unit for a numeric setpoint, or an 'explicitly requested' maximum_cooling/maximum_heating mode with no value/unit. Also states the exclusion that it does not power the device on. It stops short of naming which sibling to call when the user actually wants power or mode changes outside these two modes.

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 a non-read-only, open-world, destructive operation, and the description adds meaningful context beyond them: the exact field-level blast radius and the existence of a confirmation requirement for the target. It does not explain reversibility or what confirmation looks like, and the narrow 'display unit' framing sits somewhat awkwardly with destructiveHint=true without reconciling it.

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, no filler, with the positive scope stated first and the exclusion list immediately after. Every clause carries information an agent needs before calling.

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 three-parameter mutation tool with no output schema, the definition covers what changes, what doesn't, value formats, and the confirmation precondition. It omits any indication of success/failure signal or whether omitted fields are preserved, leaving a small gap.

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

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

Schema description coverage is 0%, so the description carries the burden and does so well: it specifies the accepted values for display_unit (f/c) and the format for time_zone (IANA) and clarifies that target must be a confirmed device. It remains silent on defaults/null behavior, which the schema only hints at.

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 mutation verb ('Change') and precisely bounds the resource to display_unit and device time_zone on a confirmed target. The explicit statement that it does not change power or target temperature cleanly separates it from siblings set_power, set_temperature, and update_routine.

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?

'For a confirmed target' establishes a prerequisite, and the negative scope ('Does not change power, target temperature, routine timezone, or reporting timezone') implicitly routes the agent to set_power, set_temperature, or update_routine for those needs. It stops short of naming those alternatives explicitly, so it is a strong 4 rather than a 5.

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

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

Annotations already declare this as destructive and non-read-only, and the description adds critical context beyond them: deletion via delete_id, confirmation after user agreement, pause semantics, inbox testing requirements, and the explicit statement that samples are never implicit consent. These details substantially improve safe invocation.

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 front-loaded and every sentence carries useful constraints. It would read more clearly with explicit structure rather than one long paragraph with inline enumerations, but it is not padded or repetitive.

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 destructive, complex routine mutation with no output schema and sparse annotations, the description covers most necessary behavior and parameter constraints. It does not clarify mutual exclusivity between row and delete_id, precedence if both are supplied, or expected success/failure outcomes, leaving a few gaps.

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% and the row parameter is an unconstrained object, so the description must carry the parameter semantics. It does this thoroughly, documenting row fields, id format, action enum values, time formats, timezone, weekday/date options, temperature constraints, window/reminder ranges, overrides, and the meaning of confirmed, alarm, and delete_id.

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 operation: upsert a complete routine row or delete via delete_id. It clearly identifies the resource (routine row) and distinguishes mutation behavior from read-oriented siblings such as list_routines and get_routine_status.

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 clear operational guidance: confirmed=true after user agreement, delete_id for deletion, enabled=false to pause, alarm=true for alarms.md, and inbox testing before enabling. It does not explicitly route agents to alternative sibling tools for inspection or manual actions, so it falls short of full when/when-not/alternatives coverage.

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